Criar Intenção de Saque

Utilize este endpoint para validar o destino de um saque antes de efetivá-lo, confirmando que a chave PIX pertence mesmo ao titular que você espera.

A resposta traz o nome do recebedor e um intentId, que você envia depois para Confirmar Intenção de Saque. É o primeiro passo do fluxo em duas etapas; para criar um saque numa única chamada, use Solicitar Saque.

Ambientes Disponíveis

Produção

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

Endpoint

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

Request Body

⚠️ Importante: Valores em Centavos

O amount deve ser enviado em centavos como número inteiro.

Exemplos:

• R$ 10,00 = 1000
• R$ 99,99 = 9999
• R$ 100,50 = 10050

NÃO use: 99.99, 10.00, valores negativos USE: 9999, 1000 (sempre inteiros)

ℹ️ O holderDocument é conferido na chave

A plataforma consulta o titular da chave PIX e compara com o holderDocument que você enviou. Se não forem a mesma pessoa, a intenção não é criada e a requisição é recusada.

É essa checagem que diferencia este fluxo da criação direta: você descobre que a chave não pertence ao titular esperado antes de o dinheiro sair.

ℹ️ A intenção expira em 5 minutos

O intentId fica válido por 5 minutos. Passado esse tempo, a confirmação responde que a intenção não foi encontrada ou expirou, e você precisa criar uma nova.

Nome	Tipo	Obrigatório	Descrição	Validações
amount	number	Sim	Valor do saque (inteiro em centavos)	Deve ser inteiro em centavos; mínimo 10 (R$ 0,10) e máximo 10000000 (R$ 100.000,00)
method	string (enum) - PIX (Valor padrão: PIX)	Não	Método do saque	Deve ser um enum válido
holderDocument	string	Sim	Documento do titular que você espera encontrar na chave	Deve ser CPF ou CNPJ válido e corresponder ao titular da chave
webhookUrl	string (URL)	Não	URL HTTPS para receber notificações	Deve ser URL válida com https obrigatório; sem fragmento (#); host e TLD obrigatórios; query permitida
externalCode	string	Não	Seu código de referência	Deve ter entre 8 e 255 caracteres
observation	string	Não	Observação interna sobre o saque	Deve ter no máximo 255 caracteres

Destino do Saque

Nome	Tipo	Obrigatório	Descrição	Validações
pixKey	string	Sim	Chave PIX do recebedor	Deve ser uma chave válida para o pixKeyType informado
pixKeyType	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Sim	Tipo da chave PIX	Deve ser um enum válido

Exemplo de Requisição

cURL

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

Resposta de Sucesso

Campo	Tipo	Obrigatório	Descrição
intentId	string (UUID)	Sim	Identificador da intenção, usado para confirmar o saque
type	string (enum) - PIX_KEY	Sim	Origem do destino resolvido
method	string (enum) - PIX	Sim	Método do saque
amount	number	Sim	Valor do saque (inteiro em centavos)
receiverName	string	Não	Nome do recebedor, quando o PSP o informa

Campo	Tipo	Obrigatório	Descrição
pixKey	string	Sim	Chave PIX do destino
pixKeyType	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Sim	Tipo da chave PIX do destino

Exemplo de Resposta

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

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

Código	Descrição	Solução
422	A chave PIX não pertence ao documento informado	Confira o holderDocument e a pixKey