Estorne total ou parcialmente um pagamento confirmado. O valor sai do seu saldo; sem saldo suficiente a resposta é 422 insufficient_balance_for_refund com o valor estornável em details. Cada estorno gera refund.created e o pagamento passa a refunded quando estornado por completo (payment.refunded).
Devolução ao pagador: a resposta traz provider_refund. Hoje os pagamentos passam pela Eupago (MB WAY, Multibanco e Pix), que não faz estorno por API: provider_refund.automatic vem false, o valor é debitado do seu saldo e a devolução ao pagador não é automática (combine com o suporte da Uneway). Pagamento pendente, expirado ou com mais de 90 dias responde 422 refund_not_allowed com o motivo.
POST /developer/payments/{ref}/refund
Estornar pagamento
Estorno total (sem amount) ou parcial. Só com chave de produção; o valor sai do seu saldo. Envie Idempotency-Key. Confira provider_refund.automatic: com a Eupago (MB WAY, Multibanco e Pix) é false, ou seja, a devolução ao pagador não é automática.
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
ref obrigatório | caminho | string | id, order_id ou pt_... |
| Campo | Tipo | Descrição |
|---|---|---|
amount | number | Valor a estornar (omitido = total restante). |
reason | string | Motivo (até 500 caracteres). |
curl -X POST https://api.uneway.pro/api/v1/developer/payments/pedido-2001/refund \
-H "Authorization: Bearer uw_test_SUA_CHAVE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"amount": 10.0, "reason": "Item fora de estoque"}'Resposta (exemplo)
{
"success": true,
"data": {
"object": "payment",
"id": 1842,
"order_id": "pedido-2001",
"status": "paid",
"method": "mbway",
"amount": "49.90",
"fee_amount": "1.50",
"net_amount": "48.40",
"currency": "EUR",
"description": "Pedido 2001",
"customer": {
"name": "Ana Souza",
"email": "ana@exemplo.com"
},
"refunded": false,
"refund_amount": "10.00",
"paid_at": "2026-10-02T14:03:11+00:00",
"expired_at": null,
"refunded_at": null,
"created_at": "2026-10-02T14:01:52+00:00",
"metadata": {},
"livemode": true,
"public_token": "pt_8bZ2mQ..."
},
"provider_refund": {
"automatic": false,
"provider": "eupago",
"message": "Estorno registrado e debitado do seu saldo. Este provedor não devolve o valor ao pagador pela API: a devolução não é automática, combine com o suporte da Uneway."
}
}Erros específicos: sandbox_refund_unsupported, refund_not_allowed, insufficient_balance_for_refund, payment_not_found