Criar Saque Recorrente

Utilize este endpoint para agendar saques automáticos e periódicos para uma chave PIX de destino.

Ao criar um saque recorrente, a API gera automaticamente todos os agendamentos (schedulings) com base na frequência e na duração informadas. Cada agendamento é processado individualmente, na sua data prevista, como um saque comum.

Ambientes Disponíveis

Produção

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

Endpoint

• Método: POST
• Endpoint: /recurring-withdrawal
• Autenticação: Bearer token

Request Body

⚠️ Importante: Valores em Centavos

O valor monetário (amount) deve ser enviado em centavos como número inteiro.

Exemplos:

• R$ 10,00 = 1000
• R$ 99,99 = 9999

ℹ️ Combinações de frequencyType e frequencyUnit

• REPEAT_EVERY (repetir a cada X dias/meses): aceita frequencyUnit DAYS ou MONTHS. frequencyValue é o intervalo entre execuções (ex.: frequencyValue: 15 + frequencyUnit: DAYS = a cada 15 dias).
• FIXED_DAY (dia fixo do mês): exige frequencyUnit: MONTHS. frequencyValue é o dia do mês em que o saque deve ocorrer (1 a 31). Se o mês não tiver aquele dia, o saque ocorre no último dia do mês.

Nome	Tipo	Obrigatório	Descrição	Validações
amount	number	Sim	Valor de cada saque (inteiro em centavos)	Deve ser inteiro em centavos; mínimo 10 (R$ 0,10) e máximo 10000000 (R$ 100.000,00)
description	string	Sim	Descrição do saque recorrente	Deve ter entre 2 e 255 caracteres
pixKey	string	Sim	Chave PIX de destino	Deve ser validada conforme o pixKeyType informado: CPF: 11 dígitos CNPJ: 14 dígitos EMAIL: formato válido PHONE: formato brasileiro (+5511999999999) EVP: UUID válido
pixKeyType	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Sim	Tipo da chave	Deve ser um enum válido
frequencyType	string (enum) - REPEAT_EVERY, FIXED_DAY	Sim	Tipo de frequência	Deve ser um enum válido
frequencyUnit	string (enum) - DAYS, MONTHS	Sim	Unidade da frequência	Se frequencyType for FIXED_DAY, deve ser obrigatoriamente MONTHS
frequencyValue	number	Sim	Intervalo (para REPEAT_EVERY) ou dia do mês (para FIXED_DAY)	Mínimo 1; se frequencyType for FIXED_DAY, máximo 31
duration	number	Sim	Quantidade de execuções a serem agendadas	Deve ser inteiro; mínimo 1; máximo 255

Exemplo de Requisição

cURL

curl --request POST \
--url https://api.gateway.com.br/core/recurring-withdrawal \
--header 'Authorization: Bearer seu-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 seu-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();

Resposta de Sucesso

Campo	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	Identificador único do saque recorrente
amount	number	Sim	Valor de cada saque (inteiro em centavos)
status	string (enum) - ACTIVE	Sim	ACTIVE: Saque recorrente criado e com agendamentos ativos

Exemplo de Resposta

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

Possíveis Erros

Código	Descrição	Solução
401	Credenciais inválidas	Verifique suas credenciais
403	Sem permissão/autorização	Contate o suporte
422	Dados inválidos ou faltando	Verifique o formato dos dados
422	Validações	Contate o suporte
500	Erro interno	Contate o suporte