Reembolsos
Quando algo dá errado, o valor volta para o cliente.
Uma transferência que não vai ser entregue termina em reembolso: o valor volta para o cliente e o status fica REFUNDED. Isso acontece de dois jeitos:
| Origem | Quando | refund.initiatedBy |
|---|---|---|
| Automático | O banco de destino recusa a entrega | OXUS |
| Pedido do parceiro | Algo deu errado antes da entrega | PARTNER |
No automático, a etapa DELIVERY fica FAILED e failureReason traz o motivo da recusa. O parceiro não precisa fazer nada.
Quando pedir
| A transferência está | O que fazer |
|---|---|
| Aguardando o pagamento de entrada | Cancelar. Ainda não há valor a devolver |
| Paga, com a entrega pendente | Pedir o reembolso |
Entregue (COMPLETED) | Não há reembolso: o valor já está com o beneficiário |
FAILED, REFUNDING ou REFUNDED | Nada: o reembolso já existe |
Fora dessa janela, a resposta é 409 TRANSFER_NOT_REFUNDABLE.
Pedir o reembolso
Gere uma Idempotency-Key por pedido. Repetir com a mesma chave nunca cria dois reembolsos.
curl -X POST $OXUS_API/v1/transfers/trf_…/refund \
-H "Authorization: Bearer $OXUS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"reason": "CUSTOMER_REQUEST",
"description": "A entrega não avançou e a cliente pediu o valor de volta."
}'reason | Quando usar |
|---|---|
CUSTOMER_REQUEST | O cliente desistiu |
INCORRECT_RECEIVER_DATA | Os dados da conta de destino estão errados |
SUSPECTED_FRAUD | Suspeita de fraude ou de conta invadida |
DUPLICATE_TRANSFER | A mesma operação foi criada duas vezes |
OTHER | Outro motivo, descrito em description |
A transferência para onde estava: as etapas concluídas ficam registradas e as seguintes passam a CANCELLED. O status vai a REFUNDING e, quando o valor chega ao cliente, a REFUNDED, com o webhook transfer.refunded.
Para onde e quanto volta
O cliente recebe de volta o valor integral que pagou, com as tarifas, mesmo que o câmbio já tenha sido feito. A variação cambial fica com a Oxus.
O valor volta sempre para a origem do pagamento: no PIX, para a conta que pagou, pela devolução do próprio PIX; em stablecoin, para a carteira que fez o depósito. Não é possível indicar outro destino.
O objeto refund
{
"id": "trf_jyqRwE1-AHShHbjuAAAAAAAPQk9qxm0WasZtIQBdIQ",
"status": "REFUNDING",
"sourceAmount": 1000015,
"stages": [
{ "stage": "CREATION", "status": "COMPLETED" },
{ "stage": "PAYMENT", "status": "COMPLETED", "reference": "E2EF9864EC3E2F03C002A8D91C1" },
{ "stage": "SETTLEMENT", "status": "COMPLETED" },
{ "stage": "DELIVERY", "status": "CANCELLED" }
],
"refund": {
"status": "PROCESSING",
"initiatedBy": "PARTNER",
"reason": "CUSTOMER_REQUEST",
"amount": 1000015,
"currency": "BRL",
"createdAt": "2026-10-07T18:10:00.000Z"
}
}Aqui o câmbio já tinha sido feito, e mesmo assim voltam os R$ 10.000,15 pagos.
Campo
Tipo
No sandbox
O reembolso termina 15 segundos depois do pedido. Para testar sem pressa, cote um valor com centavos 15: a entrega fica parada até você pedir o reembolso. Veja Testes no sandbox.