# Integrate Lunium with ChatGPT or a coding agent

English revision: 2026-09-21. Start with the [integration manual](/en/manual), [English API reference](/en/) and [sandbox guide](/en/sandbox). Machine-readable integration plan: [integration.json](/integration.json).

**Join [Lunium Partners](https://t.me/+FerOZMRRP_g5MDk5), the official integrator community.** Participation is strongly recommended for technical and operations owners, with operational notices, maintenance, API changes and partner discussions. It complements a dedicated project support group; it is not a requirement to create a sandbox key.

## Start inside ChatGPT

Eligible accounts or workspaces can connect a remote MCP app through the developer features available to them. Availability and menu labels depend on the account and workspace policy. Consult the [official connection instructions](https://developers.openai.com/plugins/deploy/connect-chatgpt).

1. Enable Developer Mode in ChatGPT settings if available to your account.
2. Add **Lunium — integration** using `https://api.luniumpay.com/mcp/onboarding`. This public connection requires no authentication.
3. Review the tools and add the connection to the conversation. Example request: “Plan a Lunium integration for receiving PIX into BRL custody using Node.js. Run a sandbox demo and prepare the code for my project.”
4. The agent calls `lunium_plan_integration`, starts `lunium_start_sandbox_demo` with a stable UUID and `flow` set to `custody`, `cashin`, `payout` or `cashout`, then tracks `lunium_get_sandbox_demo`. A successful demo reaches `COMPLETED` without moving funds.
5. Continue with the code kit and production checklist. For human assistance, provide your contact email and authorize `lunium_contact`. This contact step is optional.

The public connection supports planning, catalog discovery, synthetic tests and consented contact. It does not link production accounts through OAuth. The complete MCP endpoint at `/mcp` also provides account tools for hosts that securely configure `X-API-Key`. Do not paste a production key into chat.

An MCP endpoint does not automatically create a listing in ChatGPT's app directory. If your account cannot add the connection, use the coding-agent instructions and starter kit below.

## Start with any coding assistant

[Download the English kit](/en/starter/lunium-starter.zip). Run `node sandbox.mjs all` with Node 20+ or `python3 sandbox.py all` with Python 3.9+. No third-party libraries are required. The scripts create an in-memory test key, run the selected flows and reject production credentials. Reuse a `lun_test_` key through the backend environment variable `LUNIUM_API_KEY` if needed.

The kit's `AGENTS.md` gives integration guidance to a coding agent and complements your project's own instructions. Code: [Node.js](/en/starter/sandbox.mjs) · [Python](/en/starter/sandbox.py) · [cURL](/en/starter/curl.md).

Copy this briefing into your project:

> Integrate Lunium into this codebase for PIX collection into BRL custody. Read https://docs.luniumpay.com/en/manual and https://docs.luniumpay.com/en/openapi.json. Begin with a sandbox key and preserve the existing project architecture. Use destino=saldo, a stable external_id for each business intent and customer_ref for the end-customer subaccount. Configure and verify the webhook receiver before simulating payment. Distinguish the website demo, the local example, our backend processing an event and the first authorized production operation. Keep secrets server-side and explain which checks remain before production.

## Choose the business flow

- **Receive PIX into custody:** `POST /cashin/charge` with `destino: "saldo"`. Credit is in BRL; no fixed wallet is required. `payer_tax_number` identifies the actual PIX payer. `customer_ref` selects the subaccount.
- **Withdraw custody as crypto:** read available `/saldo`, query `/cashin/catalog`, then select the asset, `chain`, wallet and required memo. Call `POST /saldo/sacar-cripto`. Check `entregavel` and limits before offering a route.
- **Receive PIX with direct crypto delivery:** use `destino: "cripto"`, the delivery catalog and `POST /cashin/preview` before creating the charge.
- **Convert external crypto into PIX:** read `/catalog`, create `POST /cash-outs`, accept the quote, deposit and track the order. Sandbox simulates the deposit.
- **Send a PIX payout:** check `/keys/me`, available balance and fees in `/saldo`, then create `POST /payouts` and track its identifier.

For cash-in and crypto withdrawal, the network field is `chain`; for cash-out it is `network`. Fields ending in `_cents` use integer BRL cents. Cash-out `brl_amount` and crypto `amount` use decimal strings: consult the schema for each operation. Never translate API field names or enum values into English.

## What testing proves

Sandbox covers incoming PIX, custody credits, crypto withdrawals and deliveries, PIX payouts, internal transfers and cash-out. The QR is not bank-payable: confirm it through `POST /sandbox/cashin/{cashin_id}/pay`. All funds are simulated. See the [sandbox guide](/en/sandbox) for failures, holds, insufficient funds, uncertain results, signed webhooks and production differences.

The public demo uses fixed synthetic data. It does not accept a production wallet, PIX key, amount or credential. Demo identifiers expire after two hours; fictitious financial state survives restarts, while cash-out has two-hour retention. Reuse `request_id` on retries and `demo_id` for tracking. Demo completion alone does not prove that your application's receiver processed an event.

## Production credentials and activation

The standard self-service path uses `POST /keys/sandbox` for tests and `POST /keys` for a separate production key. BRL custody does not require a fixed wallet. The website's production form asks for business and legal-representative details; international businesses can provide their country and tax identification. These identify the business, not the Brazilian payer of a PIX charge.

Mesh is an additional agent-onboarding path. It uses its own registration, sandbox validation, supported settlement address and mandate prerequisites before automatic policy-based activation. Follow the [agent activation guide](/en/agent-onboarding); do not assume that testing an unrelated sandbox key satisfies Mesh validation.

For either path, check the actual live key's permissions, fees, minimums, available balance, holds and recipient details. Implement persistent idempotency, unchanged retry bodies, raw-body HMAC verification, timestamp checks, durable webhook storage and event deduplication. After a timeout, reconcile the original operation.

Cash-in completes with `status=paid` AND `settlement_status=sent`; cash-out with `state=COMPLETED`; payout with `status=sent`. Do not treat `delayed` as a failed payment. Keep all credentials on the backend and stay within the owner's authorization for the first real operation.

## Human support and live operations

**A dedicated human support group is strongly recommended.** Lunium or the partner can create it and add [@luniumb2b](https://t.me/luniumb2b), [@luniumb2c](https://t.me/luniumb2c) and [@LuniumNotifyBot](https://t.me/LuniumNotifyBot). Read the [group setup guide](/en/manual#telegram).

The [partner dashboard](https://parceiros.luniumpay.com/entrar) provides authenticated access for your team. Keep dashboard login, API key, private monitor token and webhook secrets distinct. Implement your own authenticated live view using [webhooks and reconciliation](/en/manual#monitor-ao-vivo), and never expose project-wide secrets to end customers.

## Fees, recovery and incidents

Read the [commission guide](/en/manual#comissoes), [access recovery](/en/manual#recuperar-acesso) and [incident runbook](/en/manual#incidentes). Fable and other agents can also consult [operations-playbook.json](/operations-playbook.json). Do not deduct fees twice or create another payment after a lost response. Recovering dashboard or monitor access does not recover a lost API key. Use only API routes actually published and available to your account. Historical product measurements are not current prices or guaranteed settlement times.