Para plataformas · saldo BRL → PIX
Envie Pix por API e acompanhe cada pagamento.
Envie PIX a partir do saldo em reais da sua conta ou de uma subconta. Uma integração para saques de usuários, pagamentos e repasses, com débito identificado, taxas discriminadas e acompanhamento por API.
Pagamentos e repasses integrados ao seu sistema.
Use o payout quando a sua plataforma precisa pagar um destinatário com saldo BRL disponível. Cada pagamento tem uma referência, um custo e um estado para conciliar com seu sistema.
Para uma rotina com vários destinatários, sua aplicação deve controlar cada intenção de pagamento e seu identificador. Não presuma um endpoint único de lote ou split automático. Veja também recebimentos e pagamentos Pix na LuniumPay.
O que preparar antes de enviar um PIX
O payout usa saldo BRL disponível. Ele atende plataformas que já recebem por PIX em custódia e precisam permitir saques ou repasses. Quando o dinheiro está em uma carteira cripto externa, o fluxo correspondente é cash-out de cripto para PIX.
Confira a habilitação
Leia payout.enabled em GET /keys/me e custodia_ativa em GET /saldo. Valem as condições da sua chave.
Confira saldo e taxas
Consulte o escopo correto: a casa ou customer_ref. O disponível deve cobrir amount_cents mais as taxas do saque.
Crie e acompanhe
Envie POST /payouts com referência persistida e acompanhe o payout_id retornado até o resultado final.
GET /saldo retorna somente o saldo da casa. Para um cliente, use GET /saldo?customer_ref=cliente-teste. GET /saldo/consolidado soma casa e clientes, mas esse total não é um saldo único disponível para cada subconta.
Exemplo de saque PIX de uma subconta
Use uma chave lun_test_, guardada no backend, e confirme key.sandbox=true em GET /keys/me. Os exemplos abaixo usam documentos e destinos sintéticos. Não os envie com credenciais de produção.
Primeiro, credite a subconta de teste por POST /cashin/charge com destino: "saldo" e confirme o pagamento simulado. Aguarde o crédito disponível e use exatamente o mesmo customer_ref no saque.
POST /payouts · corpo de exemplo para sandbox
{
"amount_cents": 5000,
"pix_key": "teste@example.com",
"pix_key_type": "email",
"tax_number": "00000000191",
"funding_source": "pix_brl",
"customer_ref": "cliente-teste",
"external_id": "sandbox-payout-001"
}Envie para https://api.luniumpay.com/payouts, com X-API-Key e Content-Type: application/json. O exemplo envia R$ 50,00 fictícios; é preciso ter saldo para esse valor mais as taxas. Sem customer_ref, a operação usa a casa.
Troque a chave PIX e o documento pelos do recebedor. tax_number deve conter um CPF ou CNPJ válido para chaves de e-mail, telefone e aleatória. Para uma chave CPF/CNPJ válida, a API deriva o documento da própria chave; se informado, deve coincidir. beneficiary_name continua opcional e não comprova titularidade. Chaves de 11 dígitos exigem pix_key_type: "cpf" ou "phone"; telefone usa DDI, como +55.
Este fluxo usa somente saldo em reais recebido por PIX. funding_source é opcional e aceita apenas pix_brl. O máximo por PIX é 600000 centavos (R$ 6.000,00), sujeito a limite menor da conta, além das taxas.
Em 409 external_id_divergente ou external_id_nao_verificavel, consulte a ordem indicada por payout_id/recovery_endpoint. Preserve o identificador; não gere outro para contornar o conflito. Em 503 idempotencia_indisponivel, aguarde e consulte o mesmo external_id: uma ordem anterior pode existir.
A carteira USDT é separada do saldo BRL: requer habilitação do projeto, recebe depósitos externos de USDT e não usa /payouts. Quando habilitada, usa funding_source=crypto_usdt; documento do recebedor não é exigido nesse fluxo. Seus limites vêm da cotação e das condições da API, não do teto de R$ 6.000 do saldo BRL. Não está disponível em sandbox.
Como calcular o débito e mostrar o custo
O débito é amount_cents + fee_cents. A taxa total da operação reúne fee_service_cents e fee_provider_cents. Consulte saque_fee_bps, saque_taxa_provedor_tipo, saque_taxa_estimada_cents e a fórmula retornada em GET /saldo.
Leia a tarifa vigente na API. Use a condição da chave para estimar e a taxa efetiva registrada na ordem para conciliar. Limites, carência e retenções podem impedir o uso de parte do saldo. 402 saldo_insuficiente significa que o disponível não cobre o débito completo.
A sandbox calcula a tarifa publicada por sua API sobre saldo fictício; consulte as condições de produção na chave real.
Timeout não é autorização para pagar de novo
| Resposta ou estado | Ação do integrador |
|---|---|
processing | Continue consultando GET /payouts/{payout_id}. Não exiba pagamento concluído. |
sent / payout.sent | Concilie valor, taxas e campos de prova: e2e, paid_at e verify_url, quando disponíveis. |
failed ou refunded | Confira a ordem e o extrato. Recusa explícita e resultado incerto exigem tratamentos diferentes. |
| Timeout ou resposta incerta | Recupere a operação original. Não crie outro external_id para a mesma intenção de pagamento. |
Guarde external_id e o identificador retornado antes de atualizar seu pedido. Em retry, mantenha a mesma referência e o mesmo corpo. Configure um receptor HTTPS, valide a assinatura HMAC sobre o corpo bruto e deduplique por event_id. Depois de timeout, consulte a operação original antes de decidir repetir. O manual de webhooks e conciliação detalha a implementação.
O saldo é reservado antes de chamar o provedor. Uma recusa explícita pode estornar os débitos; uma resposta incerta exige conciliação antes do estorno. Implemente uma tela que mostre “em processamento” e permita atualizar o estado sem criar outra ordem.
Dúvidas de integração
Preciso cadastrar uma carteira cripto para usar payout?
Não. Payout PIX usa saldo em reais e uma chave PIX de destino. Você pode receber esse saldo por cobrança com destino: "saldo", sem carteira fixa.
Posso separar o saldo por usuário?
Sim. Use customer_ref no depósito, consulta e saque. A referência organiza os saldos, mas a sua API key tem autoridade sobre suas subcontas; seu backend deve autorizar cada usuário.
É necessário validar o titular antes do pagamento?
GET /pix/keys/lookup é uma consulta auxiliar e pode retornar available=false ou verified=false. Nesse caso mostre titular não verificado. Não invente nome nem confunda indisponibilidade da consulta com indisponibilidade do payout.
Como testar saldo insuficiente e resultado incerto?
Execute o fluxo payout da integração guiada ou do kit. No teste por API, consulte GET /sandbox para a matriz de cenários e use settlement_uncertain quando suportado. A resolução fictícia existe apenas para chaves de sandbox.