Solicitar reembolso de uma venda

Abre uma solicitação de reembolso para a venda identificada por
reference_id. A venda precisa pertencer ao seller dono do token.

Efeitos imediatos, na mesma transação de banco:

retenção de valor bruto da venda + R$ 1,00 do saldo do seller;

criação da solicitação em requested, com um code público;

disparo do webhook refund com event = requested.

A venda não muda de status agora — ela só vai para refunding na
aprovação e para refunded na conclusão.

Não há PIN nem confirmação extra: a credencial é o próprio token do
parceiro.

Erros de negócio

Todos com corpo { "message": …, "error": … }:

`error`	HTTP	Causa
`transaction_not_found`	404	`reference_id` não existe ou não é do seller do token
`transaction_not_completed`	422	a venda não está `completed`
`transaction_type_unsupported`	422	não é PIX nem cartão de crédito
`transaction_origin_unsupported`	422	não é uma venda (split filho, comissão, taxa…)
`invalid_transaction_amount`	422	valor da venda menor ou igual a zero
`seller_not_approved`	422	conta do seller não está aprovada
`refund_out_of_window`	422	passou dos 90 dias do pagamento
`transaction_under_med`	422	venda em contestação MED aberta
`transaction_already_refunded`	409	venda já reembolsada ou em reembolso
`refund_request_in_progress`	409	já existe solicitação aberta para a venda

Os 409 são conflitos de estado: a venda pode voltar a ser
reembolsável (ex.: a solicitação anterior foi reprovada). Os 422 de
elegibilidade, exceto transaction_not_completed, são definitivos para
aquela venda — não vale a pena repetir a chamada.

Não há saldo mínimo: a retenção é aplicada mesmo que deixe o saldo do
seller negativo.

Forneça seu token bearer no cabeçalho

Authorization

ao fazer requisições para recursos protegidos.

Exemplo:

Authorization: Bearer ********************

application/json

Solicitação criada, em requested. O bloco transaction traz os
dados do comprador; events não vem nesta resposta — use
GET /refunds/{code} para o histórico.

Bodyapplication/json

curl --location '/api/partner/v1/transaction/9c1e2f3a-5b47-4d8e-9f21-6a0b3c4d5e6f/refund' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "reason": "product_not_delivered", "reason_details": "Cliente relatou que o produto nunca foi entregue e solicitou a devolução do valor." }'

{ "data": { "code": "rfd_7c02e5a1b3", "status": "requested", "status_label": "Solicitado", "amount": "250.00", "fee": "1.00", "total": "251.00", "reason": "product_not_delivered", "reason_label": "Produto não entregue", "reason_details": "Cliente relatou que o produto nunca foi entregue e solicitou a devolução do valor.", "rejection_category": null, "rejection_category_label": null, "rejection_reason": null, "provider_receipt": null, "executed_at": null, "requested_at": "2026-08-10T14:35:00.000000Z", "approved_at": null, "rejected_at": null, "completed_at": null, "cancelled_at": null, "transaction": { "reference_id": "9c1e2f3a-5b47-4d8e-9f21-6a0b3c4d5e6f", "end_to_end_id": "E1234567820260810143000abcdef123", "amount": "250.00", "paid_at": "2026-08-01T12:00:00.000000Z", "method": "pix", "fees": "12.45", "product": null, "client": { "name": "Maria Silva", "email": "maria@example.com", "document": "12345678901", "phone": "+5511999999999" } } } }

Solicitar reembolso de uma venda

Erros de negócio

Requisição

Respostas

Solicitar reembolso de uma venda

Erros de negócio#

Requisição

Respostas

Erros de negócio