Crear Retiro Recurrente

Utilice este endpoint para programar retiros automáticos y periódicos hacia una clave PIX de destino.

Al crear un retiro recurrente, la API genera automáticamente todas las programaciones (schedulings) según la frecuencia y la duración indicadas. Cada programación se procesa individualmente, en su fecha prevista, como un retiro común.

Entornos Disponibles

Producción

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

Endpoint

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

Request Body

⚠️ Importante: Montos en Centavos

El valor monetario (amount) debe enviarse en centavos, como número entero.

Ejemplos:

• BRL 10.00 = 1000
• BRL 99.99 = 9999

ℹ️ Combinaciones de frequencyType y frequencyUnit

• REPEAT_EVERY (repetir cada X días/meses): acepta frequencyUnit DAYS o MONTHS. frequencyValue es el intervalo entre ejecuciones (por ejemplo, frequencyValue: 15 + frequencyUnit: DAYS = cada 15 días).
• FIXED_DAY (día fijo del mes): exige frequencyUnit: MONTHS. frequencyValue es el día del mes en que debe ocurrir el retiro (1 a 31). Si el mes no tiene ese día, el retiro ocurre el último día del mes.

Nombre	Tipo	Obligatorio	Descripción	Validaciones
amount	number	Sí	Monto de cada retiro (entero, en centavos)	Debe ser entero en centavos; mínimo 10 (BRL 0.10) y máximo 10000000 (BRL 100,000.00)
description	string	Sí	Descripción del retiro recurrente	Debe tener entre 2 y 255 caracteres
pixKey	string	Sí	Clave PIX de destino	Debe validarse según el pixKeyType enviado: 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
frequencyType	string (enum) - REPEAT_EVERY, FIXED_DAY	Sí	Tipo de frecuencia	Debe ser un enum válido
frequencyUnit	string (enum) - DAYS, MONTHS	Sí	Unidad de la frecuencia	Si frequencyType es FIXED_DAY, debe ser obligatoriamente MONTHS
frequencyValue	number	Sí	Intervalo (para REPEAT_EVERY) o día del mes (para FIXED_DAY)	Mínimo 1; si frequencyType es FIXED_DAY, máximo 31
duration	number	Sí	Cantidad de ejecuciones a programar	Debe ser entero; mínimo 1; máximo 255

Ejemplo de Solicitud

cURL

curl --request POST \
--url https://api.gateway.com.br/core/recurring-withdrawal \
--header 'Authorization: Bearer su-token-jwt' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 10000,
    "description": "Repasse mensal para fornecedor",
    "pixKey": "12345678910",
    "pixKeyType": "CPF",
    "frequencyType": "FIXED_DAY",
    "frequencyUnit": "MONTHS",
    "frequencyValue": 5,
    "duration": 12
}'

JavaScript

const response = await fetch('https://api.gateway.com.br/core/recurring-withdrawal', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer su-token-jwt',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 10000,
    description: 'Repasse mensal para fornecedor',
    pixKey: '12345678910',
    pixKeyType: 'CPF',
    frequencyType: 'FIXED_DAY',
    frequencyUnit: 'MONTHS',
    frequencyValue: 5,
    duration: 12
  })
});
const data = await response.json();

Respuesta Exitosa

Campo	Tipo	Obligatorio	Descripción
id	string (UUID)	Sí	Identificador único del retiro recurrente
amount	number	Sí	Monto de cada retiro (entero, en centavos)
status	string (enum) - ACTIVE	Sí	ACTIVE: retiro recurrente creado y con programaciones activas

Ejemplo de Respuesta

{
  "id": "553e8400-e29b-41d4-a716-436251480000",
  "amount": 10000,
  "status": "ACTIVE"
}

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