PIX to USDT API

Who this is for

• A product already selling in Brazil that wants the money in stablecoin instead of a bank account.
• A company abroad that needs to accept PIX in Brazil, through an API integration with checks proportional to volume.
• A team replacing an on-ramp with one that has an open contract, a one-call sandbox and verifiable receipts.

The problem

Accepting PIX and ending up with stablecoin usually takes three parts that do not talk to each other: an acquirer for the PIX, a Brazilian bank account for the money to land in, and an exchange to convert. Each with its own onboarding, its own limit and its own reconciliation — with the money idle in between.

Here it is one call. The PIX comes in, the conversion happens, and the crypto goes out to the wallet you named. There is no balance waiting to be withdrawn and no manual step in the middle.

The flow, end to end

1. You call POST /cashin/charge with the amount, asset, network, your wallet and the payer's tax id.
2. The response carries qr_copypaste: that is the PIX you show the customer. It is valid for 15 minutes.
3. The customer pays in their bank. The cashin.paid webhook arrives.
4. Conversion and delivery happen on their own. cashin.settled arrives with the on-chain hash.
5. Need to check? GET /cashin/{cashin_id}/status carries a server-stamped timeline.

Endpoints used

A example that runs

curl -X POST https://api.luniumpay.com/cashin/charge \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 25000,
    "asset": "usdt",
    "chain": "polygon",
    "payout_address": "0xSuaCarteira",
    "payer_tax_number": "12345678909",
    "external_id": "pedido-7781"
  }'

const r = await fetch("https://api.luniumpay.com/cashin/charge", {
  method: "POST",
  headers: { "X-API-Key": process.env.LUNIUM_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    amount_cents: 25000,
    asset: "usdt",
    chain: "polygon",
    payout_address: "0xSuaCarteira",
    payer_tax_number: "12345678909",
    external_id: "pedido-7781",
  }),
});
const cobranca = await r.json();
console.log(cobranca.cashin_id, cobranca.qr_copypaste);

import os, requests

r = requests.post(
    "https://api.luniumpay.com/cashin/charge",
    headers={"X-API-Key": os.environ["LUNIUM_KEY"]},
    json={
        "amount_cents": 25000,
        "asset": "usdt",
        "chain": "polygon",
        "payout_address": "0xSuaCarteira",
        "payer_tax_number": "12345678909",
        "external_id": "pedido-7781",
    },
    timeout=30,
)
cobranca = r.json()
print(cobranca["cashin_id"], cobranca["qr_copypaste"])

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

The PIX is paid by a different document than the one declared: the charge is refunded to the payer and the status carries refund_reason. Nothing is delivered to the wrong owner.

The settlement provider goes down: POST /cashin/charge answers 502 provedor_indisponivel with acao: "repetir". No charge is created in that case — repeat the same call with the same external_id.

The customer did not pay in time: the charge becomes expired and nothing happens. Create another.

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

From zero to the first QR: one call for the sandbox key and one for the charge. The integrators who arrived through search did it in minutes, without talking to anyone.

For production you need a production key and a webhook URL. The rest of the code does not change: the sandbox uses the same contract, the same fields and the same errors.

Questions integrators ask