> ## 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.

# Global accounts

> Provision local-currency accounts so each customer can be paid worldwide

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](/get-started/coverage) for the supported currencies and rails.

## Step 1: Generate your API key

Head over to [dashboard.lumx.io](https://dashboard.lumx.io). Once logged in, generate a new API key and store it securely. See [Authentication](/get-started/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.

```bash Request theme={null}
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"]
  }'
```

```json Response theme={null}
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "INDIVIDUAL",
  "verification": {
    "status": "NOT_STARTED",
    "level": "STANDARD",
    "link": "https://in.sumsub.com/websdk/p/sbx_aA00bB11cC33dD44"
  }
}
```

<Info>
  The `wallets` array is only returned once the customer's verification status is `APPROVED`. Subscribe to the `customer.approved` [webhook](/developer/webhooks) or call [Read a customer](/api-reference/customers/read-a-customer) to retrieve wallets after approval.
</Info>

See [Create a customer](/guides/create-a-customer) for the full payload reference, including business customers. The list of supported currencies and rails is in [Coverage](/get-started/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:

```bash Request theme={null}
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"
  }'
```

```json Response theme={null}
{
  "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](/guides/individual-verification) or [Business verification](/guides/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.

| **Status**     | **Description**                                             |
| :------------- | :---------------------------------------------------------- |
| `PROVISIONING` | Account is being provisioned and verified                   |
| `RFI`          | Additional information is required to continue verification |
| `ACTIVE`       | Account is verified and can receive funds                   |
| `CLOSED`       | Account is permanently closed                               |

Subscribe to the `account.active` webhook to know the moment an account is ready to receive funds. See [Webhooks](/developer/webhooks) for the full event list.

```json account.active event theme={null}
{
  "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.

<Info>
  Each deposit must be matched to an on-ramp transaction created in advance with the exact amount.
</Info>

If the deposit lands after the on-ramp expires, Lumx refunds the sender on the same rail. See [Late deposits](/concepts/transactions#late-deposits).

<Tabs>
  <Tab title="USD (ACH)">
    ```bash Request theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="BRL (PIX)">
    ```bash Request theme={null}
    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": "50000.00",
        "targetCurrency": "USDC",
        "purpose": "PERSONAL_ACCOUNT"
      }'
    ```
  </Tab>

  <Tab title="MXN (SPEI)">
    ```bash Request theme={null}
    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": "200000.00",
        "targetCurrency": "USDC",
        "purpose": "PERSONAL_ACCOUNT"
      }'
    ```
  </Tab>

  <Tab title="EUR (SEPA)">
    ```bash Request theme={null}
    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": "SEPA",
        "sourceCurrency": "EUR",
        "sourceAmount": "10000.00",
        "targetCurrency": "USDC",
        "purpose": "PERSONAL_ACCOUNT"
      }'
    ```
  </Tab>

  <Tab title="USD (SWIFT)">
    ```bash Request theme={null}
    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": "SWIFT",
        "sourceCurrency": "USD",
        "sourceAmount": "10000.00",
        "targetCurrency": "USDC",
        "purpose": "PERSONAL_ACCOUNT"
      }'
    ```
  </Tab>
</Tabs>

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](/concepts/transactions) for the on-ramp lifecycle.

<Tip>
  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](/concepts/exchange-rates).
</Tip>

## Related resources

<CardGroup cols="2">
  <Card title="Accounts" href="/concepts/accounts">
    Understand virtual fiat accounts and their lifecycle.
  </Card>

  <Card title="Coverage" href="/get-started/coverage">
    Supported currencies, rails and countries.
  </Card>

  <Card title="Webhooks" href="/developer/webhooks">
    Subscribe to account and customer events.
  </Card>

  <Card title="Accounts API" href="/api-reference/accounts/read-an-account">
    Full API reference for accounts.
  </Card>
</CardGroup>