Open a Named BRL Account for a Business

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.

How it works

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

Prerequisites

An API key from the Dashboard and the sandbox base URL, 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).
A webhook endpoint, set up under Developers > Webhooks in the Dashboard. See Webhooks.

Create the customer and the account

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

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

Response

{
  "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.

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:

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.
PATCH /customers/{id}/additional-information sends the company’s activity, revenue, source of funds, and counterparties.
POST /customers/{id}/documents uploads INCORPORATION_ARTICLES, SHAREHOLDER_REGISTRY, DIRECTORS_REGISTRY, and PROOF_OF_ADDRESS.
POST /customers/{id}/associated-parties adds the UBOs, shareholders, and representatives. At least one of each role is required before you start.
POST /customers/{id}/documents again, with associatedPartyId, uploads each party’s documents.
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.

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

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:

account.active

{
  "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.

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. The step-by-step for both routes is in Collect BRL via Pix and settle in USDC or USDT. Pix runs 24/7/365. See Payment rail cut-off times.

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.

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.

Accounts

Account schema, lifecycle, and activation timelines.

Business Verification (KYB)

Every KYB call, with the full request bodies.

Collect BRL via Pix

Receive Pix and settle in USDC or USDT.

Webhooks

Event types, signatures, and retries.

Use Cases

Onboarding

Collect

Pay out

Build with AI

Open a Named BRL Account for a Business

How it works

Prerequisites

Create the customer and the account

Request fields

Complete KYB

Watch the account become active

Receive Pix

Limits

Test in sandbox

Accounts

Business Verification (KYB)

Collect BRL via Pix

Webhooks

​How it works

​Prerequisites

​Create the customer and the account

​Request fields

​Complete KYB

​Watch the account become active

​Receive Pix

​Limits

​Test in sandbox

​Related resources

Accounts

Business Verification (KYB)

Collect BRL via Pix

Webhooks

How it works

Prerequisites

Create the customer and the account

Request fields

Complete KYB

Watch the account become active

Receive Pix

Limits

Test in sandbox

Related resources