Skip to main content
POST
/
bank-accounts
curl --request POST \
  --url https://api.lumx.io/bank-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "Lumx Brazil Operations Account",
  "type": "EXTERNAL",
  "rail": "PIX",
  "currency": "BRL",
  "identifier": {
    "keyType": "CNPJ",
    "keyValue": "42.887.120/0001-00"
  },
  "holder": {
    "type": "BUSINESS",
    "relationship": "SELF",
    "legalName": "Lumx S.A",
    "taxId": "42.887.120/0001-00",
    "incorporationDate": "2020-01-01",
    "email": "hello@lumx.io",
    "address": {
      "line1": "Rua Voluntarios da Patria 89",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postalCode": "22270-000",
      "country": "BRA"
    }
  }
}
'
{
  "id": "a72f5359-ffef-6913-d1da-8g58d491g406",
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "Lumx Brazil Operations Account",
  "type": "EXTERNAL",
  "rail": "PIX",
  "currency": "BRL",
  "identifier": {
    "keyType": "CNPJ",
    "keyValue": "42.887.120/0001-00"
  },
  "holder": {
    "type": "BUSINESS",
    "relationship": "SELF",
    "legalName": "Lumx S.A",
    "taxId": "42.887.120/0001-00",
    "incorporationDate": "2020-01-01",
    "email": "hello@lumx.io",
    "address": {
      "line1": "Rua Voluntarios da Patria 89",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postalCode": "22270-000",
      "country": "BRA"
    },
    "verification": {
      "status": "UNDER_VERIFICATION",
      "level": "BASIC"
    }
  },
  "createdAt": "2025-10-16T15:30:22.456Z",
  "updatedAt": "2025-10-16T15:30:22.456Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header on the format Bearer <API_KEY>.

Headers

​
Idempotency-Key
string<uuid>

Optional UUID v4 idempotency key. If you resend the same key with a different request body, the API returns a 409 error. Cached responses include the header X-Idempotency-Cached: true. Keys expire after 24 hours.

Body

application/json
​
customerId
string<uuid>
required

Customer's unique identifier.

Example:

"3c90c3cc-0d44-4b50-8888-8dd25736052a"

​
name
string
required

Bank account's display name.

Example:

"Lumx Bank Account 1"

​
type
enum<string>
required

Bank account's type.

Available options:
EXTERNAL
Example:

"EXTERNAL"

​
rail
enum<string>
required

Bank account's payment rail.

Available options:
PIX
Example:

"PIX"

​
currency
enum<string>
required

Bank account's currency.

Available options:
BRL
Example:

"BRL"

​
identifier
object
required

Bank account's identifier.

​
holder
object
required

Bank account's holder.

Response

201 - application/json

Bank account successfully created.

Bank account's rail is PIX.

​
id
string<uuid>

Bank account's unique identifier.

Example:

"e80d3137-eddd-4791-b9b8-6e36b289f284"

​
customerId
string<uuid>

Customer's unique identifier.

Example:

"3c90c3cc-0d44-4b50-8888-8dd25736052a"

​
name
string

Bank account's display name.

Example:

"Lumx Bank Account 1"

​
type
enum<string>

Bank account's type.

Available options:
EXTERNAL
​
rail
enum<string>

Bank account's payment rail.

Available options:
PIX
​
currency
enum<string>

Bank account's currency.

Available options:
BRL
​
identifier
object

Bank account's identifier.

​
holder
object

Bank account's holder.

​
createdAt
string<date-time>

Creation date and time (UTC).

​
updatedAt
string<date-time>

Last update date and time (UTC).