---
title: "Send a PIX directly (no crypto leg)"
method: POST
path: "/payouts"
---

# Send a PIX directly (no crypto leg)

`POST /payouts`

## Request

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

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.

## Request body

- object
  - `amount_cents` integer, 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_key` string, 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_number` string: 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_name` string: 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_id` string: 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_ref` string: 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.
  - `sandbox_scenario` 'success' | 'delayed' | 'held' | 'expired' | 'refunded' | 'failed' | 'payer_mismatch' | 'settlement_failed' | 'settlement_uncertain' | 'route_unavailable' | 'provider_unavailable': 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 `200`

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

- Payout: Saque PIX (PIX→PIX) debitado do saldo custodial da chave.
  - `payout_id` string
  - `customer_ref` string, nullable
  - `status` string: processing, sent, failed ou refunded; use extrato para conciliar saldo. Estados novos devem ser tolerados.
  - `amount_cents` integer: Valor que o destinatário recebe.
  - `fee_cents` integer, nullable: Total fees beyond amount_cents: fee_service_total_cents + fee_provider_cents. Includes partner commission already; do not add it again.
  - `fee_service_cents` integer, nullable: Lunium-only service fee in recorded cents; accounting component. For customer UI and notifications use fee_service_total_cents.
  - `fee_provider_cents` integer, nullable: Tarifa do provedor: fee_cents menos fee_service_cents menos fee_partner_cents.
  - `pix_key` string
  - `pix_key_type` 'cpf' | 'cnpj' | 'phone' | 'email' | 'random'
  - `tax_number` string, nullable: Documento do beneficiário mascarado, quando informado; opcional no pedido.
  - `external_id` string, 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.
  - `error` string, nullable: Motivo quando failed/refunded.
  - `e2e` string, nullable: EndToEndId do PIX enviado.
  - `receiver_name` string, nullable: Nome obtido após o pagamento quando disponível. null quando não obtido.
  - `receiver_tax_number` string, nullable
  - `paid_at` string, date-time, nullable
  - `sent_at` string, date-time, nullable
  - `verify_url` string, nullable: Verificação pública do PIX (GET /v1/verificar/{e2e}).
  - `created_at` string, date-time, nullable
  - `updated_at` string, date-time, nullable
  - `sandbox` boolean: True for fictitious sandbox operations.
  - `simulation` object
  - `fee_partner_cents` integer, nullable: Sub fee do parceiro debitada do saldo neste saque (centavos). Parte de fee_cents.
  - `fee_service_total_cents` integer, 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.

## Other responses

- `400`: Recusa ou falha; leia erro, acao e detail quando presentes.
- `401`: X-API-Key ausente, desconhecida ou incorreta.
- `402`: Recusa ou falha; leia erro, acao e detail quando presentes.
- `403`: Administrative kill switch or `custodia_desligada`. Production keys are enabled by default; if this response appears, stop and contact support instead of retrying. No PIX was sent.
- `409`: external_id_divergente ou external_id_nao_verificavel: consulte payout_id/recovery_endpoint da operação original. Não altere parâmetros nem gere novo ID para a mesma intenção. em_processamento: consulte a ordem em andamento, sem reenviar um novo pagamento.
- `423`: carencia_primeiro_deposito — first-deposit hold (only keys with a contractual holding period; none by default since 2026-09-16): no withdrawal for this sub-account until `libera_em`.
- `500`: Recusa ou falha; leia erro, acao e detail quando presentes.
- `503`: saque_indisponivel: financiamento/provedor indisponível; nenhuma nova reserva ou débito é feito nesta tentativa. idempotencia_indisponivel: não foi possível conferir a ordem anterior; nenhuma nova ordem é criada, mas a anterior pode existir. Aguarde e consulte o mesmo external_id; não gere outro ID.

---

[API](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil.md) · [All operations](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/llms.txt) · [OpenAPI document](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/revisions/0b5a340fa9dd?raw)