Create Recurring Withdrawal

Use this endpoint to schedule automatic, periodic withdrawals to a destination PIX key.

When a recurring withdrawal is created, the API automatically generates every scheduling (schedulings) based on the frequency and duration given. Each scheduling is processed individually, on its expected date, as an ordinary withdrawal.

Available Environments

Production

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

Endpoint

• Method: POST
• Endpoint: /recurring-withdrawal
• Authentication: Bearer token

Request Body

⚠️ Important: Amounts in Cents

The monetary amount (amount) must be sent in cents, as an integer.

Examples:

• R$10.00 = 1000
• R$99.99 = 9999

ℹ️ Combinations of frequencyType and frequencyUnit

• REPEAT_EVERY (repeat every X days/months): accepts frequencyUnit DAYS or MONTHS. frequencyValue is the interval between executions (for example, frequencyValue: 15 + frequencyUnit: DAYS = every 15 days).
• FIXED_DAY (fixed day of the month): requires frequencyUnit: MONTHS. frequencyValue is the day of the month the withdrawal must happen on (1 to 31). If the month does not have that day, the withdrawal happens on the last day of the month.

Name	Type	Required	Description	Validations
amount	number	Yes	Amount of each withdrawal (integer, in cents)	Must be an integer in cents; minimum 10 (R$0.10) and maximum 10000000 (R$100,000.00)
description	string	Yes	Description of the recurring withdrawal	Must be between 2 and 255 characters
pixKey	string	Yes	Destination PIX key	Must be validated according to the pixKeyType sent: CPF: 11 digits CNPJ: 14 digits EMAIL: valid format PHONE: Brazilian format (+5511999999999) EVP: valid UUID
pixKeyType	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Yes	Key type	Must be a valid enum
frequencyType	string (enum) - REPEAT_EVERY, FIXED_DAY	Yes	Frequency type	Must be a valid enum
frequencyUnit	string (enum) - DAYS, MONTHS	Yes	Frequency unit	If frequencyType is FIXED_DAY, it must be MONTHS
frequencyValue	number	Yes	Interval (for REPEAT_EVERY) or day of the month (for FIXED_DAY)	Minimum 1; if frequencyType is FIXED_DAY, maximum 31
duration	number	Yes	Number of executions to schedule	Must be an integer; minimum 1; maximum 255

Request Example

cURL

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

Success Response

Field	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the recurring withdrawal
amount	number	Yes	Amount of each withdrawal (integer, in cents)
status	string (enum) - ACTIVE	Yes	ACTIVE: recurring withdrawal created, with active schedulings

Response Example

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

Possible Errors

Code	Description	Solution
401	Invalid credentials	Check your credentials
403	No permission/authorization	Contact support
422	Invalid or missing data	Check the format of the data
422	Validations	Contact support
500	Internal error	Contact support