Listar Retiros

Utilice este endpoint para listar retiros con filtros.

Entornos Disponibles

Producción

https://api.gateway.com.br/core

Endpoint

Método: GET
Endpoint: /withdrawal
Autenticación: Bearer token

Query Params

ℹ️ Fechas en ISO

Los campos startDate y endDate deben enviarse como ISO date string con hora.

Ejemplo:

2026-03-06T12:00:00.000Z

ℹ️ Paginación por snapshot

El snapshot no es un puntero a la "página siguiente": es un identificador fijo de la sesión de paginación, usado junto con page (que sigue siendo enviado e incrementado normalmente) para mantener los resultados consistentes incluso si se crean nuevos registros durante la navegación.

Tome el valor de snapshot de la primera respuesta (enviada sin snapshot en la primera solicitud) y reenvíe ese mismo valor, sin modificarlo, en las solicitudes de las páginas siguientes, junto con los mismos filtros y el mismo perPage usados originalmente. Si alguno de esos valores cambia mientras se reenvía un snapshot antiguo, la API devuelve un error.

Nombre	Tipo	Obligatorio	Descripción	Validaciones
`snapshot`	string	No	Identificador de la sesión de paginación (recibido en el campo `snapshot` de la primera respuesta); reenvíelo sin modificar junto con `page` en las páginas siguientes	Debe corresponder a los mismos filtros y al mismo `perPage` de la solicitud original
`startDate`	string	No	Fecha inicial del filtro	Debe ser una ISO date string con hora
`endDate`	string	No	Fecha final del filtro	Debe ser una ISO date string con hora
`status`	string[] (enum) - `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELED`, `REFUNDED`, `REJECTED`, `PENDING_COMPLIANCE`	No	Lista de estados para filtrar	Debe ser un arreglo no vacío y sin duplicados
`id`	string (UUID v4)	No	Identificador del retiro	Debe ser un UUID v4 válido
`pixKey`	string	No	Clave PIX del retiro	Debe ser una clave PIX válida (CPF, CNPJ, EMAIL, PHONE o EVP)
`endToEnd`	string	No	Identificador end-to-end del retiro	Debe tener entre 8 y 255 caracteres
`endToEndRefund`	string	No	Identificador end-to-end del reembolso	Debe tener entre 8 y 255 caracteres
`externalCode`	string	No	Su código de referencia	Debe tener entre 8 y 255 caracteres
`minAmount`	number	No	Monto mínimo del retiro (centavos)	Debe ser entero en centavos; mínimo `10` (BRL 0.10) y máximo `10000000` (BRL 100,000.00)
`maxAmount`	number	No	Monto máximo del retiro (centavos)	Debe ser entero en centavos; mínimo `10` (BRL 0.10) y máximo `10000000` (BRL 100,000.00)

Ejemplo de Solicitud

cURL
JavaScript

curl --request GET \
--url https://api.gateway.com.br/core/withdrawal?status=PENDING&status=PROCESSING&startDate=2026-03-06T00:00:00.000Z&endDate=2026-03-06T23:59:59.999Z \
--header 'Authorization: Bearer su-token-jwt'

const params = new URLSearchParams({
  startDate: '2026-03-06T00:00:00.000Z',
  endDate: '2026-03-06T23:59:59.999Z'
});
params.append('status', 'PENDING');
params.append('status', 'PROCESSING');

const response = await fetch(`https://api.gateway.com.br/core/withdrawal?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer su-token-jwt'
  }
});
const data = await response.json();

Respuesta Exitosa

Campo	Tipo	Obligatorio	Descripción
`totalPages`	number	Sí	Total de páginas
`currentPage`	number	Sí	Página actual
`perPage`	number	Sí	Elementos por página
`snapshot`	string	No	Identificador de la sesión de paginación; reenvíelo sin modificar en las páginas siguientes
`data`	array	Sí	Lista de retiros

Campos del elemento en `data`

Campo	Tipo	Obligatorio	Descripción
`id`	string (UUID)	Sí	Identificador único del retiro
`acquirerCode`	string	No	Código del adquirente
`acquirer`	string	Sí	Adquirente del retiro
`amount`	number	Sí	Monto del retiro (entero, en centavos)
`method`	string (enum) - `PIX`	Sí	Método del retiro
`webhookUrl`	string	No	URL de webhook configurada
`externalCode`	string	No	Su código de referencia
`paymentReceipt`	object	No	Comprobante de pago (ver Sub-Objeto `PaymentReceiptUrl`)
`refundReceipt`	object	No	Comprobante de reembolso (ver Sub-Objeto `PaymentReceiptUrl`)
`createdAt`	string (ISO)	Sí	Fecha de creación
`status`	string (enum) - `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELED`, `REFUNDED`, `REJECTED`, `PENDING_COMPLIANCE`	Sí	PENDING: Retiro creado, en espera de procesamiento PROCESSING: Retiro en procesamiento PROCESSED: Retiro procesado con éxito FAILED: Error en el procesamiento CANCELED: Retiro cancelado REFUNDED: Retiro reembolsado REJECTED: Retiro rechazado por el gateway PENDING_COMPLIANCE: Retiro pendiente de revisión de compliance
`statusHistory`	array	Sí	Historial de estados (ver Sub-Objetos `StatusHistory`)
`updatedAt`	string (ISO)	Sí	Fecha de la última actualización
`amountWithdrawn`	number	No	Monto efectivamente retirado
`processedDate`	string (ISO)	No	Fecha de procesamiento
`errorMessage`	string	No	Mensaje de error
`endToEnd`	string	No	Identificador end-to-end del retiro
`endToEndRefund`	string	No	Identificador end-to-end del reembolso
`refundDate`	string (ISO)	No	Fecha del reembolso
`refundAmount`	number	No	Monto del reembolso (entero, en centavos)
`payer`	object	No	Datos del pagador (ver Sub-Objetos `AccountHolder`)
`receiver`	object	No	Datos del receptor (ver Sub-Objetos `AccountHolder`)
`pixKey`	object	No	Datos de la clave PIX (ver Sub-Objetos `PixKeyVo`)
`trackingKey`	string	No	Clave de rastreo del SPEI. En retiros PIX siempre viene `null`
`feeAmount`	number	No	Monto de la comisión

Sub-Objetos

StatusHistory (elemento)

Campo	Tipo	Obligatorio	Descripción
`status`	string (enum) - `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELED`, `REFUNDED`, `REJECTED`, `PENDING_COMPLIANCE`	Sí	Estado del retiro
`date`	string (ISO)	Sí	Fecha del estado
`durationInMilliseconds`	number	Sí	Duración del estado en milisegundos

AccountHolder

Campo	Tipo	Obligatorio	Descripción
`type`	string (enum) - `PF`, `PJ`	Sí	Tipo de titular
`name`	string	Sí	Nombre del titular
`document`	string	Sí	Documento del titular
`bankAccount`	object	Sí	Datos bancarios (ver Sub-Objetos `BankAccount`)
`pix`	object	Sí	Clave PIX del titular (ver Sub-Objetos `PixKeyVo`)

BankAccount

Campo	Tipo	Obligatorio	Descripción
`type`	string	Sí	Tipo de cuenta
`digit`	string	Sí	Dígito de la cuenta
`ispb`	string	Sí	ISPB del banco

PixKeyVo

Campo	Tipo	Obligatorio	Descripción
`key`	string	Sí	Clave PIX
`type`	string (enum) - `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`	Sí	Tipo de la clave PIX

PaymentReceiptUrl

Campo	Tipo	Obligatorio	Descripción
`url`	string	Sí	URL del comprobante
`expirationDate`	string (ISO)	Sí	Fecha de expiración del comprobante

Ejemplo de Respuesta

Datos enmascarados

Los valores sensibles pueden estar enmascarados con ***.

{
  "totalPages": 1,
  "currentPage": 1,
  "perPage": 15,
  "snapshot": "b3BhcXVlLXNuYXBzaG90LXRva2Vu",
  "data": [
    {
      "id": "553e8400-e29b-41d4-a716-436251480000",
      "acquirerCode": "ACQ-123",
      "acquirer": "ACQUIRER_EXEMPLO",
      "amount": 10000,
      "method": "PIX",
      "webhookUrl": "https://sua-api.com/webhooks/withdrawal",
      "externalCode": "SAQUE-123",
      "paymentReceipt": {
        "url": "https://files.exemplo.com.br/receipts/withdrawal-553e8400-e29b-41d4-a716-436251480000.pdf",
        "expirationDate": "2026-04-01T00:00:00.000Z"
      },
      "refundReceipt": {
        "url": "https://files.exemplo.com.br/receipts/withdrawal-refund-553e8400-e29b-41d4-a716-436251480000.pdf",
        "expirationDate": "2026-04-01T00:00:00.000Z"
      },
      "createdAt": "2026-03-06T12:49:04.681Z",
      "status": "REFUNDED",
      "statusHistory": [
        {
          "status": "PENDING",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 1000
        },
        {
          "status": "PROCESSING",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 10000
        },
        {
          "status": "PROCESSED",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 10000
        },
        {
          "status": "REFUNDED",
          "date": "2026-03-06T12:49:04.681Z",
          "durationInMilliseconds": 5000
        }
      ],
      "updatedAt": "2026-03-06T12:49:04.681Z",
      "amountWithdrawn": 10000,
      "processedDate":  "2026-03-06T12:49:04.681Z",
      "errorMessage": "Falha ao registrar o estorno no PSP",
      "endToEnd": "0123456789",
      "endToEndRefund": "0123456789-REFUND",
      "refundDate": "2026-03-06T14:49:04.681Z",
      "refundAmount": 10000,
      "payer": {
        "type": "PF",
        "name": "Fulano de Tal",
        "document": "***456789**",
        "bankAccount": {
          "type": "CHECKING",
          "digit": "7",
          "ispb": "12345678"
        },
        "pix": {
          "key": "12345678910",
          "type": "CPF"
        }
      },
      "receiver": {
        "type": "PJ",
        "name": "Empresa Exemplo LTDA",
        "document": "12345678000199",
        "bankAccount": {
          "type": "CHECKING",
          "digit": "0",
          "ispb": "12345678"
        },
        "pix": {
          "key": "contato@exemplo.com",
          "type": "EMAIL"
        }
      },
      "pixKey": {
        "key": "12345678910",
        "type": "CPF"
      },
      "feeAmount": 150
    }
  ]
}

Errores Posibles

Código	Descripción	Solución
401	Credenciales inválidas	Verifique sus credenciales
403	Sin permiso/autorización	Contacte al soporte
422	Datos inválidos o faltantes	Verifique el formato de los datos
422	Validaciones	Contacte al soporte
500	Error interno	Contacte al soporte

Entornos Disponibles​

Endpoint​

Query Params​

Ejemplo de Solicitud​

Respuesta Exitosa​

Campos del elemento en data​

Sub-Objetos​

StatusHistory (elemento)​

AccountHolder​

BankAccount​

PixKeyVo​

PaymentReceiptUrl​

Ejemplo de Respuesta​

Errores Posibles​