Request Withdrawal

Use this endpoint to send funds from your account to the customer or partner, in a single call.

As an alternative, the two-step flow checks that the PIX key belongs to the expected holder before settling: Create Withdrawal Intent and then Confirm Withdrawal Intent.

Available Environments

Production

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

Endpoint

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

Request Body

⚠️ Important: Amounts in Cents

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

Examples:

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

DO NOT use: 99.99, 10.00, negative values USE: 9999, 1000 (always integers)

Name	Type	Required	Description	Validations
amount	number	Yes	Withdrawal amount (integer, in cents)	Must be an integer in cents; minimum 10 (R$0.10) and maximum 10000000 (R$100,000.00)
method	string (enum) - PIX (Default value: PIX)	No	Withdrawal method	Must be a valid enum
webhookUrl	string (URL)	No	HTTPS URL to receive notifications	Must be a valid URL, https required; no fragment (#); host and TLD required; query allowed
externalCode	string	No	Your reference code	Must be between 8 and 255 characters
observation	string	No	Internal note about the withdrawal	Must be at most 255 characters
idempotencyKey	string	Yes	Unique identifier to avoid duplicates	Must be between 8 and 255 characters

ℹ️ observation is for internal use only

The observation field is stored, but it is not returned by Get Withdrawal nor by List Withdrawals.

Withdrawal Destination

Name	Type	Required	Description	Validations
pixKey	string	Yes	Destination PIX key	Must be validated according to the pixKeyType provided: 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

Request Example

cURL

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

Success Response

Field	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the withdrawal
externalCode	string	No	Your reference code
amount	number	Yes	Withdrawal amount (integer, in cents)
status	string (enum) - PENDING	Yes	PENDING: Withdrawal created, awaiting processing

Response Example

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

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
429	Too many requests	Wait and try again
500	Internal error	Contact support