Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lumx.io/llms.txt

Use this file to discover all available pages before exploring further.

Build a marketplace where your platform takes a cut on every transaction and pays sellers anywhere in the world. Each seller is onboarded as a customer. This guide covers two scenarios depending on how buyers pay your platform. In scenario A, your marketplace runs the checkout and buyers pay in their local currency via instant local rails. The marketplace fee is taken on the way in, and the seller’s wallet receives stablecoin net of the fee. See Coverage for supported rails. In scenario B, sellers earn outside your marketplace and receive USD payouts from external platforms like Amazon or Shopify into a USD virtual account issued by a Lumx banking partner. They then off-ramp to their local currency. Both scenarios share the same setup (steps 1–3) and the same final seller payout (step 6).

​
Step 1: Generate your API key

Head over to dashboard.lumx.io. Once logged in, generate a new API key and store it securely. See Authentication for details.

​
Step 2: Create your marketplace partner fee

Configure once how much of every transaction the marketplace keeps and where the fee should be sent. The walletAddress is the marketplace’s own wallet. Rates are in basis points (e.g., "500" = 5%).
Request
curl -X POST https://api-sandbox.lumx.io/partner-fees \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Marketplace platform fee",
    "walletAddress": "0x76b74209f3542d172ca1575b5b18064594360299",
    "fees": {
      "onRamp": { "rate": "500", "flatAmount": "0" },
      "offRamp": { "rate": "500", "flatAmount": "0" }
    }
  }'
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174004",
  "name": "Marketplace platform fee",
  "walletAddress": "0x76b74209f3542d172ca1575b5b18064594360299",
  "fees": {
    "onRamp": { "rate": "500", "flatAmount": "0" },
    "offRamp": { "rate": "500", "flatAmount": "0" }
  },
  "createdAt": "2026-05-16T12:00:00Z"
}
Store the returned id. You’ll reference it on every transaction. See Partner Fees for the full schema.

​
Step 3: Onboard each seller

For each seller that lists on your marketplace, create a customer: individual for sole proprietors, business for incorporated sellers. They must accept Lumx’s terms of service (POST /customers/{id}/tos) and complete identity verification before they can receive funds. If your sellers will receive USD payouts from external platforms (Scenario B), provision a USD virtual account on the same call by passing accounts: ["USD"]. Sellers who only sell through your local checkout (Scenario A) don’t need an account; incoming on-ramps credit their wallet directly.
Request
curl -X POST https://api-sandbox.lumx.io/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "BUSINESS",
    "legalName": "Star Trading Ltd.",
    "taxId": "1234567",
    "incorporationDate": "2017-09-20",
    "country": "HKG",
    "email": "finance@startrading.hk",
    "accounts": ["USD"]
  }'
See Create a customer for the full payload reference and Business verification / Individual verification for the full onboarding flow.

​
Scenario A: local checkout for global sellers

Use this flow when your marketplace runs the checkout itself and buyers pay you in their local currency. PIX (BRL) and SPEI (MXN) are the two realistic rails: instant, push-based, and the way buyers already expect to pay online in those countries.

​
Step 4A: Create a checkout for each sale

When a buyer is ready to pay a seller, create an on-ramp transaction on the seller’s behalf, referencing your partnerFeeId. The response includes the payment details (a PIX brCode or a SPEI CLABE) which you display in your checkout flow. Use purpose: "TRADE_TRANSACTIONS" for goods and services sales.
Request
curl -X POST https://api-sandbox.lumx.io/transactions/on-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "rail": "PIX",
    "sourceCurrency": "BRL",
    "sourceAmount": "250.00",
    "targetCurrency": "USDC",
    "purpose": "TRADE_TRANSACTIONS",
    "partnerFeeId": "123e4567-e89b-12d3-a456-426614174004"
  }'
For products with prices fixed in stablecoin, fetch a locked exchange rate first and pass exchangeRateId instead of sourceAmount. The buyer is shown an exact local-currency amount and the conversion settles at that rate. See Exchange Rates.

​
Step 5A: Settle the buyer payment

When the buyer pays the returned instructions, the transaction follows this lifecycle: AWAITING_FUNDS → TRANSFERRING_FIAT → TRADING → TRANSFERRING_STABLECOIN → SUCCESS On SUCCESS, the seller’s wallet receives stablecoin net of your fee, and your marketplace wallet receives the partner fee, both in the same flow, no extra API call needed. Subscribe to onramp.success and onramp.failed webhooks to mark the order as paid in your marketplace and unlock fulfillment. See Webhooks.

​
Scenario B: USD collection from external platforms

Use this flow when sellers earn on platforms outside your marketplace (Amazon, Shopify, Etsy, foreign clients on wire) and your product gives them a USD virtual account (issued by a Lumx banking partner) to receive those payouts. Once the wallet is funded, the seller off-ramps to their local currency.

​
Step 4B: Create an on-ramp for each expected payout

For every payout the seller is expecting from Amazon, Shopify or another payer, create an on-ramp transaction with the exact amount of that payout. The response returns ACH and wire instructions the seller pastes into the external platform’s payout settings. When the deposit matches the amount, Lumx converts USD to stablecoin and credits the seller’s wallet.
Request
curl -X POST https://api-sandbox.lumx.io/transactions/on-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "rail": "ACH",
    "sourceCurrency": "USD",
    "sourceAmount": "8500.00",
    "targetCurrency": "USDC",
    "purpose": "TRADE_TRANSACTIONS",
    "partnerFeeId": "123e4567-e89b-12d3-a456-426614174004"
  }'
Each payout must be matched to an on-ramp transaction created in advance with the exact amount, suited to sellers who know what they’re expecting (Amazon order settlements, invoice payments).
Subscribe to onramp.success and onramp.failed to know when payouts land or fail. For the full on-ramp flow by rail, see Global accounts.

​
Step 6: Settle to the seller’s destination

This step applies to both scenarios. Before a seller can cash out, register their own destination with holder.relationship: "SELF". Local sellers receive in their home currency; sellers in jurisdictions Lumx doesn’t settle in receive USD via SWIFT.
Sellers in jurisdictions outside Lumx’s settlement currencies (e.g., Hong Kong, Singapore) receive USD via SWIFT into their local USD-denominated account. See Coverage for the full list of supported settlement currencies and rails.
Request
curl -X POST https://api-sandbox.lumx.io/destinations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Café Verde - Payout Account",
    "rail": "PIX",
    "currency": "BRL",
    "identifier": {
      "keyType": "CNPJ",
      "keyValue": "42.887.120/0001-00"
    },
    "holder": {
      "type": "BUSINESS",
      "relationship": "SELF",
      "legalName": "Café Verde Ltda.",
      "taxId": "42.887.120/0001-00",
      "incorporationDate": "2020-01-01",
      "email": "owner@cafeverde.com.br",
      "address": {
        "line1": "Rua Voluntários da Pátria 89",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postalCode": "22270-000",
        "country": "BRA"
      }
    }
  }'
Once the destination is approved, trigger the off-ramp. Use purpose: "PERSONAL_ACCOUNT" since the seller is moving funds to their own account. Include partnerFeeId only if your marketplace charges a separate withdrawal fee; in Scenario A the platform fee was already collected on the on-ramp, so applying it again here would double-charge the seller.
Request
curl -X POST https://api-sandbox.lumx.io/transactions/off-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destinationId": "e80d3137-eddd-4791-b9b8-6e36b289f284",
    "sourceCurrency": "USDC",
    "sourceAmount": "237.50",
    "purpose": "PERSONAL_ACCOUNT"
  }'

Partner Fees

Configure platform fees on on-ramp and off-ramp transactions.

Transactions

On-ramp lifecycle, purpose codes and rails.

Exchange Rates

Lock FX rates for stablecoin-priced catalogs.

Destinations

Seller withdrawal destinations.