Um estorno que só pode voltar de onde o dinheiro veio.
O cliente reclama no chat de suporte. O agente encontra o endToEndId do pagamento e pede à CodeSpar para devolver o Pix: o dinheiro volta para quem pagou, e a devolução nunca pode passar do que resta a devolver daquele pagamento. Cada devolução leva uma chave de idempotência, então uma nova tentativa é a mesma devolução. A devolução não é conferida contra um mandato nem um teto; o pagamento original é o seu limite. Emitir uma nota de crédito e consultar o pedido no seu ERP são a sua integração.
O estorno, a partir do chat.
Um exemplo com dados de demonstração: o cliente pede o estorno no chat de suporte; o agente encontra o pagamento Pix e pede à CodeSpar para devolvê-lo a quem pagou.
- A devolução volta para quem pagou, no mesmo rail
- Nunca mais do que resta a devolver do pagamento
- Não conferida contra um mandato nem um teto: o pagamento é o limite
A conversa é a parte fácil.
Estorno é onde o suporte encontra o dinheiro: o ticket espera alguém com acesso ao banco, a transferência manual não bate com o pagamento original, e depois ninguém sabe dizer o que foi devolvido.
Escalar cada estorno para quem tem o login do banco
O agente devolve o Pix pela API, com a própria chave de API
Uma transferência manual que não bate com o pagamento original
A devolução cita o endToEndId do pagamento e volta para quem pagou
Estornar duas vezes depois de um timeout
A chave de idempotência faz da nova tentativa a mesma devolução
Devolver mais do que foi pago
A devolução não passa do que resta a devolver do pagamento
Um estorno limitado pelo pagamento.
O agente chama POST /v1/consumers/{consumerId}/pix/devolutions com o end_to_end_id do pagamento, o valor em centavos e uma chave de idempotência; um GET na devolução lê o status. A devolução volta para quem pagou e é limitada pelo que resta a devolver daquele crédito. Ela não consome um mandato. Consultar o pedido, emitir uma nota de crédito e avisar o cliente são a sua integração.
O cliente pede o estorno
O endToEndId do pagamento
Pix de volta para quem pagou
Lido pelo id
O cliente, no chat
O ticket entra pelo seu canal de suporte. O agente encontra o pedido e o pagamento Pix nos seus sistemas e chama a rota de devolução com o endToEndId. A CodeSpar confere o pagamento contra o extrato do próprio consumidor, recusa uma segunda devolução do mesmo dinheiro, estorna o lançamento da carteira e envia a devolução pela Celcoin; o status é lido na mesma rota. Nenhum mandato é consumido: a devolução está presa a quem pagou e limitada pelo crédito original.
O código, e o que ele pressupõe.
// Prerequisites: CODESPAR_API_KEY set to a test key (csk_test_…), a consumer // (user_0000) whose wallet received the Pix, and that payment's endToEndId. import { CodeSpar } from "@codespar/sdk"; const cs = new CodeSpar(); // return R$ 186.00 of the payment to its payer; never more than what is left to return const res = await cs.api.response("post", "/v1/consumers/{consumerId}/pix/devolutions", { path: { consumerId: "user_0000" }, body: { end_to_end_id: "E00000000202610081200abcdef123456", amount_minor: 18_600, idempotency_key: "refund-8421" }, }); console.log(res.status, res.ok ? res.data : null);
Exemplo com o SDK publicado (@codespar/sdk 0.16.11). Os pré-requisitos estão nos comentários. Compilar não prova a integração: rode primeiro em modo de teste.
POST /v1/consumers/{consumerId}/pix/devolutionsDevolve um Pix recebido a quem pagou, pelo endToEndId, limitado ao crédito original, com chave de idempotência obrigatória.
GET /v1/consumers/{consumerId}/pix/devolutions/{devolutionId}Lê o status da devolução.
Comece com uma chave de teste.
Chaves de teste são gratuitas. Abra o sandbox, conecte os provedores que o seu projeto usa e veja quais ferramentas ele pode chamar antes de construir.