Skip to main content
Enable your customers to receive payments worldwide through local payment rails. You choose which currencies each customer should have an account in. To receive a payment, you create an on-ramp transaction with the exact amount of the expected deposit. Lumx returns rail-specific payment details; when the deposit matches, the funds are converted to stablecoin and credited to the customer’s wallet. See Coverage for the supported currencies and rails.

​
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 a customer with the accounts you need

Send a POST /customers request including an accounts array with the currencies you want to provision. Each currency triggers a virtual account that enters verification alongside the customer.
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": "INDIVIDUAL",
    "name": "William Default",
    "taxId": "123.456.789-00",
    "birthDate": "1990-01-01",
    "country": "BRA",
    "email": "william.default@example.com",
    "accounts": ["BRL", "USD", "EUR", "MXN"]
  }'
Response
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "INDIVIDUAL",
  "verification": {
    "status": "NOT_STARTED",
    "level": "STANDARD",
    "link": "https://in.sumsub.com/websdk/p/sbx_aA00bB11cC33dD44"
  }
}
The wallets array is only returned once the customer’s verification status is APPROVED. Subscribe to the customer.approved webhook or call Read a customer to retrieve wallets after approval.
See Create a customer for the full payload reference, including business customers. The list of supported currencies and rails is in Coverage.

​
Step 3: Collect ToS acceptance and KYC

Before the customer can transact, they must accept Lumx’s terms of service and complete identity verification. Generate a ToS acceptance link and share it with the customer:
Request
curl -X POST https://api-sandbox.lumx.io/customers/{customerId}/tos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrl": "https://yourapp.com/onboarding/next-step"
  }'
Response
{
  "url": "https://dashboard.lumx.io/tos/eyJhbGciOiJSUzI1...",
  "expiresAt": "2026-04-09T16:00:00Z"
}
Then share the verification.link returned at customer creation so they can complete KYC. See Individual verification or Business verification for the full flow.

​
Step 4: Wait for accounts to activate

Once the customer is approved, each requested account is provisioned and goes through its own verification.
StatusDescription
PROVISIONINGAccount is being provisioned and verified
RFIAdditional information is required to continue verification
ACTIVEAccount is verified and can receive funds
CLOSEDAccount is permanently closed
Subscribe to the account.active webhook to know the moment an account is ready to receive funds. See Webhooks for the full event list.
account.active event
{
  "eventType": "account.active",
  "data": {
    "id": "af04e979-360a-428a-84e6-cbd8ffc4942b",
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "currency": "USD",
    "status": "ACTIVE"
  }
}

​
Step 5: Create an on-ramp for each expected deposit

To receive a payment in any of the customer’s provisioned currencies, create an on-ramp transaction with the exact amount that will be deposited. The response includes rail-specific payment details: a PIX brCode, a SPEI CLABE, wire instructions, or an IBAN. Share those details with the depositor; when the matching amount lands, Lumx converts the fiat to stablecoin and credits the customer’s wallet.
Each deposit must be matched to an on-ramp transaction created in advance with the exact amount.
If the deposit lands after the on-ramp expires, Lumx refunds the sender on the same rail. See Late deposits.
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": "10000.00",
    "targetCurrency": "USDC",
    "purpose": "PERSONAL_ACCOUNT"
  }'
The response includes state.payment with the rail-specific details to share with the depositor (PIX brCode, SPEI clabe, ACH/wire accountNumber + routingNumber, SEPA/SWIFT iban + bic). Subscribe to onramp.success to know the moment the deposit lands and the wallet is credited. See Transactions for the on-ramp lifecycle.
For products with prices fixed in stablecoin, fetch a locked exchange rate first and pass exchangeRateId instead of sourceAmount. The depositor is shown an exact local-currency amount and the conversion settles at that rate. See Exchange Rates.

Accounts

Understand virtual fiat accounts and their lifecycle.

Coverage

Supported currencies, rails and countries.

Webhooks

Subscribe to account and customer events.

Accounts API

Full API reference for accounts.