Global accounts

Enable your customers to receive payments worldwide through local payment rails. You choose which currencies each customer should have an account in. To receive payments, you create an autoconversion rule for each account. The rule returns deposit details the customer shares with whoever pays them, and every deposit that lands is converted to stablecoin and credited to the customer’s wallet, with no per-deposit API call. 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", "GBP"]
  }'

Response

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "INDIVIDUAL",
  "verification": {
    "status": "NOT_STARTED",
    "level": "STANDARD"
  }
}

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

Once the customer accepts, the TERMS_OF_SERVICE requirement moves to APPROVED and the customer’s verification.link becomes available. Read the customer and share that link so they can complete KYC. See Individual verification or Business verification for the full flow.

Step 4: Wait for accounts to activate

Each requested account stays in AWAITING_ONBOARDING until the customer is approved, then provisioning is requested and the account goes through its own verification.

Status	Description
`AWAITING_ONBOARDING`	Account exists but the customer has not completed verification yet
`REQUESTED`	Customer approved and provisioning requested
`PROVISIONING`	Account is being provisioned and verified
`RFI`	Additional information is required to continue verification
`ACTIVE`	Account is verified and can receive funds
`REJECTED`	Account application was rejected
`INACTIVE`	Account was deactivated

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 autoconversion rule for each account

Once an account is ACTIVE, create an autoconversion rule for it, using the id from the account.active event as accountId. You do this once per account: every deposit that lands through the rule’s deposit details is converted to stablecoin and credited to the customer’s wallet, 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": "PERSONAL_ACCOUNT",
    "name": "USD → USDC"
  }'

Response

{
  "id": "c7f64332-5d53-4685-8aa9-48a5348c18c2",
  "accountId": "af04e979-360a-428a-84e6-cbd8ffc4942b",
  "partnerFeeId": null,
  "status": "ACTIVE",
  "provider": "ONE_MONEY",
  "sourceCurrency": "USD",
  "targetCurrency": "USDC",
  "blockchain": "POLYGON",
  "purpose": "PERSONAL_ACCOUNT",
  "sourceDepositInfo": [
    {
      "rail": "ACH",
      "accountNumber": "8312946570",
      "routingNumber": "021001088",
      "bankName": "HSBC Bank USA, N.A."
    },
    {
      "rail": "FEDWIRE",
      "accountNumber": "8312946570",
      "routingNumber": "021001088",
      "bankName": "HSBC Bank USA, N.A."
    },
    {
      "rail": "SWIFT",
      "accountNumber": "8312946570",
      "bic": "MRMDUS33XXX",
      "bankName": "HSBC Bank USA, N.A."
    }
  ],
  "createdAt": "2026-07-08T23:18:58.574Z"
}

The request is the same for every currency. What changes is sourceDepositInfo, which carries the details to share with the payer for each rail on the account: a static PIX brCode for BRL, a CLABE and memo for MXN, bank details for USD, an IBAN for EUR, a sort code and account number for GBP. See Share the deposit details for the fields per currency. Each deposit must be worth at least 50 USD in the account’s currency. A USD, EUR, or GBP account holds one active rule at a time; BRL and MXN accounts can hold several, each with its own reference. Subscribe to onramp.success to know the moment a deposit is converted and the wallet is credited. Each matched deposit runs as an on-ramp, so it follows the same lifecycle. See Transactions. In sandbox, trigger a deposit with POST /autoconversion-rules/simulate-deposit.

If the payer is paying one known amount, such as an invoice or a checkout with a price locked in stablecoin, create an on-ramp transaction for that deposit instead. It returns payment details for that amount only and accepts an exchangeRateId to settle at a locked 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.

Use Cases

Onboarding

Collect

Pay out

Build with AI

Global accounts

Step 1: Generate your API key

Step 2: Create a customer with the accounts you need

Step 3: Collect ToS acceptance and KYC

Step 4: Wait for accounts to activate

Step 5: Create an autoconversion rule for each account

Accounts

Coverage

Webhooks

Accounts API

​Step 1: Generate your API key

​Step 2: Create a customer with the accounts you need

​Step 3: Collect ToS acceptance and KYC

​Step 4: Wait for accounts to activate

​Step 5: Create an autoconversion rule for each account

​Related resources

Accounts

Coverage

Webhooks

Accounts API

Step 1: Generate your API key

Step 2: Create a customer with the accounts you need

Step 3: Collect ToS acceptance and KYC

Step 4: Wait for accounts to activate

Step 5: Create an autoconversion rule for each account

Related resources