Two different routes that are easy to confuse: where the money of the operation goes, and where the crypto returns if the operation cannot complete.
POST https://api.luniumpay.com/mesh/agents/{agent_id}/settlement
X-API-Key: lun_live_…
{"settlement_address": "0x…"}It is a requirement for production: with no settlement route, the money has nowhere to go. The network must be a supported one — an address on a network that does not exist is an order that never arrives.
refund_address on each orderA different thing, and the most important one to get right. It is your user’s wallet, on the same network as the deposit — where the crypto returns if the PIX cannot be paid.
refund_address, the refund goes to the on-chain origin of the deposit. When the user withdrew from an exchange, that origin is the exchange’s wallet — and their money does not come back to them. Always send it.| Situation | Outcome |
|---|---|
| PIX key refused after the deposit | The crypto returns to custody and goes on to refund_address. State REFUNDED, with refund_tx_hash. |
| Failure before sending to the settlement provider | Retried every 5 min for up to 45 min. If it does not settle, the full amount is returned — fee included. |
| Deposit differs from the quote | What was actually received is paid, re-quoted at settlement. |
Deposit after expires_at | The order revives when the deposit shows up, for up to 7 days. |
There are only two terminal outcomes with money: COMPLETED (the PIX went out, with an E2E) or REFUNDED (the crypto came back, with a hash). Never a silent third state.
Changing it requires the agent’s own key. The agent_id identifies, it does not authorise — if it did both, anyone could redirect someone else’s settlement, which is the most direct way to steal money in this design.