PIX and stablecoin for wallets and apps

Who this is for

• A wallet or app already published, replacing its current Brazilian on/off-ramp.
• A product that needs deposit and withdrawal in one integration, not two vendors.
• A team that wants to show the user where the operation is, not just a spinner.

The problem

In a wallet app, the deposit is where users give up. They type an amount, the provider refuses without saying what would fit, and the screen shows "error". After paying, they stare at a spinner with no idea whether it is five seconds or five minutes. Those two moments cost more users than any fee.

Both have an API answer. Each payer's limit is queryable before the keypad appears, and the status carries a server-stamped timeline with the measured median of each stage — you can write "step 3 of 5, usually 39 s" without making a number up.

The flow, end to end

1. The user enters their tax id once. You call GET /cashin/limits?payer_tax= and already show how much they can deposit right now and how much fits with a hold.
2. They pick an amount. POST /cashin/charge with customer_ref (their id in your system) returns the copy-and-paste code.
3. They pay. The cashin.paid webhook arrives; the screen changes stage without polling.
4. Delivery happens and cashin.settled brings the hash. If the destination is saldo, the credit is already available.
5. To withdraw: POST /payouts (PIX) or POST /saldo/sacar-cripto (any catalog coin), always with the same customer_ref.

Endpoints used

A example that runs

# depósito do usuário: PIX identificado pelo CPF dele, cripto na carteira dele
curl -X POST https://api.luniumpay.com/cashin/charge -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":15000,"asset":"usdt","chain":"polygon",
       "payout_address":"0xCarteiraDoUsuario",
       "payer_tax_number":"12345678909",
       "customer_ref":"user_8842","external_id":"dep-8842-17"}'

# limite daquele usuário ANTES de mostrar o teclado de valor
curl "https://api.luniumpay.com/cashin/limits?payer_tax=12345678909" -H "X-API-Key: $LUNIUM_KEY"

async function limiteDoUsuario(cpf) {
  const r = await fetch(`${API}/cashin/limits?payer_tax=${cpf}`, {
    headers: { "X-API-Key": process.env.LUNIUM_KEY },
  });
  const l = await r.json();
  return { naHora: l.instant_available_cents, comRetencao: l.held_qr?.available_cents ?? 0 };
}

async function depositar({ cents, cpf, carteira, userId, idempotencia }) {
  const r = await fetch(`${API}/cashin/charge`, {
    method: "POST",
    headers: { "X-API-Key": process.env.LUNIUM_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      amount_cents: cents, asset: "usdt", chain: "polygon",
      payout_address: carteira, payer_tax_number: cpf,
      customer_ref: userId, external_id: idempotencia,
    }),
  });
  if (r.status === 403) throw new Error("acima do limite deste pagador");
  return r.json();
}

import os, requests

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

def limite_do_usuario(cpf):
    l = requests.get(f"{API}/cashin/limits", headers=H, params={"payer_tax": cpf}, timeout=20).json()
    return l["instant_available_cents"], (l.get("held_qr") or {}).get("available_cents", 0)

def depositar(cents, cpf, carteira, user_id, idempotencia):
    r = requests.post(f"{API}/cashin/charge", headers=H, timeout=30, json={
        "amount_cents": cents, "asset": "usdt", "chain": "polygon",
        "payout_address": carteira, "payer_tax_number": cpf,
        "customer_ref": user_id, "external_id": idempotencia})
    if r.status_code == 403:
        raise RuntimeError("acima do limite deste pagador")
    return r.json()

Sandbox: test before spending

One call, no prior approval, no card; only your email is required (that is where we send the manual, the flowchart and the integration steps). 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 '{"email":"you@company.com","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

Use GET /catalog for incoming crypto and GET /cashin/catalog for delivery after Pix. Asset availability, networks and minimums differ between the two directions and can change.

Send the returned deposit_tag with a deposit when required. Use payout_tag for an outgoing route that requires a memo. See the API manual for the current contract.

Limits and holds

Read account limits and fees from GET /keys/me, payer availability from GET /cashin/limits?payer_tax=... and route minimums from previews. Cash-in, cash-out and payouts have different constraints.

A received payment can be held before settlement. Track status, timeline and signed events until the final outcome; read expiry from expires_at.

Measurements, not promises

Settlement time depends on the payment flow, route availability, network confirmations and any hold. Track the final state and check service status. Sandbox timing does not measure real settlement.

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

Above the payer's limit: 403 limite_do_pagador with acao: "corrigir" and how much fits. Show the number, not the word "error" — that is what converted best in the apps already using it.

Below the route minimum: the response carries the estimated minimum in reais and nothing is debited. Offer the right amount in one tap.

A document's first deposit: the credit is available immediately; only the first PIX from a document above BRL 100.00 is held for 24 h at the provider (delayed, released on its own with saldo.liberado). Show the time, not "try later".

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

The app's critical path is two calls: limit and charge. Both exist in the sandbox with the same contract — you can build the whole screen before a commercial contract exists.

Questions integrators ask