Reembolsos

Devolva todo ou parte de um pagamento capturado. O ledger nunca é alterado: cada reembolso gera um lançamento compensatório.

Operações

post /v1/payment-intents/{id}/refunds — Reembolsar PaymentIntent
get /v1/refunds/{id} — Consultar reembolso
post /v1/simulator/refunds/{id}/reconcile — Reconciliar reembolso agora

Criar um reembolso

Reembolso parcial de R$ 49,00 curl

curl -sS -X POST "$WOLF_API_URL/v1/payment-intents/$PAYMENT_INTENT_ID/refunds" \
  -H "Authorization: Bearer $WOLF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reembolso-A-1001-1" \
  -d '{ "amount_minor": "4900" }'

Exige os escopos payments:read e refunds:write e uma Idempotency-Key. Pela sessão do app do seller exige também reautenticação recente (até 10 minutos; senão 403 STEP_UP_REQUIRED); API keys são autorizadas só pelo escopo.
Só um PaymentIntent succeeded pode ser reembolsado. Reembolsos parciais podem se repetir até o valor capturado; a soma dos reembolsos (mais disputas abertas) nunca passa dele — senão 409 REFUND_EXCEEDS_CAPTURED.
A resposta traz o reembolso com o status do provedor. 202 significa resultado desconhecido: a reconciliação automática resolve (no sandbox, force com POST /v1/simulator/refunds/{id}/reconcile).

O objeto Refund

Objeto Refund

Objeto Refund
Campo	Tipo	Detalhes
`id` obrigatório	string	Começa com `rfd_`
`payment_intent_id` obrigatório	string	Começa com `pi_`
`charge_id` obrigatório	string	Começa com `chg_`
`amount_minor` obrigatório	string
`currency` obrigatório	string	Padrão `^[A-Z]{3}$`
`status` obrigatório	string	Valores: `created`, `processing`, `succeeded`, `failed`, `unknown`
`provider_id` obrigatório	string
`external_id` obrigatório	string \| null
`failure_code` obrigatório	string \| null

Estados

Estado	Significado	Pode ir para
`created`	Registrado; o valor já está reservado contra o capturado.	`processing`
`processing`	Enviado ao provedor simulado.	`succeeded`,`failed`,`unknown`
`succeeded`final	Concluído, com journal compensatório no ledger.	—
`failed`final	Recusado pelo provedor; o valor volta a ficar disponível para reembolso.	—
`unknown`	Resultado desconhecido no provedor; a reconciliação decide.	`succeeded`,`failed`

Eventos

refund.created, refund.completed, refund.failed, refund.reconciliation_required e refund.reconciled.