> ## 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.
# Changelog
> Stay up to date with the latest updates and improvements to Lumx
### Account provisioning at customer creation π¦
**Enhancement:**
1. **Provision accounts at customer creation**
You can now pass an `accounts` array of currency codes when creating a customer. Each currency provisions an account that enters verification and becomes `ACTIVE` once approved. The customer response now also returns the linked accounts with their `id` and `currency`.
Transition period: Until June 19, 2026, the `accounts` field is optional. During
this period, if no account is specified, the BRL account will be created. After
this date, it will be required when creating a customer.
```json theme={null}
{
"type": "BUSINESS",
"legalName": "Lumx Tecnologia LTDA",
"taxId": "00.000.000/0001-91",
"incorporationDate": "2020-01-01",
"country": "BRA",
"email": "hello@lumx.io",
"accounts": [
{ "id": "8412f484-32fe-418f-80d1-99eb1b3ba7f3", "currency": "BRL" },
{ "id": "af04e979-360a-428a-84e6-cbd8ffc4942b", "currency": "USD" },
{ "id": "d06d342c-629a-4d99-a26f-34e8ea528403", "currency": "EUR" },
{ "id": "16cb802f-8521-41ad-ab6e-dc40f43c0ad3", "currency": "MXN" }
]
}
```
2. **Read accounts**
List a customer's accounts via `GET /accounts`. Each account is linked to a customer and runs through a verification workflow (`PROVISIONING` β `ACTIVE`). See [Accounts](/concepts/accounts) for details.
```json theme={null}
{
"data": [
{
"id": "433bbe8b-feba-49e3-80f8-7bb528d3744e",
"customerId": "3b55a2fa-57dc-48f1-ac0f-ac1d5ba4674a",
"currency": "BRL",
"status": "ACTIVE",
"createdAt": "2026-05-13T20:49:13.236Z",
"updatedAt": "2026-05-14T13:55:15.418Z"
}
]
}
```
3. **Account webhook events**
Subscribe to `account.provisioning`, `account.rfi`, `account.active`, and `account.closed` to receive real-time updates as an account moves through verification. See [Available events](/developer/webhooks#available-events).
### Bank accounts renamed to destinations π¦
**Deprecated:**
Transition period: The `/bank-accounts` route will continue to work until June 19, 2026. After this date, only `/destinations` will be available. Migrate your integration before then.
1. **Resource renamed across the API**
The `/bank-accounts` resource is now `/destinations`. The `bankAccountId` field is now `destinationId`. See [Destinations](/concepts/destinations) for the updated concept.
`POST /transactions/off-ramp` will accept either `destinationId` or `bankAccountId` until June 19, 2026. After this date, only `destinationId` will be accepted.
2. **`bank_account.*` webhook events renamed to `destinations.*`**
The events previously emitted as `bank_account.under_verification`, `bank_account.approved`, and `bank_account.final_rejection` are now `destinations.under_verification`, `destinations.approved`, and `destinations.final_rejection`.
3. **`type` field removed from destination requests**
The `type` field is no longer documented for `POST /destinations`. The `/destinations` route will continue to accept `type` as an optional field until June 19, 2026 so existing integrations migrating from `/bank-accounts` keep working. After this date, the field will be rejected. Continue sending `type` on `/bank-accounts`; stop sending it on `/destinations`.
Update your subscriptions on the [dashboard](https://dashboard.lumx.io) to start receiving the new `destinations.*` events β the old event names will no longer fire.
### `TEMPORARY_REJECTION` renamed to `RFI` βοΈ
**Deprecated:**
Breaking change. The status value, the value returned for each associated
party, and the webhook event name have all changed. Update your integration
before deploying to production.
1. **Customer and associated party status renamed**
The verification status `TEMPORARY_REJECTION` is now `RFI` (Request for Information). The rename applies to the `status` field on both the customer and each entry in the `associatedParties` array, in API responses and webhook payloads.
2. **New `customer.rfi` webhook event**
A new `customer.rfi` webhook event has been introduced. The `customer.temporary_rejection` event will continue to exist, but it will no longer fire β only the new `customer.rfi` event will be emitted. The `customer.temporary_rejection` event will be removed in a future release.
Update your subscriptions on the [dashboard](https://dashboard.lumx.io) to
start receiving the new `customer.rfi` event.
### Wallets only returned for APPROVED customers π
**Deprecated:**
1. **`wallets` gated by verification status**
The `wallets` array is now only returned on customer responses once the customer's `verification.status` is `APPROVED`. This also means [Create a customer](/api-reference/customers/create-a-customer) no longer returns `wallets`. Call [Read a customer](/api-reference/customers/read-a-customer) or register the `customer.approved` [webhook](/developer/webhooks) to get notified once verification is approved and the wallets become available.
### Isolated retry for associated party verification π
**Enhancement:**
1. **Retry verification for specific associated parties**
The [Start a verification](/api-reference/customers/start-a-verification) endpoint now accepts an optional `associatedPartyIds` array in the request body. When provided, only the listed associated parties are sent for verification again, and any associated party not included keeps its current verification status. See [Retrying verification for specific associated parties](/guides/business-verification#retrying-verification-for-specific-associated-parties) for details.
Applies only to BUSINESS customers. Resubmit any corrected
documents/information for the affected associated parties before starting the
retry.
```json theme={null}
{
"associatedPartyIds": [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"b2c3d4e5-f6a7-8901-bcde-f12345678901"
]
}
```
### Improving customer onboarding π©οΈ
**Enhancement:**
1. **Auto-assign UBO role to sole shareholders**
If an individual associated party is the only shareholder, the system will automatically add `UBO` to their `roles` array. No action required from your side.
2. **`PROOF_OF_ADDRESS` document now required**
A `PROOF_OF_ADDRESS` document is now required when [uploading documents](/api-reference/customers/upload-a-document) for individual customers, business customers, UBOs, and representatives. You can't start a verification without sending this document.
The proof of address document must have been issued within the last **90
days**.
```json theme={null}
{
"type": "PROOF_OF_ADDRESS"
}
```
3. **Terms of service acceptance required before verification**
Transition period: Until April 16, 2026, acceptance of terms of service will
be optional to start a verification. After this date, acceptance will be
mandatory.
Customers must now accept terms of service before verification can start. Send a `POST` request to `/customers/{id}/tos` with an optional `redirectUrl` to get the acceptance URL. Share the returned URL with your customer. The `requirements` array includes `TERMS_OF_SERVICE` until the customer has accepted. See also [Read a customer](/api-reference/customers/read-a-customer).
```json Request body (optional) theme={null}
{
"redirectUrl": "https://yourapp.com/onboarding/next-step"
}
```
```json Response theme={null}
{
"url": "https://dashboard.lumx.io/tos/sandbox/eyJhbGciOiJSUzI1...",
"expiresAt": "2026-04-09T16:00:00Z"
}
```
The acceptance URL expires after **24 hours**. Generate a new one if it expires before the customer accepts.
### Webhooks v2 π
**Enhancement:**
1. **New webhook delivery system**
Webhooks now use a new delivery infrastructure with improved reliability, automatic retries with exponential backoff, and signature verification. All events follow a consistent structure with `eventId`, `eventType`, and `data` fields. See [Webhooks](/developer/webhooks) for details.
**Deprecated:**
Transition period: Until April 30, 2026, both legacy and new webhook formats
will be delivered. After this date, only the new format will be sent.
2. **Legacy webhook format deprecated:** Migrate to the new webhook format and update your signature verification to use the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. See [Verifying webhook signatures](/developer/webhooks#verifying-webhook-signatures) for implementation examples.
### MXN support is now live π²π½
**New feature:**
1. **MXN transactions now available**
You can now execute transactions using MXN (Mexican Peso) as source or target currency, expanding our coverage to support payments in Mexico.
```json theme={null}
{
"sourceCurrency": "MXN",
"sourceAmount": "10000.00",
"targetCurrency": "USDC",
"purpose": "PERSONAL_ACCOUNT"
}
```
2. **MXN bank accounts now supported**
You can now create and manage bank accounts with MXN currency for off-ramp payments to Mexican bank accounts using SPEI.
```json theme={null}
{
"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "Mexico Supplier Account",
"type": "EXTERNAL",
"rail": "SPEI",
"currency": "MXN",
"identifier": {
"clabe": "012180001234567897"
},
"holder": {
"type": "INDIVIDUAL",
"relationship": "SUPPLIER",
"name": "Juan PΓ©rez",
"taxId": "PEPJ850101ABC",
"address": {
"line1": "Avenida Insurgentes Sur 1458",
"city": "Mexico City",
"state": "CDMX",
"postalCode": "03900",
"country": "MEX"
}
}
}
```
For complete coverage details, see [Coverage](/get-started/coverage).
### Sandbox magic numbers for testing πͺ
**New feature:**
1. **Magic numbers for customer verification testing**
Use sentinel values in the `taxId` field when creating customers in sandbox to simulate different verification statuses. No API changes required, magic numbers use existing fields.
| `taxId` ending | Simulated status |
| -------------- | ------------------------------------------------------- |
| `1` | `NOT_STARTED` - verification never starts automatically |
| `2` | `RFI` - requests additional documents |
| `3` | `FINAL_REJECTION` - permanent rejection |
| Any other | `APPROVED` - default behavior |
```json theme={null}
{
"type": "INDIVIDUAL",
"name": "William Default",
"taxId": "123.456.789-01",
"birthDate": "1990-01-01",
"country": "BRA",
"email": "william.default@example.com"
}
```
Webhooks are triggered almost instantly with the simulated status, so you can test your full end-to-end flow exactly as it works in production.
### Multiple roles for associated parties π
**Deprecated:**
Breaking change. Requests using the old `role` field will be rejected. Update
your integration before deploying to production.
1. **`role` changed to `roles` array in associated parties:** The `POST /customers/{id}/associated-parties` endpoint now requires a `roles` array instead of the single `role` string field. This allows associated parties to hold multiple roles simultaneously (e.g., both UBO and REPRESENTATIVE). Valid values: `UBO`, `REPRESENTATIVE`, `SHAREHOLDER`.
Before:
```json theme={null}
{
"type": "INDIVIDUAL",
"role": "UBO",
"name": "Maria Santos",
"birthDate": "1985-07-10",
"email": "maria.santos@example.com",
"taxId": "987.654.321-00",
"ownershipPercentage": 40
}
```
After:
```json theme={null}
{
"type": "INDIVIDUAL",
"roles": ["UBO"],
"name": "Maria Santos",
"birthDate": "1985-07-10",
"email": "maria.santos@example.com",
"taxId": "987.654.321-00",
"ownershipPercentage": 40
}
```
For multiple roles:
```json theme={null}
{
"type": "INDIVIDUAL",
"roles": ["UBO", "REPRESENTATIVE"],
"name": "Maria Santos"
}
```
### KYC/KYB API and idempotency support π€―
**New feature:**
1. **KYC/KYB verification endpoints**
New endpoints for the full identity verification flow: send additional information, upload documents, manage associated parties, and start verifications β all via API.
* `PATCH /customers/{id}/additional-information` β Submit KYC/KYB data
* `POST /customers/{id}/documents` β Upload verification documents
* `POST /customers/{id}/associated-parties` β Add UBOs, shareholders, and representatives
* `GET /customers/{id}/associated-parties` β List associated parties
* `GET /customers/{id}/associated-parties/{associatedPartyId}` β Read an associated party
* `POST /customers/{id}/verifications` β Start a verification
* `GET /customers/{id}/verifications/{verificationId}` β Read verification status
2. **`additionalInformation` in customer response**
After sending additional information, the customer response now includes an `additionalInformation` object with all submitted KYC/KYB data.
3. **Multi-level corporate structures**
Associated parties now support a `parentId` field, allowing you to nest shareholders across multiple levels of ownership hierarchy.
```json theme={null}
{
"type": "INDIVIDUAL",
"role": "SHAREHOLDER",
"parentId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "John Smith",
"ownershipPercentage": 50
}
```
4. **Idempotency support**
All mutation endpoints (`POST`, `PUT`, `PATCH`) now accept an `Idempotency-Key` header to prevent duplicate operations. Keys expire after 24 hours. See [Idempotency](/developer/idempotency) for details.
### Individual customers and bank account holders π₯³
**New feature:**
1. **Individual customer type**
Customers can now be created with `type: "INDIVIDUAL"` for natural persons. Individual customers require `name`, `taxId`, and `birthDate` fields.
```json theme={null}
{
"type": "INDIVIDUAL",
"name": "William Default",
"taxId": "100.100.100-01",
"birthDate": "1990-01-01"
}
```
2. **Individual bank account holders**
Bank accounts now support individual holders with the same structure. For counterparty bank accounts, `birthDate` is optional.
3. **Individual bank account identifier key type as CPF**
Bank account now support `CPF` as a valid `keyType` identifier for PIX.
**Enhancement:**
4. **New relationship types for bank account holders**
Added `FRIEND`, `RELATIVE`, and `EMPLOYEE` to the available relationship types for bank account holders.
### Multi-blockchain support π₯
**New feature:**
1. **Multiple wallets per customer**
Customers now support multiple wallets, one per blockchain. The new `wallets` array includes blockchain, address, block explorer link, stablecoin balances, and default blockchain indication.
```json theme={null}
{
"wallets": [
{
"blockchain": "POLYGON",
"address": "0x...",
"blockExplorerUrl": "https://polygonscan.com/address/0x...",
"isDefault": true,
"balances": [{ "stablecoin": "USDC", "balance": "1000.00" }]
}
]
}
```
2. **Blockchain field in transactions**
All transactions (on-ramp, off-ramp, transfer) now accept an optional `blockchain` field. If not specified, the project's default blockchain is used.
```json theme={null}
{
"blockchain": "BASE",
"sourceCurrency": "BRL",
"sourceAmount": "1000.00",
"targetCurrency": "USDC"
}
```
3. **Blockchain field in exchange rates**
Exchange rate requests now accept an optional `blockchain` field. The response indicates which blockchain was used for rate calculation.
**Enhancement:**
4. **Improved balance tracking**
Balances are now tracked per blockchain and per stablecoin, providing better clarity for multi-network operations.
**Deprecated:**
Transition period: Until January 26, 2026, both old and new formats will be
returned. After this date, only the new format will be available.
5. **`wallet` and `balances` fields deprecated on customers:** Migrate to the new `wallets` array. Affected endpoints: `POST /customers`, `GET /customers`.
6. **Default partner fee removed:** If no `partnerFeeId` is provided, partner fees will be zero. Remove any logic that depends on a default fee. Affected endpoints: `GET /partner-fees`, `POST /partner-fees`.
### Transaction limits response improved β‘
**Enhancement:**
1. **Transaction limits now include usage tracking**
When using `includeTransactionLimits=true`, the `transactionLimits` object now returns detailed usage information with `used` and `remaining` fields for `daily` and `monthly` limits, giving you real-time visibility into your customer's limit consumption.
```json theme={null}
{
"transactionLimits": {
"single": { "max": "10000.00" },
"daily": {
"max": "100000.00",
"used": "0.00",
"remaining": "100000.00"
},
"monthly": {
"max": "1000000.00",
"used": "0.00",
"remaining": "1000000.00"
}
}
}
```
**Deprecated:**
This is a breaking change. Update your integration before deployment.
2. **`transactionLimits` no longer returned by default:** The `transactionLimits` field is no longer included in `GET /customers/{id}` responses by default. Use the new query parameter `includeTransactionLimits=true` to retrieve transaction limits.
3. **`transactionLimits` removed from customer listing:** The `GET /customers` endpoint no longer returns the `transactionLimits` field in the response array.
4. **10-second timelock removed from exchange rates:** The 10-second timelock option is no longer available. The 30-second timelock now has no additional fees, and fees for other timelock options have been optimized.
### SEPA and SWIFT are live π
**New feature:**
1. **SEPA support now available**
You can now create bank accounts and execute transactions using SEPA (Single Euro Payments Area) for EUR payments across Europe. SEPA provides instant settlement for transactions under \$100k and 1 business day settlement for larger amounts.
```json theme={null}
{
"rail": "SEPA",
"sourceCurrency": "EUR",
"sourceAmount": "10000.00",
"targetCurrency": "USDC",
"purpose": "PERSONAL_ACCOUNT"
}
```
2. **SWIFT support now available**
You can now create bank accounts and execute transactions using SWIFT for USD international wire transfers. SWIFT enables global payments with 1-5 business day settlement times.
```json theme={null}
{
"rail": "SWIFT",
"sourceCurrency": "USD",
"sourceAmount": "10000.00",
"targetCurrency": "USDC",
"purpose": "PERSONAL_ACCOUNT"
}
```
For complete coverage details, see [Coverage](/get-started/coverage).
**Enhancement:**
3. **Purpose field now returned in transaction responses**
The `purpose` field is now included in transaction responses under the `request` object, providing full visibility of the original transaction intent.
4. **Target amount visibility improved**
Transaction responses now consistently return `targetAmount` in the `receipt` object when the conversion is complete, ensuring you always have access to the final conversion amounts.
5. **Bank account ordering updated**
Bank accounts are now ordered by creation date (newest first) instead of by ID, making it easier to find recently added accounts.
### Bank Accounts are live π
**New feature:**
1. **Supplier payments now available**
You can now send off-ramp funds to bank accounts that don't belong to the registered customer. This enables direct supplier payments.
The new `/bank-accounts` endpoint allows you to register and manage bank accounts for supplier payments. Refer to the [Create a Bank Account](/api-reference/bank-accounts/create-a-bank-account) for details.
**Enhancement:**
2. `PROCESSING` **status renamed to** `TRANSFERRING_STABLECOIN`
3. `state.blockchain` **moved to** `state.receipt`
The new `receipt` object includes `transactionHash` and `blockExplorerUrl` fields for better transaction tracking.
4. `purpose` **now required for on-ramp and off-ramp transactions**
For compliance reasons, all transaction requests must include a `purpose` field. Requests without this field will be rejected.
5. **On-ramp:** `payment.rail` moved to request level `rail`
6. **Off-ramp:** `customerId` and `payment` object removed, use `bankAccountId` only
7. **Exchange Rate:** `rail` and `customerId` parameters now required