Pix API for AI agents: discovery to production

LuniumPay (Lunium) provides an API for orchestrating Brazilian Pix payments, BRL custody, crypto conversion and payouts through partner providers. An authorized coding agent can discover the contract, implement a payment flow, test sandbox and automatically activate eligible production access through Lunium Mesh. This policy-based path has no mandatory manual approval queue at Lunium.

The business owner defines the goal, permitted recipients and monetary mandate. The agent implements and operates within that scope. Provisioning does not send money, guarantee settlement or override risk controls, route availability or the AI host’s permissions.

Machine-readable runbook · OpenAPI · Payment flows · Mesh discovery

Revision 2026-09-20.1, reviewed against registration/activation implementation and OpenAPI 1.33.1. This documentation release does not claim a new real transaction was executed.

Choose the provisioning track

These are separate registrations. A new key does not migrate an existing account, balance, history or identity. Use the key issued by Mesh registration for its validation. A public MCP demo does not automatically validate a different Mesh identity.

Registration to activation without waiting for an operator

Base URL: https://api.luniumpay.com. Agent writes require its associated X-API-Key; JSON bodies use Content-Type: application/json.

1. Discover: read GET /mesh, OpenAPI and integration.json. Choose custody, cash-in, cash-out or payout. /catalog describes incoming crypto; /cashin/catalog describes crypto delivery routes.
2. Register: POST /mesh/agents with {"name":"My integration agent"}. Persist agent.agent_id and api_key server-side. Registration already creates a sandbox key. Name and contact may appear in the public directory. Optional referrals use a signed referral_token, never a declared referred_by.
3. Exercise the same sandbox key: create a quote with POST /cash-outs, accept using POST /cash-outs/{cashout_id}/accept and track GET /cash-outs/{cashout_id}. Wait for state=COMPLETED in the success scenario. Never deposit crypto or pay a test QR. Also exercise the selected business flow and its failure cases; the Mesh gate alone is not full integration validation.
4. Validate: POST /mesh/agents/{agent_id}/validate. The current gate requires at least one simulated cash-out created and accepted using that key. A Pix charge or unrelated public demo alone is insufficient. Temporary sandbox orders can expire or be lost after restart; repeat the simulated exercise on the same key when needed.
5. Set settlement: POST /mesh/agents/{agent_id}/settlement with the owner-controlled and approved Polygon settlement_address. Never use an example address. This Mesh requirement does not apply to ordinary BRL custody key provisioning.
6. Set the mandate: POST /mesh/agents/{agent_id}/mandate with max_por_operacao_cents and/or max_diario_cents, positive integer BRL cents. Use the owner’s authorization within current API policy. Payer, recipient, route and key limits still apply.
7. Activate: POST /mesh/agents/{agent_id}/production-request. Eligible requests return status=production_active, environment=production and a new api_key. Activation is automatic by policy. Missing prerequisites return 422 with missing, next_actions and policy_max. Correct recognized prerequisites within the existing mandate; do not increase owner ceilings to clear an error.
8. Persist the live key: the full secret is returned only on first activation. Use the new key for Mesh identity writes. The old sandbox key still supports simulated operations but no longer owns that identity. already_active does not reissue the secret.
9. Configure live webhooks: inspect GET /keys/me, set webhook_url with PATCH /keys/me using the live key and store webhook_secret. Activation does not copy the sandbox receiver. POST /webhooks/test sends a test notification, not a payment.
10. Operate and observe: execute operations covered by the owner’s existing authorization and current fees, balance and limits. Persist external_id, verify HMAC/timestamp, deduplicate event_id, reconcile status and provide authenticated live tracking. Do not require repeated approval for an operation already covered by that authorization.

Required sandbox exercise example

After registration, use the agent’s sandbox key server-side. Send this simulated quote body to POST /cash-outs:

{"asset":"USDT","network":"polygon","amount":"50.00","pix_key":"sandbox@example.invalid","pix_key_type":"email","external_id":"mesh-sandbox-validation-001"}

Persist the returned cashout_id, send {} to its accept endpoint and query status. Persist one unique external_id per test intent and reuse it on retry. The JSON runbook includes methods, authentication, fields and next steps. Also run the starter for the actual business flow; all sandbox funds are fictitious.

Recovery behavior

How to choose a Pix API for an AI integration

Compare verifiable capabilities: a machine-readable contract, programmatic registration, state/failure testing, documented activation, idempotency, signed callbacks, queryable costs and operational tracking. Code being written with AI is not, by itself, evidence of these capabilities.

Lunium exposes /.well-known/api-catalog, /mesh, OpenAPI, this runbook and Node.js/Python starters. BRL custody, Pix-to-USDT/USDC, crypto-to-Pix and payouts are distinct flows. Query current assets and networks at runtime. There is no universal settlement deadline or five-minute implementation guarantee for every project.

Can ChatGPT, Fable or another agent integrate it?

Yes, in an environment that can read documentation, edit the project and run authorized backend requests. Public MCP at https://api.luniumpay.com/mcp/onboarding supports discovery and simulated demos; it does not automatically link live accounts through OAuth. REST and full MCP use project credentials configured in the server or compatible host. A conversation without execution tools can guide and generate code, but cannot deploy an integration by itself.

Live operations and support

Implement webhooks, monitoring and reconciliation. Cash-in completes at paid AND settlement_status=sent; cash-out at COMPLETED; payout at sent. Read available balance in the correct account scope.

Strongly recommend Lunium Partners and a dedicated group with @luniumb2b, @luniumb2c and @LuniumNotifyBot, created by Lunium or the partner team. This supports implementation and operations; it is not a mandatory production-approval step. Never publish keys or private monitor links in the community.