Reembolsar uma transação

Reembolsa uma transação previamente aprovada, com suporte a reembolso total ou parcial. É a ferramenta para devoluções, cancelamentos e correções de cobrança.

Visão Geral

Reembolsa uma transação previamente aprovada, com suporte a reembolso total ou parcial. É a ferramenta para devoluções, cancelamentos e correções de cobrança.

O reembolso é assíncrono: o endpoint aceita a solicitação (HTTP 202) e o estorno é processado em background. Acompanhe o resultado pelos webhooks (transaction.refunded, receivable.refunded) ou consultando a transação.

Precauções

Só pode reembolsar transações no status approved ou pre-authorized.
A soma dos reembolsos não pode exceder o valor original da cobrança.
Há uma trava contra reembolsos concorrentes para a mesma transação.
O reembolso afeta o saldo financeiro da conta.
O ID da transação é sensível a maiúsculas e minúsculas (tra_... ou trx_...).

Casos de uso

Cancelamento de compra após a aprovação.
Produto indisponível/defeituoso — devolução.
Cobrança incorreta — estorno por valor errado.
Acordo comercial — reembolso parcial.

Requisição

POST /v1/transactions/{transactionId}/refund

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`transactionId`	string	Sim	Identificador da transação a reembolsar

Parâmetros do Corpo da Requisição

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	integer	Não	Valor a reembolsar em centavos. Se omitido, reembolsa o valor restante (total)
`reason`	string	Não	Motivo do reembolso (máx. 255 caracteres)

Exemplo — Reembolso Total

{ "reason": "Cliente desistiu da compra e solicitou reembolso" }

Exemplo — Reembolso Parcial

{
  "amount": 5000,
  "reason": "Cliente devolveu apenas um dos itens do pedido"
}

Resposta

Aceito (HTTP 202 Accepted)

O reembolso foi aceito para processamento assíncrono.

{
  "transactionId": "tra_987654321",
  "status": "approved",
  "accepted": true
}

Atributo	Tipo	Descrição
`transactionId`	string	Identificador da transação
`status`	string	Status no momento do aceite (a transição para `refunded` chega por webhook)
`accepted`	boolean	Sempre `true`

Erros

`error.code`	HTTP	Quando
`transactionNotRefundable`	422	A transação não pode ser reembolsada no status atual
`refundAmountInvalid`	422	Valor zero/negativo, ou os reembolsos acumulados excederiam a cobrança original
`refundInProgress`	409	Já existe um reembolso em andamento para esta transação
`transactionNotFound`	404	Transação inexistente

Exemplo de erro (HTTP 409)

{
  "error": {
    "status": "Conflict",
    "statusCode": 409,
    "category": "transaction",
    "code": "refundInProgress",
    "message": "A refund for this transaction is already in progress."
  }
}

Melhores Práticas

Verifique o status antes de reembolsar.
Reaja aos webhooks transaction.refunded / receivable.refunded para confirmar o estorno.
Registre o motivo (reason) para auditoria.
Para cartão de crédito, lembre que o estorno pode levar de 7 a 30 dias para aparecer na fatura.

Reembolsar uma transação

On this page