rfd_) devolve ao comprador o valor de um pagamento já liquidado. Ele registra o
pedido, o motivo e o caminho percorrido até o dinheiro sair — no cartão e no Pix pelo próprio
gateway, no boleto por transferência bancária.
Você não cria um reembolso neste recurso: não existe POST /refunds. Ele nasce do estorno de
uma transação ou de um pagamento, e é lá que o
reason é informado. Os endpoints abaixo consultam o que já existe e decidem o que está pendente.
O reembolso carrega o comprador e o checkout da venda de origem.
customerId, customerName,
customerEmail, customerDocument e customerDocumentType dizem de quem era a compra, e
additionalInfo.checkoutLinkId liga o estorno ao link de checkout que a vendeu — os mesmos campos
em GET /refunds/:id, na listagem e em todos os eventos refund.*, para você reagir a um estorno
sem consultar a transação. Eles são copiados da transação no momento em que o reembolso é
criado: editar o cadastro do cliente depois não os altera. additionalInfo é nulo quando a
venda foi criada direto pela API, sem link de checkout; os campos do comprador só são nulos quando
a própria transação não tem cliente.Todas as rotas exigem o header
x-api-key (sua chave de sandbox). Veja
Autenticação. Os exemplos nas páginas de cada endpoint usam a base URL de
sandbox https://api.sandbox.z2pay.com/v1.Endpoints
Cada endpoint tem sua própria página, com os campos aceitos, exemplos e o playground para testar.Status do reembolso
O status diz em que ponto do caminho o dinheiro está. No cartão e no Pix quem o determina é o gateway; no boleto, quem executa a transferência — a plataforma ou a sua própria conta, conforme o contrato. A você cabe a decisão inicial, quando ela é manual, e o fim do ciclo quando a devolução é sua. Os estados terminais sãorefunded, refused e failed.
O que decide o status inicial
Um reembolso raramente começa onde se espera: o método de pagamento e uma configuração da sua conta mudam o ponto de partida. Três regras explicam o que você vai ver.Com aprovação automática, cartão e Pix já nascem resolvidos. A configuração vem habilitada por
padrão: o reembolso é criado, aprovado e processado no gateway dentro da própria requisição de
estorno, e a resposta já traz
refunded ou failed. Os estados approved e processing existem,
mas são atravessados durante essa chamada — você não os vê numa resposta síncrona.Boleto sempre nasce
pending, mesmo com a aprovação automática ligada, porque não há estorno
a fazer no gateway: o valor volta por transferência bancária e é preciso saber para qual conta.
Ao ser aprovado, ele vai para awaiting_bank_details — não para processing.Quem coleta os dados bancários do comprador pode ser você. Por padrão o comprador recebe um
e-mail nosso pedindo a conta, e você não faz nada. Se a sua conta for configurada, no painel, para
não enviar esse e-mail — o caso de quem já atende o próprio comprador —, os dados passam por
POST /refunds/:id/bank-details. Assine
refund.awaiting_bank_details para saber quando existe um reembolso esperando destino.A transferência do boleto não é automática, e o reembolso não caminha sozinho. Não há estorno
no gateway: alguém executa a TED ou o Pix e registra que ele saiu. Quando a devolução é da
plataforma, quem faz e confirma somos nós, sem prazo prometido aqui. Quando é a sua conta que
devolve — definido em contrato —, você fecha o ciclo com
POST /refunds/:id/confirm, e nesse caso a transação continua paid:
o valor da venda permanece no seu saldo, então o estorno aparece no reembolso e nos eventos
refund.*, não no status da transação.Veja também
Pagamentos
Onde o reembolso nasce: o estorno de um pagamento, no todo ou em parte.
Transações
O estorno da transação inteira, e como ele afeta o status dela.
Chargebacks
A devolução que parte do emissor do cartão, e não de você.
Taxas
A taxa de reembolso que incide sobre a operação.