Skip to main content
POST
/
payout
Criar Payout
curl --request POST \
  --url https://api.example.com/payout \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 123,
  "pixKey": "<string>",
  "pixKeyType": "<string>",
  "referenceId": "<string>",
  "webhookUrl": "<string>",
  "beneficiaryName": "<string>",
  "beneficiaryDocument": "<string>"
}
'

Documentation Index

Fetch the complete documentation index at: https://developers.holdinglegacy.io/llms.txt

Use this file to discover all available pages before exploring further.

Crie e acompanhe transferências de saídas seguras do seu saldo disponível utilizando as chaves PIX de destino cadastradas em território brasileiro.

​
Autorização

​
Authorization
string
required
Use o Basic Auth codificado em 64 das suas chaves de produção.

​
Body

​
amount
integer
required
Somas totais a retirar em centavos sem pontuação (Min: R$1,00 - 100).
​
pixKey
string
required
Documentação/chave da conta recebedora do Bacen. Pode ser Email, CPF/CNPJ ou UUID.
​
pixKeyType
string
required
Determina de que formato é a pixKey. Valores suportados:
  • CPF
  • CNPJ
  • EMAIL
  • PHONE
  • EVP (Chave Aleatória)
​
referenceId
string
required
Identificador unívoco do seu lado para alinhar recibos. Recomendação: GUIDV4.
​
webhookUrl
string
Um end-point configurado do seu lado para ouvir mudanças até que o saco atinja COMPLETED ou FAILED.
​
beneficiaryName
string
O nome da pessoa que receberá na conta bancária (Aprovado durante o KYC do DICT - Diretório de contatos PIX). Opcional.
​
beneficiaryDocument
string
Opcional. Caso o recebedor possua empresa associada ao destino do saque.

​
Response

A rota retornará o estado inicial da transferência. Como o saque bancário depende da grade horária do SPB, geralmente a resposta nasce como PENDING ou PROCESSING. 
{
  "id": "payout_1001A",
  "externalId": null,
  "status": "PENDING",
  "amount": 250000,
  "pixKey": "maria@email.com",
  "pixKeyType": "EMAIL",
  "referenceId": "comissionado_001",
  "beneficiaryName": null,
  "createdAt": "2026-03-02T16:25:00.000Z"
}

​
Erros de Validação Comuns (4xx):

  • Insufficient Funds (400): A sua conta, descontando os bloqueios ou saques previstos, não possui o amount para a transferência se concretizar.
  • Invalid Key (422): A formatação da chave falhou antes de ser encaminhada ao DICT para varredura.
Lembre-se de verificar sempre em nossos Webhooks para automatizar o reflexo do saque retornado de falha na carteira do seu painel e devolver o saldo virtual de volta.