Reembolsos e cancelamento

Reembolsar

POST /v1/payments/{id}/refund — total (omita amount) ou parcial. idempotencyKey é obrigatório; reenviar a mesma chave retorna o reembolso existente sem criar um duplicado.

curl -X POST 'https://v2.pagnow.com/v1/payments/{id}/refund' \
  -H 'apikey: pnk_sua_chave_aqui' \
  -H 'content-type: application/json' \
  -d '{
    "idempotencyKey": "refund-pedido-123",
    "amount": 1990,
    "reason": "Cliente solicitou"
  }'

Campos do reembolso

Campo	Tipo	Obrigatório	Notas
`idempotencyKey`	string (8-128 chars)	sim	Protege contra reembolso duplo em caso de falha de rede.
`amount`	int	não	Centavos. Omita para reembolso total. Deve ser maior que 0 e até o saldo reembolsável.
`reason`	string	não	Motivo do reembolso (max 500 chars).
`strategy`	string	não	`devolution` = devolução BACEN pelo `endToEndId`; `cashout` = PIX-out para a chave do pagador. Padrão: `cashout`.
`passFeeToTenant`	boolean	não	Se `true`, a taxa de PIX-out do reembolso por cashout é debitada da sua carteira; se `false`/omitido, a plataforma absorve.
`destinationKey`	string	não	Chave PIX de destino para cashout (sobrescreve o `customerDocument` da cobrança). Útil quando a cobrança não possui documento do pagador.
`refundId`	string (UUID)	não	ID do reembolso gerado pelo chamador. Se omitido, o gateway gera automaticamente.

Ciclo de vida do reembolso

PENDING → IN_PROGRESS → REFUNDED
                      → FAILED

O reembolso começa em PENDING, avança para IN_PROGRESS enquanto o provedor processa e termina em REFUNDED (sucesso) ou FAILED (erro no provedor). Você recebe o webhook correspondente a cada transição.

Listar reembolsos de uma transação

curl 'https://v2.pagnow.com/v1/payments/{id}/refunds' \
  -H 'apikey: pnk_sua_chave_aqui'

Cancelar

POST /v1/payments/{id}/cancel — cancela uma cobrança em aberto (WAITING_PAYMENT / PENDING / PROCESSING). Cobranças já pagas devem ser reembolsadas, não canceladas.

curl -X POST 'https://v2.pagnow.com/v1/payments/{id}/cancel' \
  -H 'apikey: pnk_sua_chave_aqui'