Marketplaces

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.

PIX (BRL)
SPEI (MXN)

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"
  }'

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": "SPEI",
    "sourceCurrency": "MXN",
    "sourceAmount": "5000.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 autoconversion rule for the seller’s USD account

Once the seller’s USD account is ACTIVE, create an autoconversion rule for it, referencing your partnerFeeId. You do this once per seller: the response’s sourceDepositInfo carries the ACH, Fedwire, and SWIFT details the seller pastes into Amazon, Shopify, or any other payer’s payout settings. Every payout that lands is converted to stablecoin and credited to the seller’s wallet net of your fee, whatever the amount.

Request

curl -X POST https://api-sandbox.lumx.io/autoconversion-rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "accountId": "af04e979-360a-428a-84e6-cbd8ffc4942b",
    "targetCurrency": "USDC",
    "purpose": "TRADE_TRANSACTIONS",
    "name": "Marketplace payouts",
    "partnerFeeId": "123e4567-e89b-12d3-a456-426614174004"
  }'

Each payout must be worth at least 50 USD. A USD account holds one active rule at a time. Subscribe to onramp.success and onramp.failed to know when payouts land or fail. For the response, the deposit details per rail, and when to create a one-off on-ramp instead, 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"
      }
    }
  }'

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": "Tienda Sol - Payout Account",
    "rail": "SPEI",
    "currency": "MXN",
    "identifier": {
      "keyType": "CLABE",
      "keyValue": "012180001234567899"
    },
    "holder": {
      "type": "BUSINESS",
      "relationship": "SELF",
      "legalName": "Tienda Sol S.A. de C.V.",
      "taxId": "TSO200115ABC",
      "incorporationDate": "2020-01-15",
      "email": "owner@tiendasol.mx",
      "address": {
        "line1": "Calzada de Tlalpan 3465",
        "city": "Mexico City",
        "state": "CDMX",
        "postalCode": "04650",
        "country": "MEX"
      }
    }
  }'

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": "Acme Goods - Payout Account",
    "rail": "ACH",
    "currency": "USD",
    "identifier": {
      "type": "CHECKING",
      "accountNumber": "123456789012",
      "routingNumber": "021000021"
    },
    "bank": {
      "name": "JPMorgan Chase Bank",
      "address": {
        "line1": "383 Madison Avenue",
        "city": "New York",
        "state": "NY",
        "postalCode": "10179",
        "country": "USA"
      }
    },
    "holder": {
      "type": "BUSINESS",
      "relationship": "SELF",
      "legalName": "Acme Goods Inc.",
      "taxId": "12-3456789",
      "incorporationDate": "2018-06-01",
      "email": "owner@acmegoods.com",
      "address": {
        "line1": "100 Wall Street",
        "city": "New York",
        "state": "NY",
        "postalCode": "10005",
        "country": "USA"
      }
    }
  }'

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": "Boutique Paris - Payout Account",
    "rail": "SEPA",
    "currency": "EUR",
    "identifier": {
      "iban": "FR1420041010050500013M02606",
      "bic": "BNPAFRPP"
    },
    "bank": {
      "name": "BNP Paribas",
      "address": {
        "line1": "16 Boulevard des Italiens",
        "city": "Paris",
        "state": "IDF",
        "postalCode": "75009",
        "country": "FRA"
      }
    },
    "holder": {
      "type": "BUSINESS",
      "relationship": "SELF",
      "legalName": "Boutique Paris SAS",
      "taxId": "98765432100015",
      "incorporationDate": "2019-04-10",
      "email": "owner@boutiqueparis.fr",
      "address": {
        "line1": "45 Avenue Montaigne",
        "city": "Paris",
        "state": "IDF",
        "postalCode": "75008",
        "country": "FRA"
      }
    }
  }'

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": "London Goods - Payout Account",
    "rail": "FPS",
    "currency": "GBP",
    "identifier": {
      "sortCode": "040509",
      "accountNumber": "00125977"
    },
    "bank": {
      "name": "Mock Bank",
      "address": {
        "line1": "1 Bank Street",
        "city": "London",
        "state": "LND",
        "postalCode": "EC1A 1BB",
        "country": "GBR"
      }
    },
    "holder": {
      "type": "BUSINESS",
      "relationship": "SELF",
      "legalName": "London Goods Ltd",
      "taxId": "1234567890",
      "incorporationDate": "2018-09-03",
      "email": "owner@londongoods.co.uk",
      "address": {
        "line1": "221 Baker Street",
        "city": "London",
        "state": "LND",
        "postalCode": "NW1 6XE",
        "country": "GBR"
      }
    }
  }'

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": "Star Trading HK - Payout Account",
    "rail": "SWIFT",
    "currency": "USD",
    "identifier": {
      "accountNumber": "399876543210",
      "bic": "HSBCHKHHXXX"
    },
    "bank": {
      "name": "HSBC Hong Kong",
      "address": {
        "line1": "1 Queen's Road Central",
        "city": "Hong Kong",
        "state": "Hong Kong",
        "postalCode": "999077",
        "country": "HKG"
      }
    },
    "holder": {
      "type": "BUSINESS",
      "relationship": "SELF",
      "legalName": "Star Trading Ltd.",
      "taxId": "1234567",
      "incorporationDate": "2017-09-20",
      "email": "finance@startrading.hk",
      "address": {
        "line1": "23 Queen's Road Central, Suite 1801",
        "city": "Hong Kong",
        "state": "Hong Kong",
        "postalCode": "999077",
        "country": "HKG"
      }
    }
  }'

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.

Use Cases

Onboarding

Collect

Pay out

Build with AI

Marketplaces

Step 1: Generate your API key

Step 2: Create your marketplace partner fee

Step 3: Onboard each seller

Scenario A: local checkout for global sellers

Step 4A: Create a checkout for each sale

Step 5A: Settle the buyer payment

Scenario B: USD collection from external platforms

Step 4B: Create an autoconversion rule for the seller’s USD account

Step 6: Settle to the seller’s destination

Partner Fees

Transactions

Exchange Rates

Destinations

​Step 1: Generate your API key

​Step 2: Create your marketplace partner fee

​Step 3: Onboard each seller

​Scenario A: local checkout for global sellers

​Step 4A: Create a checkout for each sale

​Step 5A: Settle the buyer payment

​Scenario B: USD collection from external platforms

​Step 4B: Create an autoconversion rule for the seller’s USD account

​Step 6: Settle to the seller’s destination

​Related resources

Partner Fees

Transactions

Exchange Rates

Destinations

Step 1: Generate your API key

Step 2: Create your marketplace partner fee

Step 3: Onboard each seller

Scenario A: local checkout for global sellers

Step 4A: Create a checkout for each sale

Step 5A: Settle the buyer payment

Scenario B: USD collection from external platforms

Step 4B: Create an autoconversion rule for the seller’s USD account

Step 6: Settle to the seller’s destination

Related resources