Reembolsos

Devolver a totalidade ou parte de uma cobrança.

Criar um reembolso

POST /v1/refunds

Campo	Obrigatório	Descrição
payment_id	sim	A cobrança original: o seu identificador ou a sua referência
amount_minor	—	Cadeia, em unidades menores. Ausente = o saldo restante
reason	—	customer_request, duplicate, fraudulent ou other
description	—	Texto livre, visível no painel

O reembolso é uma operação de pleno direito: o seu próprio id, o seu próprio estado, o seu próprio evento webhook (refund.success / refund.failed).

Regras

• Só uma cobrança bem-sucedida se reembolsa.
• A soma dos reembolsos não pode ultrapassar o montante cobrado — acima disso a API responde 422 refund_exceeds_refundable.
• As comissões de cobrança não são devolvidas: ficam a seu cargo.
• Um reembolso parcial deixa a cobrança original consultável, com o seu histórico completo.
• Os fundos são retirados do seu saldo disponível no momento da chamada, como num pagamento.

Uma chave de idempotência por reembolso. Nunca o identificador do pagamento original: uma cobrança pode ser reembolsada em várias vezes, e uma chave com o identificador do pai faria o segundo reembolso parcial passar por um reenvio do primeiro.

Ler e listar

GET /v1/refunds/{id}
GET /v1/refunds                     — lista; ?payment_id= para uma só cobrança
GET /v1/payments/{id}/refunds        — os reembolsos de uma cobrança

GET /v1/payments/{id}/refunds e GET /v1/refunds?payment_id= devolvem o mesmo objeto que a lista, com a mesma paginação. A cobrança é designada pelo seu identificador ou pela sua referência; a de outra conta responde 404 no sub-recurso, e uma lista vazia no filtro.

Códigos de recusa

Um reembolso recusado responde 422, no envelope de erro habitual:

Código	Significado
refund_exceeds_refundable	O montante excede o que resta reembolsável. O erro inclui amount_refundable_minor.
wave_partial_refund_window_closed	Cobrança Wave: o prazo de reembolso parcial terminou; só é possível o reembolso total, se nada tiver sido reembolsado.
wave_partial_refunds_disabled	Os reembolsos parciais Wave não estão abertos; o reembolso total continua possível.
wave_refund_window_closed	Cobrança Wave já reembolsada em parte e prazo terminado: nenhum outro reembolso.
payer_not_found	A Wave não indica o pagador: um reembolso parcial, pago ao pagador, não pode ser enviado.
insufficient_funds	O seu saldo disponível não cobre o reembolso.

Wave: reembolsos parciais

A Wave só reembolsa uma transação na totalidade. Um reembolso parcial de uma cobrança Wave é, por isso, pago ao número Wave do pagador, e apenas dentro do prazo indicado por partial_refund_deadline na cobrança. Depois desse prazo, só é possível o reembolso total, e apenas se nada tiver sido reembolsado.