Solicitar Retiro

Utilice este endpoint para enviar fondos de su cuenta al cliente o socio, en una única llamada.

Como alternativa, el flujo en dos pasos verifica que la clave PIX pertenezca al titular esperado antes de ejecutarlo: Crear Intención de Retiro y luego Confirmar Intención de Retiro.

Entornos Disponibles

Producción

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

Endpoint

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

Request Body

⚠️ Importante: Montos en Centavos

Todos los valores monetarios (amount) deben enviarse en centavos, como números enteros.

Ejemplos:

• BRL 10.00 = 1000
• BRL 99.99 = 9999
• BRL 100.50 = 10050

NO use: 99.99, 10.00, valores negativos USE: 9999, 1000 (siempre enteros)

Nombre	Tipo	Obligatorio	Descripción	Validaciones
amount	number	Sí	Monto del retiro (entero, en centavos)	Debe ser entero en centavos; mínimo 10 (BRL 0.10) y máximo 10000000 (BRL 100,000.00)
method	string (enum) - PIX (Valor por defecto: PIX)	No	Método del retiro	Debe ser un enum válido
webhookUrl	string (URL)	No	URL HTTPS para recibir notificaciones	Debe ser una URL válida con https obligatorio; sin fragmento (#); host y TLD obligatorios; se permite query
externalCode	string	No	Su código de referencia	Debe tener entre 8 y 255 caracteres
observation	string	No	Observación interna sobre el retiro	Debe tener como máximo 255 caracteres
idempotencyKey	string	Sí	Identificador único para evitar duplicados	Debe tener entre 8 y 255 caracteres

ℹ️ observation es solo de uso interno

El campo observation se almacena, pero no se devuelve en Consultar Retiro ni en Listar Retiros.

Destino del Retiro

Nombre	Tipo	Obligatorio	Descripción	Validaciones
pixKey	string	Sí	Clave PIX de destino	Debe validarse según el pixKeyType informado: CPF: 11 dígitos CNPJ: 14 dígitos EMAIL: formato válido PHONE: formato brasileño (+5511999999999) EVP: UUID válido
pixKeyType	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Sí	Tipo de la clave	Debe ser un enum válido

Ejemplo de Solicitud

cURL

curl --request POST \
--url https://api.gateway.com.br/core/withdrawal \
--header 'Authorization: Bearer su-token-jwt' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 10000,
    "pixKey": "12345678910",
    "pixKeyType": "CPF",
    "webhookUrl": "https://sua-api.com/webhooks/withdrawal",
    "externalCode": "SAQUE-123",
    "observation": "Repasse referente ao pedido 4521",
    "idempotencyKey": "unique-key-12345"
}'

JavaScript

const response = await fetch('https://api.gateway.com.br/core/withdrawal', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer su-token-jwt',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 10000,
    pixKey: "12345678910",
    pixKeyType: "CPF",
    webhookUrl: "https://sua-api.com/webhooks/withdrawal",
    externalCode: "SAQUE-123",
    observation: "Repasse referente ao pedido 4521",
    idempotencyKey: "unique-key-12345"
  })
});
const data = await response.json();

Respuesta Exitosa

Campo	Tipo	Obligatorio	Descripción
id	string (UUID)	Sí	Identificador único del retiro
externalCode	string	No	Su código de referencia
amount	number	Sí	Monto del retiro (entero, en centavos)
status	string (enum) - PENDING	Sí	PENDING: Retiro creado, en espera de procesamiento

Ejemplo de Respuesta

{
  "id": "553e8400-e29b-41d4-a716-436251480000",
  "externalCode": "SAQUE-123",
  "amount": 10000,
  "status": "PENDING"
}

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
429	Demasiadas solicitudes	Espere e inténtelo de nuevo
500	Error interno	Contacte al soporte