Estornos

Um estorno devolve ao comprador todo ou parte de um pagamento confirmado. Pede-se pela API, com o payment_id que veio no payment.succeeded (ou no payment da sessão), ou no painel, em Estornos.

curl -s "$SPOLLY_API_URL/v1/refunds" \
  -H "Authorization: Bearer $SPOLLY_SECRET_KEY" \
  -H "Idempotency-Key: estorno-1042-1" \
  -H "Content-Type: application/json" \
  -d '{"payment_id": "pay_...", "amount": 500000, "reason": "Devolução parcial a pedido do cliente."}'

{
  "id": "re_7Tq3Mn5Wx9Yz2Ab4Cd6Ef8",
  "object": "refund",
  "payment_id": "pay_9Hq2Lm4Rt8Vx1Zb6Nc3Kd0",
  "amount": {"amount": 500000, "currency": "AOA"},
  "status": "pending",
  "reason": "Devolução parcial a pedido do cliente.",
  "created_at": "2026-12-02T09:00:00Z"
}

• Sem amount, estorna-se o que resta do pagamento. Com ele, em unidades menores, na moeda do pagamento (em AOA, kwanzas inteiros).
• Podem fazer-se vários estornos parciais do mesmo pagamento, e a soma nunca passa o que se cobrou: um estorno acima do que resta é recusado com 422 estorno_acima_do_cobrado, com o que resta na mensagem, mesmo com dois pedidos ao mesmo tempo.
• Um pagamento que não está confirmado dá 409 pagamento_nao_pago, e um já todo estornado dá 409 pagamento_ja_estornado.
• O Idempotency-Key é obrigatório, como em todos os POST: um pedido repetido com a mesma chave devolve o mesmo estorno, e não estorna duas vezes.

O desfecho de um estorno que ficou processing ou pending lê-se com GET /v1/refunds/re_.... O webhook refund.created chega quando o estorno fica aceite (pending ou succeeded).

curl -s "$SPOLLY_API_URL/v1/refunds/re_..." \
  -H "Authorization: Bearer $SPOLLY_SECRET_KEY"

O valor estornado sai do teu saldo disponível e, quando não chega, da reserva. Se nem assim chegar, o saldo fica negativo, e os saques param até os pagamentos seguintes o cobrirem. A taxa do pagamento não se devolve.