Reembolsar cobrança

Devolve ao pagador o valor total ou parcial de uma cobrança paga, descontando do seu saldo disponível.

POST

/charge/{chargeId}/refund

Authorization

apiKey

headerAuthorizationBearer <token>

Chave de API gerada no painel: Authorization: Bearer <chave>.

Path Parameters

chargeId*string

Id da cobrança, como veio em id (ou chargeId) na criação.

Request Body

application/json

body

value?string

Valor a reembolsar, string com duas casas decimais. Omitido, reembolsa tudo o que ainda não foi reembolsado.

Padrão (regex)^\d{1,20}\.\d{2}$

reason?string

Motivo, para o seu controle. Não é mostrado ao pagador.

Tamanholength <= 500

Response Body

Reembolso processado.

application/json

response

id?string

Id do reembolso.

Formatouuid

chargeId?string

Id da cobrança reembolsada.

amount?string

Valor reembolsado, string decimal (pode vir com mais de duas casas, como "20.00000000").

status?string

PROCESSED: reembolso feito. FAILED: recusado. REQUESTED: em processamento.

Valores aceitos"REQUESTED""PROCESSED""FAILED"

reason?|

O motivo enviado.

gateway?|

Identificador interno de quem processou. Não use em regra de negócio.

externalRefundId?|

Comprovante do reembolso no processador de pagamento, quando informado.

createdAt?string

Criação, em UTC.

Formatodate-time

curl -X POST 'https://api.gates2b.com/charge/string/refund' \  -H 'Content-Type: application/json' \  -d '{  "value": "20.00",  "reason": "Item fora de estoque"}'

Example ResponseSchema

{  "id": "0192f4d0-2b1a-7c3d-8e4f-5a6b7c8d9e0f",  "chargeId": "01JC8Z3R5W7Y9A1C3E5G7J9K2M",  "amount": "20.00000000",  "status": "PROCESSED",  "reason": "Item fora de estoque",  "gateway": null,  "externalRefundId": "e2e-7c1a9b3f",  "createdAt": "2026-10-22T15:30:00.000Z"}

Como funciona

O reembolso é síncrono: a mesma chamada valida o pedido, devolve o dinheiro ao pagador e debita o seu saldo. Quando a resposta chega com status: "PROCESSED", o reembolso está feito.

1.até 7 dias após a criaçãoVocêPedidoPOST /charge/{chargeId}/refund, com value ou sem (restante)
2.Gates2bValidaçãocobrança paga, valor até o restante, saldo disponível suficiente
3.Gates2bDevolução ao pagadorpelo mesmo meio do pagamento
4.Gates2bDébito no seu saldoo valor reembolsado sai do seu saldo; partes de split não são debitadas
5.Gates2bPROCESSED + charge.refundeda resposta traz o reembolso; o webhook avisa as suas inscrições

Um reembolso de cobrança, do pedido à resposta, numa única chamada.

Exemplo: numa cobrança paga de 100.00, um reembolso de 30.00 deixa a cobrança em PAID com refundedAmount: "30.00". Um segundo pedido sem value reembolsa os 70.00 restantes e a cobrança passa a REFUNDED.

Regras

A cobrança precisa ter sido paga e criada há no máximo 7 dias. Fora disso, a resposta é 400.
Sem value, o reembolso cobre tudo o que ainda não foi reembolsado. Com value, a soma dos reembolsos não pode passar de grossAmount.
O valor sai do seu saldo disponível. Se o saldo não cobrir, a resposta é 400 com o disponível e o necessário na mensagem.
O reembolso sai só do seu saldo. As partes de split já distribuídas não são debitadas.
Alguns meios de pagamento só aceitam reembolso do valor total. Nesses casos, um value menor que grossAmount responde 400 pedindo o valor integral.
O processamento é síncrono: status: "PROCESSED" na resposta significa reembolso feito. Se o processamento falhar, a resposta é 400 com mensagem genérica; tente de novo ou fale com o suporte.
Cada reembolso processado gera o evento charge.refunded nas suas inscrições de webhook.

AuthorizationCopiar link da seção

Path ParametersCopiar link da seção

Request BodyCopiar link da seção

Response BodyCopiar link da seção

Como funcionaCopiar link da seção