PIX payout API

Who this is for

• A platform paying many people that today does it by spreadsheet and internet banking.
• A marketplace that needs to pay sellers with a trail and a receipt.
• An operation that already holds a BRL balance with us and wants to distribute it over API.

The problem

Mass payouts usually live outside the system: someone exports a spreadsheet, uploads it to a bank, checks it by hand and then tries to explain each line. There is no idempotency, no state, and the receipt is an image.

A payout API fixes all three at once: external_id stops double payment, the state is queryable, and the receipt is the EndToEndId — which the other side verifies on their own in the open verifier.

The flow, end to end

1. You hold a BRL balance on the key (from a PIX deposit with destino: "saldo", or from selling crypto).
2. Before paying, check the key owner with GET /pix/keys/lookup: the bank refuses a key that does not belong to the stated document.
3. POST /payouts with amount, key, type, the receiver's tax id and your external_id.
4. The operation is recorded and the balance debited in the same transaction, before any provider call — there is no debit without an order.
5. payout.sent arrives with e2e and verify_url. An explicit failure refunds the amount and the fee.

Endpoints used

A example that runs

# 1. confira o titular da chave ANTES de mandar
curl "https://api.luniumpay.com/pix/keys/lookup?key=11122233344&type=cpf" -H "X-API-Key: $LUNIUM_KEY"

# 2. envie o PIX
curl -X POST https://api.luniumpay.com/payouts -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":50000,"pix_key":"11122233344","pix_key_type":"cpf",
       "tax_number":"11122233344","beneficiary_name":"Joao P.",
       "customer_ref":"fornecedor_31","external_id":"pgto-2026-0918"}'

async function pagarPix({ cents, chave, tipo, doc, nome, ref, idempotencia }) {
  const h = { "X-API-Key": process.env.LUNIUM_KEY, "Content-Type": "application/json" };

  const titular = await (await fetch(
    `${API}/pix/keys/lookup?key=${encodeURIComponent(chave)}&type=${tipo}`, { headers: h })).json();
  if (titular.verified && titular.owner_tax_number && !bate(titular.owner_tax_number, doc)) {
    throw new Error("a chave não pertence a este CPF/CNPJ");
  }

  const r = await fetch(`${API}/payouts`, { method: "POST", headers: h, body: JSON.stringify({
    amount_cents: cents, pix_key: chave, pix_key_type: tipo,
    tax_number: doc, beneficiary_name: nome,
    customer_ref: ref, external_id: idempotencia,
  })});
  const p = await r.json();
  if (r.status === 502 && p.erro === "provedor_sem_resposta") {
    return { indefinido: true, consultar: `/payouts/${p.payout_id ?? idempotencia}` };
  }
  return p;
}

import os, requests

API, H = "https://api.luniumpay.com", {"X-API-Key": os.environ["LUNIUM_KEY"]}

def pagar_pix(cents, chave, tipo, doc, nome, ref, idempotencia):
    titular = requests.get(f"{API}/pix/keys/lookup", headers=H, timeout=20,
                           params={"key": chave, "type": tipo}).json()
    if titular.get("verified") and titular.get("owner_tax_number") and not bate(titular["owner_tax_number"], doc):
        raise RuntimeError("a chave nao pertence a este CPF/CNPJ")

    r = requests.post(f"{API}/payouts", headers=H, timeout=60, json={
        "amount_cents": cents, "pix_key": chave, "pix_key_type": tipo,
        "tax_number": doc, "beneficiary_name": nome,
        "customer_ref": ref, "external_id": idempotencia})
    p = r.json()
    if r.status_code == 502 and p.get("erro") == "provedor_sem_resposta":
        return {"indefinido": True}   # consulte, nao repita
    return p

Sandbox: test before spending

One call, no signup, no card. The lun_test_ key exercises the whole surface without moving any money.

curl -X POST https://api.luniumpay.com/keys/sandbox \
  -H "Content-Type: application/json" \
  -d '{"name":"my-test"}'

What the sandbox does not prove: real settlement. No crypto moves and no PIX is paid — it is there to get the contract right, not to measure the rail.

Assets and networks

Instant (our own rail): USDT on Polygon and USDC na Polygon — settled in seconds, no exchange in the path.

Through the exchange: 1,478 assets across 241 networks on the sell side (1,668 asset×network pairs) and 1,795 routes on the buy side. The wait is the number of confirmations each chain requires, not a choice of ours.

Shared-address networks (ALGO, ATOM, EOS, HBAR, KAVA, LUNA, TON, XLM, XRP): the deposit must carry the memo. On the sell side it comes as deposit_tag in the accept; on the buy side you send payout_tag with the address.

The catalog changes on its own as networks come and go. Read it from GET /catalog and GET /cashin/catalog instead of keeping a list in code.

Limits and holds

The ladder is per paying document, not per receiving account: ten payers are ten independent limits. That is what makes this work for e-commerce and marketplaces. Check a payer's headroom before charging with GET /cashin/limits?payer_tax=, and read your key's limits from GET /keys/me — ceilings above the tier are contracted.

Measurements, not promises

Measured in production, 90-day window, on 2026-09-07:

Off Polygon the clock is the network's: the wait is the number of confirmations the exchange requires, and it is in eta in the catalog. We do not promise "instant" off our own rail.

Idempotency

Send external_id on every money-moving call. Repeating the same call returns the same operation, never a second one; the same parameters with a different id create two, and the same id with different parameters answers 409 external_id_divergente instead of guessing.

A timeout is not a refusal. If the call did not answer, look the operation up by external_id before repeating — it may already exist.

Webhooks and reconciliation

Every transition fires an event signed with HMAC SHA-256 plus a timestamp (header X-Lunium-Signature, format t=…,v1=…) — the timestamp is what stops a captured delivery from being replayed. Verify the signature before trusting the body.

The webhook is the primary signal; polling is optional. When you do poll, the status carries a timeline stamped by the server — draw the stage from it, because your polling stopwatch measures your network, not the operation.

Did not answer 2xx? Delivery is retried with backoff. You can resend by hand at POST /webhooks/deliveries/{event_id}/retry and test your URL at POST /webhooks/test.

When it goes wrong

Insufficient balance: 402 saldo_insuficiente with available and held amounts. Nothing is debited.

No answer from the provider: 502 provedor_sem_resposta with acao: "parar". The PIX may have gone out: query GET /payouts/{id}, do not repeat. The order exists on our side even then — that is what makes reconciliation possible instead of guesswork.

Explicit bank refusal: amount and fee return to the balance, and the reason stays in error.

Sub-account's first deposit: 423 carencia_primeiro_deposito with libera_em.

Security

• webhook assinado — Todo webhook vai assinado em HMAC SHA-256 com timestamp (header X-Lunium-Signature, formato t=…,v1=…), o que impede replay de uma entrega capturada.
• idempotencia — external_id em cash-in, cash-out e payout: repetir a mesma chamada devolve a MESMA operação, nunca uma segunda. Parâmetros diferentes no mesmo external_id respondem 409.
• egress validado — A URL de webhook é resolvida e validada antes de cada entrega: endereço interno, metadata de nuvem e redirect para rede privada são recusados, e a conexão é fixada no IP validado.
• retencao fail closed — A retenção é verificada na liquidação e repetida na reivindicação SQL: nenhum caminho (worker, consulta de status, fila) consegue liquidar antes da hora.
• payout duravel — O saque grava a operação e debita o saldo na MESMA transação, antes de qualquer chamada ao provedor: não existe débito sem ordem para reconciliar.
• verificacao aberta — GET /v1/verificar/{e2e} confere um PIX liquidado sem chave nenhuma — a contraparte não precisa confiar na nossa palavra.

Open verification is the one that matters in a negotiation: your counterparty checks the PIX themselves, with no key and without taking our word for it.

Time to first integration

One call, plus the owner lookup that prevents the most common refusal. In production the PIX usually lands within a few minutes; the declared maximum is one hour.

Questions integrators ask