Crear Intención de Retiro

Utilice este endpoint para validar el destino de un retiro antes de ejecutarlo, confirmando que la clave PIX realmente pertenece al titular que usted espera.

La respuesta trae el nombre del receptor y un intentId, que luego envía a Confirmar Intención de Retiro. Es el primer paso del flujo en dos pasos; para crear un retiro en una única llamada, use Solicitar Retiro.

Entornos Disponibles

Producción

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

Endpoint

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

Request Body

⚠️ Importante: Montos en Centavos

El amount debe enviarse en centavos, como número entero.

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)

ℹ️ El holderDocument se coteja con la clave

La plataforma consulta el titular de la clave PIX y lo compara con el holderDocument que usted envió. Si no son la misma persona, la intención no se crea y la solicitud es rechazada.

Esa verificación es lo que diferencia este flujo de la creación directa: usted descubre que la clave no pertenece al titular esperado antes de que salga el dinero.

ℹ️ La intención expira en 5 minutos

El intentId permanece válido por 5 minutos. Pasado ese tiempo, la confirmación responde que la intención no fue encontrada o expiró, y debe crear una nueva.

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
holderDocument	string	Sí	Documento del titular que usted espera encontrar en la clave	Debe ser un CPF o CNPJ válido y corresponder al titular de la clave
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

Destino del Retiro

Nombre	Tipo	Obligatorio	Descripción	Validaciones
pixKey	string	Sí	Clave PIX del receptor	Debe ser una clave válida para el pixKeyType informado
pixKeyType	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Sí	Tipo de la clave PIX	Debe ser un enum válido

Ejemplo de Solicitud

cURL

curl --request POST \
--url https://api.gateway.com.br/core/withdrawal/intent \
--header 'Authorization: Bearer su-token-jwt' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 10000,
    "pixKey": "12345678910",
    "pixKeyType": "CPF",
    "holderDocument": "123.456.789-10",
    "webhookUrl": "https://sua-api.com/webhooks/withdrawal",
    "externalCode": "SAQUE-123",
    "observation": "Repasse semanal"
}'

JavaScript

const response = await fetch('https://api.gateway.com.br/core/withdrawal/intent', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer su-token-jwt',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 10000,
    pixKey: '12345678910',
    pixKeyType: 'CPF',
    holderDocument: '123.456.789-10',
    webhookUrl: 'https://sua-api.com/webhooks/withdrawal',
    externalCode: 'SAQUE-123',
    observation: 'Repasse semanal',
  })
});
const data = await response.json();

Respuesta Exitosa

Campo	Tipo	Obligatorio	Descripción
intentId	string (UUID)	Sí	Identificador de la intención, usado para confirmar el retiro
type	string (enum) - PIX_KEY	Sí	Origen del destino resuelto
method	string (enum) - PIX	Sí	Método del retiro
amount	number	Sí	Monto del retiro (entero, en centavos)
receiverName	string	No	Nombre del receptor, cuando el PSP lo informa

Campo	Tipo	Obligatorio	Descripción
pixKey	string	Sí	Clave PIX del destino
pixKeyType	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Sí	Tipo de la clave PIX del destino

Ejemplo de Respuesta

{
  "intentId": "553e8400-e29b-41d4-a716-436251480000",
  "type": "PIX_KEY",
  "method": "PIX",
  "amount": 10000,
  "receiverName": "Fulano de Tal",
  "pixKey": "12345678910",
  "pixKeyType": "CPF"
}

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

Código	Descripción	Solución
422	La clave PIX no pertenece al documento informado	Verifique el holderDocument y la pixKey