Jump to Content

Criar Payout

Inicia uma transferência financeira via PIX do seu saldo disponível para uma chave PIX de destino.

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 about 2 months ago

Did this page help you?