OnnixPay

Pagamentos

Criar pagamento

Envia um pagamento de saída a partir do saldo do Merchant. Escolha o trilho em method e o destino conforme o caso. O valor é reservado na hora; o resultado chega por webhook.

POST/v1/payouts

Headers

x-api-keystringobrigatório
Sua chave de API com escopo payout:write.
Idempotency-Keystringobrigatório
Chave única da operação (mín. 8 caracteres). Reenvios retornam o mesmo pagamento e nunca duplicam a transferência.

Corpo da requisição

methodenumopcionaldefault: pix
Trilho: pix (instantâneo) ou ted (SPB, outros bancos).
amountintegeropcional
Valor em centavos. Obrigatório, exceto em PIX pix_code (o valor vem embutido no copia-e-cola).
pix_keystringopcional
PIX por chave. Chave do recebedor (CPF, CNPJ, e-mail, telefone ou aleatória). Exige end_to_end_id.
end_to_end_idstringobrigatório
Obrigatório com pix_key. O end_to_end_id devolvido por POST /v1/pix/dict/lookup para essa mesma chave. Vale 12 horas e serve para um único pagamento.
pix_codestringopcional
PIX copia-e-cola. EMV BR Code dinâmico (com valor). Dispensa amount.
recipientobjectopcional
Conta bancária. Obrigatório em TED; em PIX, transfere manualmente para uma conta. Veja os campos abaixo.
finalitystringopcionaldefault: 10
Apenas TED. Código de finalidade (purpose). 99999 (Outros) exige description.
descriptionstringopcional
Descrição do pagamento (máx. 140 chars).
referencestringopcional
Identificador livre do seu lado (máx. 140 chars). Ecoado na resposta.
webhook_urlstringopcional
URL que recebe os eventos deste pagamento (pix.out.completed, pix.out.failed, ted.out.completed, ted.out.failed). Complementa os webhooks configurados no Merchant. Ecoada na resposta.
webhook_secretstringopcional
Segredo (mín. 8 chars) usado para assinar a entrega deste webhook (HMAC-SHA256 no header x-onnix-signature). Nunca é retornado.

O objeto recipient

namestringobrigatório
Nome do titular da conta.
documentstringobrigatório
CPF (11 dígitos) ou CNPJ (14 dígitos), só números.
bank_ispbstringobrigatório
ISPB do banco do recebedor (8 dígitos).
branchstringobrigatório
Agência, sem dígito.
accountstringobrigatório
Número da conta, sem o dígito verificador.
account_digitstringopcional
Dígito verificador da conta.
account_typeenumopcionaldefault: checking
checking (corrente) ou savings (poupança).

Acompanhe o resultado por webhook

O payout nasce processing. Quando a rede confirma, enviamos pix.out.completed ou ted.out.completed; se falhar, pix.out.failed / ted.out.failed e a reserva volta ao saldo. Configure os eventos em Webhooks.

Pagar por chave exige consultar antes

Um payout com pix_key só é aceito com o end_to_end_id devolvido por POST /v1/pix/dict/lookup para aquela mesma chave. São sempre duas chamadas: consulta a chave, confirma o recebedor com o pagador, e paga reenviando o id. Sem o campo a resposta é 422 PAYOUT_END_TO_END_ID_REQUIRED.

O motivo é o DICT: cada consulta gasta uma unidade do saldo de consultas da conta, e o pagamento só a devolve se reenviar o id daquela consulta. Se a API consultasse por conta própria dentro do payout, o saldo se esgotaria e os saques passariam a falhar com 429 para todo mundo.

O id expira em 12 horas e vale um pagamento. Se você receber 422 PIX_DICT_LOOKUP_EXPIRED, consulte a chave de novo e refaça o payout com o id novo. Pagamentos por pix_code ou recipient não usam esse campo.

TED é para outros bancos

TED entre contas do mesmo banco é recusada pela rede. Para destinos na própria instituição, use method: "pix".
Requisição
curl https://apiv2.onnixpay.com/v1/payouts \
  -X POST \
  -H "x-api-key: sk_live_sua_chave_aqui" \
  -H "Idempotency-Key: saque-7781" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "amount": 5000,
    "pix_key": "maria@exemplo.com",
    "end_to_end_id": "E1393589320260828143000s0a1b2c3d4",
    "description": "Repasse de comissão",
    "reference": "saque-7781",
    "webhook_url": "https://seu-app.com/webhooks/onnix"
  }'
Resposta
{
  "id": "019e9045-8a9b-7f76-9017-297fcf4fd5cf",
  "object": "payout",
  "method": "pix",
  "status": "processing",
  "amount": 5000,
  "currency": "BRL",
  "end_to_end_id": null,
  "recipient": {
    "name": "Maria Souza",
    "document": "12345678909",
    "bank_ispb": "60701190",
    "branch": "0001",
    "account": "123456",
    "pix_key": "maria@exemplo.com"
  },
  "description": "Repasse de comissão",
  "reference": "saque-7781",
  "webhook_url": "https://seu-app.com/webhooks/onnix",
  "failure_reason": null,
  "created_at": "2026-06-04T01:35:37.115Z",
  "completed_at": null,
  "failed_at": null
}
AnteriorO objeto PayoutPróximo Consultar pagamento