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

# Open a Named BRL Account for a Business

> Create a BUSINESS customer with a BRL account through the Lumx API, pass KYB, and receive Pix in the company's name. Includes statuses and webhooks.

To open a named BRL account for a business, create a `BUSINESS` customer with `"accounts": ["BRL"]` through `POST /customers`, complete KYB, and wait for the account to reach `ACTIVE`. The account is issued by a Lumx banking partner in the customer's name, and it receives Pix. A company incorporated outside Brazil can hold it without a local entity in Brazil.

This guide covers the calls from customer creation to the first Pix. To turn those Pix payments into stablecoin, see [Collect BRL via Pix and settle in USDC or USDT](https://docs.lumx.io/guides/use-cases/collect-brl-via-pix-settle-in-stablecoins.md).

## How it works

1. Create the business customer and request the BRL account in the same call.
2. Have the company accept the terms of service.
3. Complete KYB: company details, documents, and associated parties.
4. Start the verification and wait for `APPROVED`.
5. The BRL account is provisioned and becomes `ACTIVE`.
6. Collect Pix into the account.

## Prerequisites

* An API key from the [Dashboard](https://dashboard.lumx.io) and the sandbox base URL, [https://api-sandbox.lumx.io](https://api-sandbox.lumx.io).
* The company's legal name, tax ID (CNPJ for a Brazilian company), incorporation date, country, and email.
* Its UBOs, shareholders, and at least one representative, with their documents. See [Business Verification (KYB)](https://docs.lumx.io/guides/business-verification.md).
* A webhook endpoint, set up under **Developers > Webhooks** in the Dashboard. See [Webhooks](https://docs.lumx.io/developer/webhooks.md).

## Create the customer and the account

Send a `POST` request to `/customers` with `type` set to `BUSINESS` and `accounts` set to `["BRL"]`.

```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": "BUSINESS",
    "legalName": "Lumx S.A",
    "taxId": "42.887.120/0001-00",
    "incorporationDate": "2020-01-01",
    "country": "BRA",
    "email": "hello@lumx.io",
    "accounts": ["BRL"]
  }'
```

```json Response theme={null}
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "BUSINESS",
  "legalName": "Lumx S.A",
  "taxId": "42.887.120/0001-00",
  "incorporationDate": "2020-01-01",
  "country": "BRA",
  "email": "hello@lumx.io",
  "verification": {
    "status": "NOT_STARTED",
    "level": "STANDARD"
  },
  "requirements": [
    { "name": "INCORPORATION_ARTICLES", "status": "NOT_SENT" },
    { "name": "DIRECTORS_REGISTRY", "status": "NOT_SENT" },
    { "name": "SHAREHOLDER_REGISTRY", "status": "NOT_SENT" },
    { "name": "TERMS_OF_SERVICE", "status": "NOT_SENT" }
  ],
  "accounts": [
    { "id": "8412f484-32fe-418f-80d1-99eb1b3ba7f3", "currency": "BRL" }
  ],
  "metadata": {},
  "createdAt": "2021-01-01T00:00:00Z",
  "updatedAt": "2021-01-01T00:00:00Z"
}
```

Save the customer `id` and the account `id`. The account starts in `AWAITING_ONBOARDING`. Customer creation also provisions a wallet on every supported blockchain, but the `wallets` array only appears once the customer is `APPROVED`. See [Create a Customer](https://docs.lumx.io/guides/create-a-customer.md).

### Request fields

| **Field** | **Required** | **Description** |
| :- | :- | :- |
| `type` | Yes | `BUSINESS` |
| `legalName` | Yes | Registered legal name |
| `taxId` | Yes | Valid tax ID in the country of incorporation |
| `incorporationDate` | Yes | Date, formatted YYYY-MM-DD |
| `country` | Yes | ISO 3166-1 alpha-3 code, for example `BRA` |
| `email` | Yes | Company email |
| `accounts` | Yes | At least one currency. Use `BRL` for this guide |
| `metadata` | No | Any JSON object, returned on the customer |

## Complete KYB

A business customer cannot transact until KYB is `APPROVED`. The steps, in order:

1. `POST /customers/{id}/tos` returns a `url` for the company to accept the terms of service. The link expires after 24 hours. See [Terms of Service](https://docs.lumx.io/compliance/terms-of-service.md).
2. `PATCH /customers/{id}/additional-information` sends the company's activity, revenue, source of funds, and counterparties.
3. `POST /customers/{id}/documents` uploads `INCORPORATION_ARTICLES`, `SHAREHOLDER_REGISTRY`, `DIRECTORS_REGISTRY`, and `PROOF_OF_ADDRESS`.
4. `POST /customers/{id}/associated-parties` adds the UBOs, shareholders, and representatives. At least one of each role is required before you start.
5. `POST /customers/{id}/documents` again, with `associatedPartyId`, uploads each party's documents.
6. `POST /customers/{id}/verifications` starts the review and returns a verification `id`.

Poll `GET /customers/{id}/verifications/{verificationId}` or, better, subscribe to the `customer.*` webhooks. Lumx targets two business days for the KYB review.

> [!WARNING]
>
> If you drive KYB through the API, do not also share `verification.link` with the company. Mixing the hosted flow and the API causes conflicts. If you would rather not build the flow, share the link and skip steps 2 to 6. It is returned once the terms of service are accepted.

Details for every step, including the full body for each associated party, are in [Business Verification (KYB)](https://docs.lumx.io/guides/business-verification.md).

## Watch the account become active

The account has its own status, separate from the customer's.

| **Status** | **Meaning** |
| :- | :- |
| `AWAITING_ONBOARDING` | Created, waiting for the customer's verification |
| `REQUESTED` | Customer approved, provisioning requested |
| `PROVISIONING` | Being provisioned and verified |
| `RFI` | Lumx needs more details to continue |
| `ACTIVE` | Ready to receive funds |
| `REJECTED` | Application rejected |
| `INACTIVE` | Deactivated |
| `CLOSED` | Closed |

For BRL, provisioning completes right after the customer is `APPROVED`, foreign companies included. Subscribe to the `account.active` webhook to know the moment the account is ready. The payload is the account itself:

```json account.active theme={null}
{
  "eventId": "81d783f1-3675-4f3a-92d1-e4f5af66cca3",
  "eventType": "account.active",
  "data": {
    "id": "8412f484-32fe-418f-80d1-99eb1b3ba7f3",
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "ACTIVE",
    "currency": "BRL",
    "createdAt": "2024-03-20T15:30:00Z",
    "updatedAt": "2024-03-20T15:30:05Z"
  }
}
```

You can also list a customer's accounts with `GET /accounts?customerId={customerId}`. Each item has `id`, `customerId`, `status`, `currency`, `createdAt`, and `updatedAt`.

The webhooks to handle during onboarding:

| **Event** | **Triggered when** |
| :- | :- |
| `customer.under_verification` | KYB review is in progress |
| `customer.approved` | Customer was approved |
| `customer.rfi` | Customer must send more information |
| `customer.final_rejection` | Customer was permanently rejected |
| `account.requested` | Provisioning was requested |
| `account.active` | The account can receive funds |
| `account.rfi` | The account needs additional information |
| `account.rejected` | The account application was rejected |

If an account moves to `RFI`, you are told what is missing. See [RFI](https://docs.lumx.io/compliance/rfi.md).

## Receive Pix

The account object carries status and currency. It does not return payment coordinates. A BRL account receives Pix through a Pix code, the `brCode`, which Lumx generates in one of two ways:

| **Method** | **Call** | **Where the `brCode` is** |
| :- | :- | :- |
| One charge per payment | `POST /transactions/on-ramp` with `rail` set to `PIX` | `state.payment.brCode` on the transaction |
| Standing rule for the account | `POST /autoconversion-rules` with the account's `id` | `sourceDepositInfo[0].brCode` on the rule |

Both convert the BRL to `USDC` or `USDT` and deliver it on-chain. Request one, share the `brCode` with the payer, and follow the conversion through the `onramp.*` webhooks. The rule route, one static Pix QR code for every deposit, is in [Autoconversion Rules](https://docs.lumx.io/guides/autoconversion-rules.md). The step-by-step for both routes is in [Collect BRL via Pix and settle in USDC or USDT](https://docs.lumx.io/guides/use-cases/collect-brl-via-pix-settle-in-stablecoins.md).

Pix runs 24/7/365. See [Payment rail cut-off times](https://docs.lumx.io/additional-information/sla-and-cutoffs.md).

## Limits

Each customer has `onramp`, `offramp`, and `transfer` limits. Read the current usage with `GET /customers/{id}?includeTransactionLimits=true`. A transaction above a limit returns `422` with `TRANSACTION_LIMIT_EXCEEDED`. See [Transaction Limits](https://docs.lumx.io/compliance/transaction-limits.md).

## Test in sandbox

In sandbox, the last digit of the customer's `taxId` sets the simulated verification outcome: `1` stays `NOT_STARTED`, `2` returns `RFI`, `3` returns `FINAL_REJECTION`, and any other digit is `APPROVED`. The webhooks fire almost instantly, so you can run the whole flow end to end.

## Related resources

> [card] [Accounts](https://docs.lumx.io/concepts/accounts.md)
>
> Account schema, lifecycle, and activation timelines.

> [card] [Business Verification (KYB)](https://docs.lumx.io/guides/business-verification.md)
>
> Every KYB call, with the full request bodies.

> [card] [Collect BRL via Pix](https://docs.lumx.io/guides/use-cases/collect-brl-via-pix-settle-in-stablecoins.md)
>
> Receive Pix and settle in USDC or USDT.

> [card] [Webhooks](https://docs.lumx.io/developer/webhooks.md)
>
> Event types, signatures, and retries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.