Skip to main content
POST
/
refunds
/
invoice
/
{invoiceId}
curl -X POST "https://api.gates2b.com/refunds/invoice/123" \
  -H "Authorization: Bearer {seu-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 50.00,
    "reason": "Produto com defeito"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invoice": {
    "id": 123,
    "transaction_pix_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
    "amount_final": 100.00,
    "status": "REFUND_REQUESTED",
    "med_amount": 0
  },
  "user": {
    "id": 456,
    "name": "João Silva",
    "email": "joao@empresa.com"
  },
  "gateway": "PIX",
  "transaction_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
  "amount": 50.00,
  "reason": "Produto com defeito",
  "status": "REFUND_IN_PROGRESS",
  "external_refund_id": "",
  "created_at": "2025-09-24T14:30:15.123Z",
  "updated_at": "2025-09-24T14:30:15.123Z"
}
​
Authorization
string
required
O token de autenticação no formato Bearer é obrigatório para acessar este endpoint.
​
invoiceId
string
required
ID da invoice (venda) para a qual será solicitado o reembolso.
​
value
number
Valor específico do reembolso. Se não informado, será processado um reembolso total do valor recebido na venda.
​
reason
string
Motivo do reembolso. Campo opcional utilizado para controle interno.

​
Response

​
id
string
Identificador único do reembolso criado.
​
invoice
object
Dados da venda relacionada ao reembolso.
​
user
object
Dados do usuário que solicitou o reembolso.
​
gateway
string
Gateway utilizado para processar o reembolso (ex: PIX, IUGU).
​
transaction_id
string
ID da transação original que está sendo reembolsada.
​
amount
number
Valor do reembolso solicitado.
​
reason
string
Motivo do reembolso informado na solicitação.
​
status
string
Status atual do reembolso. Possíveis valores:
  • REFUND_IN_PROGRESS: Reembolso em processamento
  • REFUND_COMPLETED: Reembolso concluído
  • REFUND_FAILED: Reembolso falhou
  • REFUND_CANCELLED: Reembolso cancelado
​
external_refund_id
string
ID externo do reembolso fornecido pelo gateway.
​
created_at
string
Data e hora de criação do reembolso.
​
updated_at
string
Data e hora da última atualização do reembolso.
curl -X POST "https://api.gates2b.com/refunds/invoice/123" \
  -H "Authorization: Bearer {seu-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 50.00,
    "reason": "Produto com defeito"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invoice": {
    "id": 123,
    "transaction_pix_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
    "amount_final": 100.00,
    "status": "REFUND_REQUESTED",
    "med_amount": 0
  },
  "user": {
    "id": 456,
    "name": "João Silva",
    "email": "joao@empresa.com"
  },
  "gateway": "PIX",
  "transaction_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
  "amount": 50.00,
  "reason": "Produto com defeito",
  "status": "REFUND_IN_PROGRESS",
  "external_refund_id": "",
  "created_at": "2025-09-24T14:30:15.123Z",
  "updated_at": "2025-09-24T14:30:15.123Z"
}

​
Observações Importantes

​
Reembolso Parcial vs Total

  • Reembolso Parcial: Quando o parâmetro value é informado, o sistema processará um reembolso do valor especificado
  • Reembolso Total: Quando o parâmetro value não é informado, o sistema calculará automaticamente o valor total disponível para reembolso (valor recebido + valor MED)

​
Validações

  1. Saldo Disponível: O sistema verifica se há saldo suficiente na conta para processar o reembolso
  2. Status da Invoice: A invoice deve estar em status válido para reembolso (não pode estar já reembolsada)
  3. Valor Máximo: O valor do reembolso não pode exceder o valor total recebido na venda

​
Fluxo de Processamento

  1. Criação: O reembolso é criado com status REFUND_IN_PROGRESS
  2. Processamento: O sistema envia a solicitação para o gateway de pagamento
  3. Conclusão: Uma vez processado pelo gateway, o status é atualizado via webhook interno
  4. Balanceamento: O valor é debitado do saldo disponível do usuário

​
Códigos de Status HTTP

  • 201: Reembolso criado com sucesso
  • 400: Dados inválidos ou restrições de negócio
  • 401: Token de autenticação inválido
  • 404: Invoice não encontrada
  • 500: Erro interno do servidor