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á. Quem determina a maior parte dele é o gateway (cartão e Pix) ou o andamento da transferência (boleto) — a você cabe apenas a decisão inicial, quando ela é manual. 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.A coleta dos dados bancários acontece fora desta API. O comprador recebe um convite para
informar a conta, e o reembolso caminha sozinho por
bank_details_received e ted_processing
conforme a transferência avança. Não há endpoint aqui para enviar esses dados.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.