Create Withdrawal Intent

Use this endpoint to validate the destination of a withdrawal before settling it, confirming that the PIX key really belongs to the holder you expect.

The response carries the receiver's name and an intentId, which you then send to Confirm Withdrawal Intent. This is the first step of the two-step flow; to create a withdrawal in a single call, use Request Withdrawal.

Available Environments

Production

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

Endpoint

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

Request Body

⚠️ Important: Amounts in Cents

The 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)

ℹ️ The holderDocument is checked against the key

The platform looks up the holder of the PIX key and compares it with the holderDocument you sent. If they are not the same person, the intent is not created and the request is rejected.

That check is what sets this flow apart from direct creation: you find out that the key does not belong to the expected holder before the money leaves.

ℹ️ The intent expires in 5 minutes

The intentId stays valid for 5 minutes. After that, the confirmation replies that the intent was not found or has expired, and you have to create a new one.

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
holderDocument	string	Yes	Document of the holder you expect to find on the key	Must be a valid CPF or CNPJ and match the holder of the key
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

Withdrawal Destination

Name	Type	Required	Description	Validations
pixKey	string	Yes	PIX key of the receiver	Must be a valid key for the pixKeyType provided
pixKeyType	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Yes	PIX key type	Must be a valid enum

Request Example

cURL

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

Success Response

Field	Type	Required	Description
intentId	string (UUID)	Yes	Identifier of the intent, used to confirm the withdrawal
type	string (enum) - PIX_KEY	Yes	Source of the resolved destination
method	string (enum) - PIX	Yes	Withdrawal method
amount	number	Yes	Withdrawal amount (integer, in cents)
receiverName	string	No	Name of the receiver, when the PSP provides it

Field	Type	Required	Description
pixKey	string	Yes	PIX key of the destination
pixKeyType	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Yes	PIX key type of the destination

Response Example

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

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

Code	Description	Solution
422	The PIX key does not belong to the document provided	Check the holderDocument and the pixKey