Saltar al contenido principal
POST
https://api.gates2b.com
/
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": "Producto con defecto"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invoice": {
    "id": 123,
    "transaction_pix_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
    "amount_final": 100.0,
    "status": "REFUND_REQUESTED",
    "med_amount": 0
  },
  "user": {
    "id": 456,
    "name": "Joao Silva",
    "email": "joao@empresa.com"
  },
  "gateway": "PIX",
  "transaction_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
  "amount": 50.0,
  "reason": "Producto con defecto",
  "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
requerido
El token de autenticacion en formato Bearer es obligatorio para acceder a este endpoint.
​
invoiceId
string
requerido
ID de la invoice (venta) para la cual se solicitara el reembolso.
​
value
number
Monto especifico del reembolso. Si no se informa, se procesara un reembolso total del valor recibido en la venta.
​
reason
string
Motivo del reembolso. Campo opcional para control interno.

​
Response

​
id
string
Identificador unico del reembolso creado.
​
invoice
object
Datos de la venta relacionada al reembolso.
​
user
object
Datos del usuario que solicito el reembolso.
​
gateway
string
Gateway utilizado para procesar el reembolso (ej: PIX, IUGU).
​
transaction_id
string
ID de la transaccion original que se reembolsa.
​
amount
number
Monto del reembolso solicitado.
​
reason
string
Motivo del reembolso informado en la solicitud.
​
status
string
Estado actual del reembolso. Valores posibles: - REFUND_IN_PROGRESS: Reembolso en proceso - REFUND_COMPLETED: Reembolso completado - REFUND_FAILED: Reembolso fallido - REFUND_CANCELLED: Reembolso cancelado
​
external_refund_id
string
ID externo del reembolso proporcionado por el gateway.
​
created_at
string
Fecha y hora de creacion del reembolso.
​
updated_at
string
Fecha y hora de la ultima actualizacion del 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": "Producto con defecto"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invoice": {
    "id": 123,
    "transaction_pix_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
    "amount_final": 100.0,
    "status": "REFUND_REQUESTED",
    "med_amount": 0
  },
  "user": {
    "id": 456,
    "name": "Joao Silva",
    "email": "joao@empresa.com"
  },
  "gateway": "PIX",
  "transaction_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
  "amount": 50.0,
  "reason": "Producto con defecto",
  "status": "REFUND_IN_PROGRESS",
  "external_refund_id": "",
  "created_at": "2025-09-24T14:30:15.123Z",
  "updated_at": "2025-09-24T14:30:15.123Z"
}

​
Observaciones Importantes

​
Reembolso Parcial vs Total

  • Reembolso Parcial: Cuando se informa value, el sistema procesa un reembolso por el monto especificado
  • Reembolso Total: Cuando value no se informa, el sistema calcula automaticamente el monto total disponible para reembolso (monto recibido + monto MED)

​
Validaciones

  1. Saldo Disponible: El sistema verifica si hay saldo suficiente en la cuenta para procesar el reembolso
  2. Estado de la Invoice: La invoice debe estar en un estado valido para reembolso (no puede estar ya reembolsada)
  3. Monto Maximo: El monto del reembolso no puede exceder el monto total recibido en la venta

​
Flujo de Procesamiento

  1. Creacion: El reembolso se crea con estado REFUND_IN_PROGRESS
  2. Procesamiento: El sistema envia la solicitud al gateway de pago
  3. Conclusion: Una vez procesado por el gateway, el estado se actualiza via webhook interno
  4. Balanceo: El monto se debita del saldo disponible del usuario

​
Codigos de Estado HTTP

  • 201: Reembolso creado con exito
  • 400: Datos invalidos o restricciones de negocio
  • 401: Token de autenticacion invalido
  • 404: Invoice no encontrada
  • 500: Error interno del servidor