Estornos

Só pagamentos com status done podem ser estornados. O estorno é assíncrono: a API aceita o pedido na hora e o resultado chega por webhook.

Estorno diretoCopy Anchor Link

curl -X POST "$XPAYZ_URL/refund/0d4ba8f5-bbc6-4cbb-ae65-13de2f903271" \
  -H "X-Secret-ID: $XPAYZ_SECRET_ID" \
  -H "X-Secret-Key: $XPAYZ_SECRET_KEY"

{ "status": "processing", "refund_correlation_id": "c1d2e3f4-..." }

O ID no caminho é o data.external_id do webhook (ou o id em Listar pagamentos do link). Quando o estorno terminar, você recebe event.refunded.

Solicitação de estornoCopy Anchor Link

Subcontas não estornam direto (recebem 403, código PGPL0024). Elas abrem uma solicitação com o motivo, que é analisada antes de ser executada:

curl -X POST "$XPAYZ_URL/refund-request/0d4ba8f5-bbc6-4cbb-ae65-13de2f903271" \
  -H "Content-Type: application/json" \
  -H "X-Secret-ID: $XPAYZ_SECRET_ID" \
  -H "X-Secret-Key: $XPAYZ_SECRET_KEY" \
  -d '{ "reason": "Cliente desistiu da compra" }'

Se aprovada, chega event.refunded. Se recusada, event.refund_rejected.

RespostasCopy Anchor Link