Send a PIX directly (no crypto leg)

Envia PIX debitando somente saldo BRL disponível da casa ou subconta customer_ref, recebido por PIX. Confira payout.enabled em GET /keys/me, custodia_ativa, pix_rules e taxas em GET /saldo. Máximo R$ 6.000,00 por PIX, sujeito a limites menores da conta. CPF/CNPJ válido do recebedor é obrigatório; a API pode derivá-lo de uma chave CPF/CNPJ. Valor mais taxas são reservados antes de chamar o provedor; sem saldo, 402. Consulte a tarifa vigente na API e concilie fee_cents da operação. Limites e mandate da chave continuam aplicáveis. Use external_id estável e consulte a ordem original após timeout. Sandbox usa saldo fictício e calcula a tarifa publicada pela API; não há pagamento real. 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.

post/payouts

Request

Base URL: https://api.luniumpay.com
URL: https://api.luniumpay.com/payouts
Auth: API key in header X-API-Key

Request body

amount_centsinteger required

Valor do PIX em CENTAVOS de real, inteiro (5000 = R$ 50,00). Máximo 600000 (R$ 6.000,00), sujeito a limite menor da conta. Taxas são debitadas além deste valor.

pix_keystring required

Chave PIX de destino que recebe os reais (CPF, CNPJ, telefone +55, e-mail ou chave aleatória). Com 11 dígitos crus envie também pix_key_type ("cpf" ou "phone") — sem isso a API recusa com erro=tipo_ambiguo em vez de adivinhar.

pix_key_type'cpf' | 'cnpj' | 'phone' | 'email' | 'random'

Opcional: deduzido do formato da chave (e-mail, CNPJ, UUID, telefone com +55). So e obrigatorio quando a chave tem 11 digitos puros, onde CPF e telefone sao indistinguiveis — nesse caso a API recusa com erro tipo_ambiguo em vez de chutar.

tax_numberstring

CPF ou CNPJ válido do recebedor, com dígitos verificadores conferidos. Obrigatório para chave de e-mail, telefone ou aleatória. Para chave CPF/CNPJ válida, pode ser omitido: a API usa o documento da própria chave; se informado, deve coincidir. Não comprova titularidade da chave.

beneficiary_namestring

Optional. Beneficiary's full name, forwarded to the PIX provider as the end user's name. Not required — payouts to third-party PIX keys are allowed.

external_idstring

Identificador idempotente de até 64 caracteres. Nos retries, mantenha valor, chave PIX, tipo, documento, customer_ref e funding_source do pedido original. Conflito 409 external_id_divergente ou external_id_nao_verificavel retorna payout_id/recovery_endpoint para consultar a ordem original; não gere outro ID apenas para contornar o conflito.

customer_refstring

Sub-account to debit (custody keys). Debited BEFORE the PIX is sent: amount + house fee (saque_fee_bps) + provider fee; on explicit provider refusal the debits are reversed. 402 saldo_insuficiente when available balance < amount + fees (saque_fee_bps, saque_taxa_estimada_cents in GET /saldo). Sub-account (e.g. the merchant) whose balance is debited. Same value used on the deposit.

Only for a sandbox key. GET /sandbox provides the scenario matrix by flow. Omit in production. All prices, payments and withdrawals remain fictitious.

funding_source'pix_brl'

Opcional. Único valor aceito: pix_brl. Este endpoint debita saldo em reais recebido por PIX; nunca debita a carteira USDT.

Response

Payout criado ou replay idempotente da operação original.

payout_idstring

customer_refstring nullable

statusstring

processing, sent, failed ou refunded; use extrato para conciliar saldo. Estados novos devem ser tolerados.

amount_centsinteger

Valor que o destinatário recebe.

fee_centsinteger nullable

Total fees beyond amount_cents: fee_service_total_cents + fee_provider_cents. Includes partner commission already; do not add it again.

fee_service_centsinteger nullable

Lunium-only service fee in recorded cents; accounting component. For customer UI and notifications use fee_service_total_cents.

fee_provider_centsinteger nullable

Tarifa do provedor: fee_cents menos fee_service_cents menos fee_partner_cents.

pix_keystring

pix_key_type'cpf' | 'cnpj' | 'phone' | 'email' | 'random'

tax_numberstring nullable

Documento do beneficiário mascarado, quando informado; opcional no pedido.

external_idstring nullable

Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.

errorstring nullable

Motivo quando failed/refunded.

e2estring nullable

EndToEndId do PIX enviado.

receiver_namestring nullable

Nome obtido após o pagamento quando disponível. null quando não obtido.

receiver_tax_numberstring nullable

paid_atstring date-time nullable

sent_atstring date-time nullable

verify_urlstring nullable

Verificação pública do PIX (GET /v1/verificar/{e2e}).

created_atstring date-time nullable

updated_atstring date-time nullable

sandboxboolean

True for fictitious sandbox operations.

simulationobject

fee_partner_centsinteger nullable

Sub fee do parceiro debitada do saldo neste saque (centavos). Parte de fee_cents.

fee_service_total_centsinteger nullable

Combined customer service fee: recorded Lunium fee plus partner commission. Preserves original cent rounding and historical pricing; null when the legacy house component is unknown. Included in payout responses and payout.* webhook data, production and sandbox. Add fee_provider_cents once to get fee_cents; do not add fee_partner_cents again.

Changes

No recorded changes to this operation across all 3 revisions of this API.