Transações - Reembolsar

#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.
• O valor do reembolso não pode exceder o valor da cobrança.
• Cada venda aceita um reembolso: depois dele, mesmo parcial, a transação passa a refunded, e um novo pedido de reembolso responde 422 transactionNotRefundable.
• Há uma trava contra reembolsos concorrentes para a mesma transação.
• Plataformas de marketplace: o reembolso de uma venda feita com onBehalfOf é pedido como a sub-conta, com X-Selectwin-Account: bus_… — veja Operar como a sub-conta. O estorno sai do saldo da sub-conta.
• 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âmetros do Corpo da Requisição

#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
}

#Erros

#Exemplo de erro (HTTP 409)

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

#Melhores Práticas

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