Jump to Content

Criar Payout

Cria uma solicitação de saque do saldo disponível na sua conta Legacy para qualquer chave PIX válida registrada no DICT do Banco Central.

POST https://api.legacyecombr.com.br/payout

📘
Autenticação obrigatória
Envie o cabeçalho Authorization: Basic base64(pk_live_xxxx:sk_live_yyyy) em todas as chamadas. Consulte o guia de Autenticação.

🚧
Saldo insuficiente retorna 400
Se sua conta não possuir saldo disponível suficiente (descontando reservas e saques pendentes), a requisição retornará 400 Bad Request com o código INSUFFICIENT_FUNDS.

Corpo da requisição

Campos obrigatórios

Campo	Tipo	Descrição
`amount`	`number`	Valor do saque em centavos (ex.: `25000` = R$250,00)
`pixKey`	`string`	Chave PIX de destino
`pixKeyType`	`string`	Tipo da chave: `CPF`, `CNPJ`, `EMAIL`, `PHONE` ou `EVP`
`referenceId`	`string`	Identificador único no seu sistema para conciliação

Campos opcionais

Campo	Tipo	Descrição
`beneficiaryName`	`string`	Nome do beneficiário (auxilia na confirmação antes do envio)
`beneficiaryDocument`	`string`	CPF ou CNPJ do beneficiário
`webhookUrl`	`string (URL)`	URL para receber notificações de status via POST

Exemplo de requisição

POST /payout HTTP/1.1
Host: api.holdinglegacy.io
Content-Type: application/json
Authorization: Basic base64(pk_live_xxxx:sk_live_yyyy)

{
  "amount": 250000,
  "pixKey": "[email protected]",
  "pixKeyType": "EMAIL",
  "referenceId": "comissao-parceiro-001",
  "beneficiaryName": "Maria Silva",
  "beneficiaryDocument": "83416281085",
  "webhookUrl": "https://sua-api.com/webhooks/legacy"
}

Resposta `201 Created`

{
  "id": "payout_1A2B3C",
  "externalId": null,
  "status": "PENDING",
  "amount": 250000,
  "currency": "BRL",
  "pixKey": "[email protected]",
  "pixKeyType": "EMAIL",
  "referenceId": "comissao-parceiro-001",
  "beneficiaryName": "Maria Silva",
  "beneficiaryDocument": "83416281085",
  "feeAmount": null,
  "netAmount": null,
  "bankReceipt": null,
  "createdAt": "2026-03-02T16:25:00.000Z",
  "updatedAt": "2026-03-02T16:25:00.000Z"
}

📘
Fluxo de status do Payout
O saque parte de PENDING → PROCESSING → COMPLETED (em caso de sucesso) ou FAILED / REFUSED (em caso de rejeição). O saldo é debitado imediatamente ao criar o Payout e devolvido automaticamente em caso de falha. Monitore os eventos via Webhooks.

Aprovação manual

Dependendo da configuração da sua conta, alguns saques podem entrar no status AWAITING_APPROVAL, exigindo aprovação manual no Dashboard da Legacy antes de serem processados. Em contas com aprovação automática, o Payout vai direto para PENDING.

Erros comuns

Erro	Status	Causa
`INVALID_PIX_KEY`	400	Chave PIX inválida ou não encontrada no DICT
`BEYOND_LIMITS`	400	Valor excede o limite permitido neste horário
`TEMPORARY_UNAVAILABLE`	502	Adquirente temporariamente indisponível — tente novamente em 5 a 10 minutos
`PROVIDER_REJECTED`	502	Transferência rejeitada pelo SPB — saldo será estornado automaticamente

Updated 40 minutes ago