You are a senior full-stack engineer adding a stablecoin checkout to an existing app on Lumx: the buyer pays in local currency and the merchant receives stablecoin. Lumx has no hosted checkout, widget or payment link, so you build the payment page inside this app. Do not look for one and do not invent an endpoint.
Ground truth. Read all three before writing any code and follow them over any prior knowledge:
1. https://docs.lumx.io/llms.txt — the documentation index. Every page has a .md twin at its own path.
2. https://lumx-docs-public-prod.s3.us-east-1.amazonaws.com/api-production.yaml — the OpenAPI 3.1 spec. Take field names, required flags and enum values from here.
3. https://docs.lumx.io/get-started/coverage.md — the live rails. A rail marked with a quarter is not live: leave it out.
Work against sandbox at https://api-sandbox.lumx.io with a server-side key sent as "Authorization: Bearer <key>". The key never reaches the browser: the payment page calls your backend.
1. Settle whose checkout this is. If the app sells its own goods, its company is one Lumx customer. If it sells for merchants, each merchant is its own customer in APPROVED status and each order is created for that merchant's customerId. Funds for a merchant Lumx has not onboarded are nesting; read /compliance/nested-payments and stop if the design needs it.
2. Enable rails through the "accounts" array of POST /customers: BRL for PIX, MXN for SPEI, USD for ACH and FEDWIRE, EUR for SEPA, GBP for FPS. GBP is optional, so make it a setting. Show a rail at checkout only when GET /accounts?customerId={id} reports that currency ACTIVE.
3. Create one POST /transactions/on-ramp per order with rail, sourceCurrency, sourceAmount as a decimal string, targetCurrency, a purpose from the request enum that describes the sale, blockchain, optional partnerFeeId, and metadata carrying your order id. Send an Idempotency-Key tied to the order and stored before sending.
4. Choose the price lock and record why. A floating on-ramp expires after 1 day on PIX and SPEI and 7 days on other rails. A locked one, from POST /exchange-rates with timelock 30s, 1m or 5m, expires with its quote, so use it only when the payer pays while the page is open.
5. Render state.payment for the payer. Its shape follows the rail: brCode for PIX, clabe for SPEI, and an identifier with a holder for ACH, FEDWIRE, SEPA and FPS. The spec types it as a free-form object, so take field names from the on-ramp examples there and flag any you cannot find. Show a memo when one is present.
6. Mark the order paid only on onramp.success, confirmed with GET /transactions/{id}. Treat onramp.failed and onramp.expired as unpaid and create a new on-ramp for a retry. Match events on your order id, dedupe on webhook-id, and store the receipt amounts and blockExplorerUrl per order.
7. For recurring collection or a payer-chosen amount, use POST /autoconversion-rules and render sourceDepositInfo instead. BRL and MXN accounts take several rules; a USD, EUR or GBP account takes one active rule, and a second returns 409 AUTOCONVERSION_RULE_ALREADY_EXISTS. The spec has no delete, so never create a rule per order.
8. Test in sandbox: an on-ramp completes on its own, and POST /autoconversion-rules/simulate-deposit simulates a rule deposit with the depositIdentifier or reference. It returns 404 in production.
Constraints:
- A refund after success is a payout, not an endpoint. Read /concepts/destinations for the CUSTOMER relationship and flag what you cannot confirm.
- Do not state a minimum for an on-ramp or a behavior for a short or excess payment on a bank rail. None is published. Flag both.
- Do not state a rate limit. None is published. Handle 429 TOO_MANY_REQUESTS with exponential backoff.
Deliverables:
- A payment page that renders each enabled rail from live API data.
- An order service that is idempotent on your order id, with a webhook handler for the onramp.* events.
- A sandbox script that pays one order on each enabled rail and prints every status change.
- A list of every field you could not confirm in either source.
