Changelog - Lumx

New FeatureEnhancementDeprecated

v2.22.0

Preparing for our Brazil VASP license 💜

We’re getting close to applying for our VASP license in Brazil, and part of that preparation reaches the API. Transaction limits will be split by transaction type, and the onboarding questionnaire gets simpler, with monthly income and revenue questions and fixed lists for most answers. Your customers will also accept terms of service with each Lumx legal entity they work with, and your webhooks will tell you when those terms change. Here is what changes and what your integration needs to handle.

We’ll roll out these breaking changes on October 28, 2026: terms of service before verification, transaction limits per transaction type, the required type on limit requests, and the new questionnaire fields and accepted values. Please update your integration before then.

Enhancement:

Terms of service come before verification

Customers accept the terms of service before they can start identity verification. verification.link is only returned once the TERMS_OF_SERVICE requirement is APPROVED, so read the customer again after acceptance to get it. See Terms of Service.

Transaction limits per transaction type

transactionLimits now returns separate limits for onramp, offramp and transfer. Each one has the same single, daily and monthly structure you already know. Update your integration to read the bucket that matches the transaction you’re creating. See Transaction limits.

Before

"transactionLimits": {
	"single": { "max": "1000.00" },
	"daily": { "max": "5000.00", "used": "1200.00", "remaining": "3800.00" },
	"monthly": { "max": "20000.00", "used": "1200.00", "remaining": "18800.00" }
}

After

"transactionLimits": {
	"onramp": {
		"single": { "max": "1000.00" },
		"daily": { "max": "5000.00", "used": "1200.00", "remaining": "3800.00" },
		"monthly": { "max": "20000.00", "used": "1200.00", "remaining": "18800.00" }
	},
	"offramp": { "single": { ... }, "daily": { ... }, "monthly": { ... } },
	"transfer": { "single": { ... }, "daily": { ... }, "monthly": { ... } }
}

Limit increase requests follow the same split. POST /customers/{id}/limit-requests now requires a type field (ONRAMP, OFFRAMP or TRANSFER), and each type can have its own pending request. Limit request responses include type, which is null for requests created before this change.

Request (POST /customers/{id}/limit-requests, excerpt)

{
	"type": "OFFRAMP",
	"requested": {
		"single": "5000.00",
		"daily": "10000.00",
		"monthly": "50000.00"
	}
}

Individual additional information

We updated the questionnaire behind customer verification to meet new regulatory requirements. PATCH /customers/{id}/additional-information for individuals now requires monthlyIncomeInUSD, and professionalSituation, sourceOfFunds and transactionCounterparties only accept the values listed under Accepted values below.

Request (PATCH /customers/{id}/additional-information)

{
	"type": "INDIVIDUAL",
	"phone": "+5511999999999",
	"firstName": "Maria",
	"middleName": "Silva",
	"lastName": "Souza",
	"address": {
		"country": "BRA",
		"line1": "Rua A, 100",
		"city": "São Paulo",
		"state": "SP",
		"postalCode": "01000-000"
	},
	"professionalSituation": "BUSINESS_OWNER",
	"professionalOccupation": "Engineer",
	"monthlyIncomeInUSD": "8000",
	"monthlyVolumeInUSD": "5000",
	"transactionVolumeInUSD": "1000",
	"sourceOfFunds": "SALARY_EMPLOYMENT_INCOME",
	"transactionCounterparties": ["SELF", "FAMILY"]
}

Business additional information

For businesses, monthlyRevenueInUSD is now required and monthlyTransactionVolumeInUSD takes a range instead of free text. businessActivity, sourceOfFunds and transactionCounterparties only accept the values listed under Accepted values below.

Request (PATCH /customers/{id}/additional-information)

{
	"type": "BUSINESS",
	"phone": "+5511999999999",
	"address": {
		"country": "BRA",
		"line1": "Av. B, 200",
		"city": "São Paulo",
		"state": "SP",
		"postalCode": "01000-000"
	},
	"website": "https://acme.com",
	"businessActivity": "PAYMENT_INSTITUTION",
	"servicesProvided": "Cross-border payments for small businesses",
	"monthlyRevenueInUSD": "250000",
	"monthlyTransactionVolumeInUSD": "1M_TO_5M",
	"sourceOfFunds": "OPERATING_SERVICE_REVENUE",
	"transactionCounterparties": ["CUSTOMERS", "SUPPLIERS_VENDORS"],
	"isRegulatedActivity": true,
	"regulatedActivityDetails": "Licensed payment institution"
}

Individual associated parties

UBOs, shareholders and representatives that are individuals now require monthlyIncomeInUSD on POST /customers/{id}/associated-parties, and you’ll also get it back when you read associated parties. Business associated parties stay the same.

Request (POST /customers/{id}/associated-parties)

{
	"type": "INDIVIDUAL",
	"roles": ["UBO", "REPRESENTATIVE"],
	"email": "joao@acme.com",
	"taxId": "12345678909",
	"name": "João Lima",
	"birthDate": "1985-04-12",
	"address": {
		"line1": "Rua C, 10",
		"city": "São Paulo",
		"state": "SP",
		"postalCode": "01000-000",
		"country": "BRA"
	},
	"ownershipPercentage": 40,
	"monthlyIncomeInUSD": "12000"
}

Accepted values

professionalSituation (individual)

EMPLOYEE
SELF_EMPLOYED
BUSINESS_OWNER
GOVERNMENT_OFFICIAL
INVESTOR
STUDENT
RETIRED
HOMEMAKER
UNEMPLOYED
OTHER

sourceOfFunds (individual)

SALARY_EMPLOYMENT_INCOME
BUSINESS_INCOME_DIVIDENDS
SAVINGS_INVESTMENT_RETURNS
PENSION_RETIREMENT
SALE_OF_ASSETS_REAL_ESTATE
INHERITANCE_GIFT
LOAN
GOVERNMENT_BENEFITS
GAMBLING_LOTTERY_PROCEEDS
ROYALTIES_INTELLECTUAL_PROPERTY
THIRD_PARTY_FUNDS
OTHER

transactionCounterparties (individual)

SELF
FAMILY
FRIENDS
EMPLOYER
MERCHANTS_BUSINESSES
GOVERNMENT
OTHER

sourceOfFunds (business)

OPERATING_SERVICE_REVENUE
INVESTMENT_RETURNS_CAPITAL_GAINS
ASSET_BUSINESS_SALE
SHAREHOLDER_EQUITY_RAISE
LOAN
INTERCOMPANY_TRANSFER
GRANT
CRYPTOCURRENCY_DIGITAL_ASSETS
ROYALTIES_AFFILIATE_INCOME
LEGAL_SETTLEMENT_SUCCESSION
GAMBLING_REVENUE
CHARITABLE_CONTRIBUTIONS
OTHER

transactionCounterparties (business)

OWN_ACCOUNTS_INTERCOMPANY
SHAREHOLDERS_PARTNERS
CUSTOMERS
MERCHANTS
SUPPLIERS_VENDORS
EMPLOYEES
CONTRACTORS
FINANCIAL_INSTITUTIONS_VASP
INVESTMENT_COUNTERPARTIES
GOVERNMENT_TAX_AUTHORITIES
AFFILIATED_COMPANIES
OTHER

monthlyTransactionVolumeInUSD (business)

UP_TO_100K
100K_TO_1M
1M_TO_5M
5M_TO_10M
10M_TO_20M
20M_TO_30M
OVER_30M

businessActivity (business)

SOFTWARE_DEVELOPMENT
VASP
PAYMENT_INSTITUTION
PAYMENT_PROCESSOR_GATEWAY
LIQUIDITY_PROVIDER_OTC_DESK
CRYPTO_MSB
STABLECOIN_ISSUER
NON_CUSTODIAL_WALLET_PROVIDER
CUSTODIAN
CRYPTO_CARDS
DEFI_DAO_FOUNDATION
NFT_MARKETPLACE_TOKEN_PROJECT
P2P_MERCHANTS
ATM_KIOSK_OPERATOR
CRYPTO_MINER
GAMING_METAVERSE_P2E
FOREIGN_EXCHANGE_FX
NON_CRYPTO_MSB
BANKING_CORRESPONDENT
BANK_FINANCIAL_INSTITUTION
ECOMMERCE_MARKETPLACE
IMPORTER_EXPORTER_TRADE
TRAVEL_AGENCY_TOURISM
INVESTMENT_FUND
INVESTMENT_ADVISOR_MANAGER
VENTURE_CAPITAL_PRIVATE_EQUITY
SOVEREIGN_WEALTH_FUND
HOLDING_SPV_FAMILY_OFFICE
TRUST
COMPANY_FORMATION_CSP
LOAN_OR_FINANCE_COMPANY
INSURANCE_COMPANY
COMMODITIES_OIL_AND_GAS
PRECIOUS_METALS_AND_STONES
REAL_ESTATE_LEASING
LOGISTICS_CUSTOMS_TRANSPORT
WHOLESALER
GENERAL_MANUFACTURING
RETAILER
JEWELRY_RETAIL
PROFESSIONAL_MARKETING_SERVICES
PAYROLL_PEO_HR_SERVICES
PHARMACEUTICAL_DRUG_DISTRIBUTION
CHARITY_NGO_NON_PROFIT
GAMBLING_CASINO_BETTING
ART_ANTIQUITIES_COLLECTIBLES
PAWN_SHOPS
MINING_AND_EXTRACTION
CONSTRUCTION_SKILLED_TRADE
MEDIA_ARTS_ENTERTAINMENT
TOBACCO_ALCOHOL
MARIJUANA_CANNABIS
ADULT_ENTERTAINMENT
ARMS_INDUSTRY
AGRICULTURE_FISHING_HUNTING
HEALTHCARE_SOCIAL_ASSISTANCE
EDUCATIONAL_SERVICES
ACCOMMODATION_FOOD_SERVICE
UTILITIES_PUBLIC_ADMIN
OTHER

Values outside these lists return 400, including values we accepted before this change. Customers you onboarded earlier keep their previous answers in additionalInformation.Deprecated:

Removed from individual additional information: jurisdictions, involvedActivities.
Removed from business additional information: jurisdictions, involvedActivities, annualRevenue, complianceAndAML, monthlyVolumeInUSD, transactionVolumeInUSD. Send the expected monthly volume in monthlyTransactionVolumeInUSD instead.
Renamed in business additional information: companyType is now businessActivity, with the new list of values above.

New feature:

Terms of service webhooks

Customers now sign the terms of service of each Lumx legal entity separately. If your project has webhooks configured, you’ll receive these new events automatically. You don’t need to subscribe to anything.

Event	When it fires
`customer.tos.pending`	The customer needs to accept new terms before `graceUntil`
`customer.tos.updated`	The terms changed, but the customer doesn’t need to accept them again
`customer.tos.signed`	The customer signed terms of service
`customer.missing_tos`	`graceUntil` passed without acceptance and the customer moved to `MISSING_TOS`

customer.tos.pending brings everything you need to send the customer to the new terms. tosLink is the acceptance page and stops working at expiresAt. graceUntil is the deadline to accept. url points to the terms themselves. If the link expires, generate a new one with Create TOS acceptance link.

customer.tos.pending

{
	"eventId": "550e8400-e29b-41d4-a716-446655440000",
	"eventType": "customer.tos.pending",
	"data": {
		"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
		"tosLink": "https://dashboard.example.com/tos/...",
		"expiresAt": "2026-08-28T00:00:00.000Z",
		"graceUntil": "2026-08-21T00:00:00.000Z",
		"url": "https://provider.example.com/terms"
	}
}

customer.tos.updated is a heads-up only. Share the updated url with your customer if you’d like, there’s nothing for them to sign.

customer.tos.updated

{
	"eventId": "550e8400-e29b-41d4-a716-446655440000",
	"eventType": "customer.tos.updated",
	"data": {
		"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
		"url": "https://provider.example.com/terms"
	}
}

customer.tos.signed fires every time the customer signs: during onboarding, after accepting new terms, and when recovering from MISSING_TOS.

customer.tos.signed

{
	"eventId": "550e8400-e29b-41d4-a716-446655440000",
	"eventType": "customer.tos.signed",
	"data": {
		"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
		"signedAt": "2026-08-11T12:00:00.000Z"
	}
}

If the customer doesn’t accept by graceUntil, their verification status moves to MISSING_TOS and they can’t create on-ramps, off-ramps or transfers until they sign. You’ll receive customer.missing_tos with statusReason.reason set to TOS_GRACE_EXPIRED.

customer.missing_tos (excerpt)

{
	"eventId": "550e8400-e29b-41d4-a716-446655440000",
	"eventType": "customer.missing_tos",
	"data": {
		"id": "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
		"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
		"status": "missing_tos",
		"statusReason": {
			"reason": "TOS_GRACE_EXPIRED"
		}
	}
}

We’re here to help your team through these changes. Thank you for building with us! 💜

New FeatureEnhancement

v2.20.0

GBP accounts and FPS are live 🇬🇧

New feature:

GBP accounts

Request GBP in the accounts array when you create a customer to provision a GBP virtual account, subject to your project’s allowed currencies. Track it with GET /accounts.

Request

{
	"accounts": ["GBP"]
}

Response (GET /accounts)

{
	"data": [
		{
			"id": "4e8a1d20-9c7b-4f33-b512-7d0e9f1a2b3c",
			"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
			"status": "ACTIVE",
			"currency": "GBP",
			"createdAt": "2026-09-29T13:58:40.217Z",
			"updatedAt": "2026-09-29T14:02:05.931Z"
		}
	]
}

FPS on-ramps

On-ramps accept rail: "FPS" (Faster Payments Service) with sourceCurrency: "GBP". The response returns the sort code and account number to pay into under state.payment.identifier.

Request

{
	"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
	"rail": "FPS",
	"sourceCurrency": "GBP",
	"sourceAmount": "1000.00",
	"targetCurrency": "USDC",
	"purpose": "PERSONAL_ACCOUNT"
}

Response

{
	"id": "123e4567-e89b-12d3-a456-426614174012",
	"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
	"type": "ON_RAMP",
	"request": {
		"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
		"rail": "FPS",
		"sourceCurrency": "GBP",
		"sourceAmount": "1000.00",
		"targetCurrency": "USDC",
		"purpose": "PERSONAL_ACCOUNT"
	},
	"state": {
		"status": "AWAITING_FUNDS",
		"payment": {
			"rail": "FPS",
			"identifier": {
				"sortCode": "040509",
				"accountNumber": "00126007"
			},
			"holder": {
				"name": "Lumx UK Ltd"
			}
		}
	},
	"metadata": {},
	"createdAt": "2026-10-01T15:30:00Z",
	"updatedAt": "2026-10-01T15:30:05Z"
}

FPS destinations

Create UK bank account destinations with rail: "FPS" and currency: "GBP". The identifier is the 6-digit sortCode and 8-digit accountNumber. bank and holder are required, but their addresses only need country. SEPA destinations follow the same rule.

Request

{
	"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
	"name": "UK Supplier Account",
	"type": "EXTERNAL",
	"rail": "FPS",
	"currency": "GBP",
	"identifier": {
		"sortCode": "040509",
		"accountNumber": "00125977"
	},
	"bank": {
		"name": "Mock Bank",
		"address": {
			"country": "GBR"
		}
	},
	"holder": {
		"type": "INDIVIDUAL",
		"relationship": "SUPPLIER",
		"name": "William Default",
		"taxId": "QQ123456C",
		"email": "william@example.com",
		"address": {
			"country": "GBR"
		}
	}
}

Response

{
	"id": "7a2c9e14-5b3f-4d81-9e6a-0f1b2c3d4e5f",
	"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
	"name": "UK Supplier Account",
	"type": "EXTERNAL",
	"rail": "FPS",
	"currency": "GBP",
	"identifier": {
		"sortCode": "040509",
		"accountNumber": "00125977"
	},
	"bank": {
		"name": "Mock Bank",
		"address": {
			"country": "GBR"
		}
	},
	"holder": {
		"type": "INDIVIDUAL",
		"relationship": "SUPPLIER",
		"name": "William Default",
		"taxId": "QQ123456C",
		"email": "william@example.com",
		"address": {
			"country": "GBR"
		},
		"verification": {
			"status": "UNDER_VERIFICATION",
			"level": "BASIC"
		}
	},
	"createdAt": "2026-10-01T15:30:22.456Z",
	"updatedAt": "2026-10-01T15:30:22.456Z"
}

EUR and GBP autoconversion rules

Create autoconversion rules for EUR and GBP accounts. sourceDepositInfo returns the SEPA (iban, bic) or FPS (sortCode, accountNumber) details to share with the sender. As with USD, deposits are matched to the account, so each customer can have one active EUR rule and one active GBP rule at a time. See Autoconversion Rules.

Request

{
	"accountId": "4e8a1d20-9c7b-4f33-b512-7d0e9f1a2b3c",
	"targetCurrency": "USDC",
	"blockchain": "POLYGON",
	"purpose": "INVESTMENT",
	"name": "GBP → USDC investment"
}

Response (GBP)

{
	"id": "2c6e5a71-8b3d-4f99-ae42-1d5f6b7c8d9e",
	"accountId": "4e8a1d20-9c7b-4f33-b512-7d0e9f1a2b3c",
	"partnerFeeId": null,
	"status": "ACTIVE",
	"provider": "OPENPAYD",
	"sourceCurrency": "GBP",
	"targetCurrency": "USDC",
	"blockchain": "POLYGON",
	"purpose": "INVESTMENT",
	"sourceDepositInfo": [
		{
			"rail": "FPS",
			"sortCode": "040075",
			"accountNumber": "82624944"
		}
	],
	"createdAt": "2026-09-29T14:07:52.104Z"
}

Response (EUR)

{
	"id": "1b5d4f60-7a2c-4e88-9d31-0c4f5a6b7c8d",
	"accountId": "9f1c2b7e-3d4a-4c5e-8f10-2a6b7c8d9e01",
	"partnerFeeId": null,
	"status": "ACTIVE",
	"provider": "OPENPAYD",
	"sourceCurrency": "EUR",
	"targetCurrency": "USDC",
	"blockchain": "POLYGON",
	"purpose": "INVESTMENT",
	"sourceDepositInfo": [
		{
			"rail": "SEPA",
			"iban": "GB29NWBK60161331926819",
			"bic": "OPCVGB2LXXX"
		}
	],
	"createdAt": "2026-09-29T14:03:11.482Z"
}

Enhancement:

SEPA routing and cut-off times

SEPA payments settle instantly 24/7/365. Payments of €100k or more submitted between 4:30 PM and 2:30 AM UK time route to SEPA Credit Transfer and settle on the same or next business day. Lumx picks the scheme automatically, so you keep sending rail: "SEPA". See Payment rail cut-off times.

Immediate EUR account activation

EUR accounts now move to ACTIVE right after the customer is APPROVED, instead of waiting up to 1 business day for a banking partner review. GBP accounts activate the same way. See Activation timelines.For complete coverage details, see Coverage.

New Feature

v2.19.0

New account statuses and lifecycle 🏦

New feature:

New account statuses

Accounts now report the full lifecycle: AWAITING_ONBOARDING (account created, customer not yet verified), REQUESTED (customer approved, provisioning requested), REJECTED (account application rejected), and INACTIVE (customer deactivated), in addition to the existing PROVISIONING, RFI, and ACTIVE. The CLOSED status was merged into INACTIVE, and the account.closed webhook event was removed. See Accounts for the lifecycle.

New webhook events

account.awaiting_onboarding, account.requested, account.rejected, and account.inactive fire on the new transitions. During the migration, account creation emits both account.awaiting_onboarding and the legacy account.provisioning, so existing integrations keep working.

Subscribe to the new account.* events on the dashboard’s webhook settings to receive the new lifecycle notifications.

New Feature

v2.18.0

Limit increase requests via API 📈

New feature:

Limit increase requests

Request higher transaction limits for a customer directly through the API:

Upload a supporting document with POST /customers/{id}/documents using one of the new document types: LIMIT_REQUEST_BANK_STATEMENT, LIMIT_REQUEST_TAX_RETURN, or LIMIT_REQUEST_FINANCIAL_STATEMENTS.
Create the request with POST /customers/{id}/limit-requests.
Track it with the read endpoints or subscribe to the customer.limit_request.* webhook events. The status moves from IN_REVIEW to APPROVED, PARTIALLY_APPROVED, or REJECTED.

See the Limit Increase Requests guide.

{
	"requested": {
		"single": "15000.00",
		"daily": "60000.00",
		"monthly": "120000.00"
	},
	"supportingDocumentId": "9d1e2f3a-4b5c-6d7e-8f90-1a2b3c4d5e6f"
}

New Feature

v2.17.0

USD autoconversion rules 💵

New feature:

USD autoconversion rules

Create autoconversion rules for USD accounts: every USD deposit is automatically converted to USDC or USDT and delivered on-chain. sourceDepositInfo carries the bank details for the ACH, FEDWIRE, and SWIFT rails. Each customer can have one active USD rule at a time. See Autoconversion Rules.

{
	"accountId": "a3f8d21c-6e94-4b7a-8c15-9d0e2f4b6a83",
	"targetCurrency": "USDC",
	"purpose": "INVESTMENT",
	"name": "USD → USDC investment"
}

Enhancement:

Optional simulate-deposit reference

reference is now optional on POST /autoconversion-rules/simulate-deposit and is not used for USD simulations.

Enhancement

v2.16.0

New error response contract 🚨

Enhancement:

Standardized error responses

Every error now returns the same envelope with a machine-readable code field, a requestId for support requests, and field-level details in validationErrors on validation failures. Handle errors by code and not by message. See the full catalog in Errors.

{
	"requestId": "9f6f9741-4c65-4e0b-a48f-16d5b34d9e2f",
	"timestamp": "2026-08-10T10:30:45.123Z",
	"path": "/transactions/on-ramp",
	"status": 403,
	"code": "KYC_NOT_APPROVED",
	"message": "KYC/B is not approved for this customer"
}

Enhancement

v2.15.0

IP allowlisting for API keys 🔒

Enhancement:

IP allowlisting

Add allowed IP addresses for each API key on the Developers → API Keys page in the Dashboard. The allowlist applies to production only (https://api.lumx.io), sandbox stays open to requests from any IP. During the current grace period nothing is blocked, even for keys that already have an allowlist. Enforcement starts on September 21, 2026, when the production API begins rejecting requests from IPs outside the allowlist, so register your server IPs before then.

New Feature

v2.14.0

Stellar network support ⭐

New feature:

Stellar network

Pass "blockchain": "STELLAR" on on-ramps and exchange rate requests to settle USDC on the Stellar network. On-ramp only for now. See Coverage and Stablecoin Wallets.

{
	"customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
	"rail": "PIX",
	"sourceCurrency": "BRL",
	"sourceAmount": "10000.00",
	"targetCurrency": "USDC",
	"blockchain": "STELLAR",
	"purpose": "PERSONAL_ACCOUNT"
}

New Feature

v2.13.0

Autoconversion rules 🔁

New feature:

Autoconversion rules

Create a standing rule with POST /autoconversion-rules and every fiat deposit that hits the account is automatically converted to USDC or USDT and delivered on-chain — no per-transaction API call. Available for BRL and MXN accounts for now. See Autoconversion Rules for the full guide.

{
	"accountId": "44dd9734-176a-4ced-924f-103f8d50ea5e",
	"targetCurrency": "USDC",
	"blockchain": "POLYGON",
	"purpose": "INVESTMENT",
	"name": "BRL → USDC investment"
}

New Feature

v2.12.0

New feature:

Reuse an existing Sumsub verification

If your customers already completed KYC on your own Sumsub account, pass a Sumsub share token in the new optional shareToken field when creating a customer to import the existing verification instead of collecting documents again. Only available for individual customers, and requires a data-sharing agreement between you and Lumx — contact compliance@lumx.io to set it up. See the KYC Reuse guide.

{
	"shareToken": "_act-sbx-jwt-token-from-sumsub",
	"type": "INDIVIDUAL",
	"name": "William Default",
	"taxId": "123.456.789-00",
	"birthDate": "1990-01-01",
	"country": "BRA",
	"email": "william.default@example.com",
	"accounts": ["BRL"]
}

Enhancement

v2.11.0

Account provisioning at customer creation 🏦

Enhancement:

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.

{
	"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" }
	]
}

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 for details.

{
	"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"
		}
	]
}

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.

Deprecated

v2.11.0

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.

Resource renamed across the API

The /bank-accounts resource is now /destinations. The bankAccountId field is now destinationId. See 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.

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.

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 to start receiving the new destinations.* events — the old event names will no longer fire.

Deprecated

v2.11.0

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

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.

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 to start receiving the new customer.rfi event.

Deprecated

v2.11.0

Wallets only returned for APPROVED customers 👛

Deprecated:

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 no longer returns wallets. Call Read a customer or register the customer.approved webhook to get notified once verification is approved and the wallets become available.

Enhancement

v2.11.0

Isolated retry for associated party verification 🔁

Enhancement:

Retry verification for specific associated parties

The 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 for details.

Applies only to BUSINESS customers. Resubmit any corrected documents/information for the affected associated parties before starting the retry.

{
	"associatedPartyIds": [
		"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		"b2c3d4e5-f6a7-8901-bcde-f12345678901"
	]
}

EnhancementDeprecated

v2.10.0

Improving customer onboarding 🛩️

Enhancement:

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.

PROOF_OF_ADDRESS document now required

A PROOF_OF_ADDRESS document is now required when uploading documents 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.

{
	"type": "PROOF_OF_ADDRESS"
}

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.

Request body (optional)

{
	"redirectUrl": "https://yourapp.com/onboarding/next-step"
}

Response

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

EnhancementDeprecated

v2.9.0

Webhooks v2 🔔

Enhancement:

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

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 for implementation examples.

New Feature

v2.8.0

MXN support is now live 🇲🇽

New feature:

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.

{
	"sourceCurrency": "MXN",
	"sourceAmount": "10000.00",
	"targetCurrency": "USDC",
	"purpose": "PERSONAL_ACCOUNT"
}

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.

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

New Feature

v2.7.0

Sandbox magic numbers for testing 🪄

New feature:

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

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

Deprecated

v2.6.0

Multiple roles for associated parties 🎭

Deprecated:

Breaking change. Requests using the old role field will be rejected. Update your integration before deploying to production.

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:

{
	"type": "INDIVIDUAL",
	"role": "UBO",
	"name": "Maria Santos",
	"birthDate": "1985-07-10",
	"email": "maria.santos@example.com",
	"taxId": "987.654.321-00",
	"ownershipPercentage": 40
}

After:

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

{
	"type": "INDIVIDUAL",
	"roles": ["UBO", "REPRESENTATIVE"],
	"name": "Maria Santos"
}

New FeatureEnhancement

v2.5.0

KYC/KYB API and idempotency support 🤯

New feature:

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

additionalInformation in customer response

After sending additional information, the customer response now includes an additionalInformation object with all submitted KYC/KYB data.

Multi-level corporate structures

Associated parties now support a parentId field, allowing you to nest shareholders across multiple levels of ownership hierarchy.

{
	"type": "INDIVIDUAL",
	"role": "SHAREHOLDER",
	"parentId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
	"name": "John Smith",
	"ownershipPercentage": 50
}

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 for details.

New FeatureEnhancement

v2.4.0

Individual customers and bank account holders 🥳

New feature:

Individual customer type

Customers can now be created with type: "INDIVIDUAL" for natural persons. Individual customers require name, taxId, and birthDate fields.

{
	"type": "INDIVIDUAL",
	"name": "William Default",
	"taxId": "100.100.100-01",
	"birthDate": "1990-01-01"
}

Individual bank account holders

Bank accounts now support individual holders with the same structure. For counterparty bank accounts, birthDate is optional.

Individual bank account identifier key type as CPF

Bank account now support CPF as a valid keyType identifier for PIX.Enhancement:

New relationship types for bank account holders

Added FRIEND, RELATIVE, and EMPLOYEE to the available relationship types for bank account holders.

New FeatureEnhancementDeprecated

v2.3.0

Multi-blockchain support 🔥

New feature:

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.

{
	"wallets": [
		{
			"blockchain": "POLYGON",
			"address": "0x...",
			"blockExplorerUrl": "https://polygonscan.com/address/0x...",
			"isDefault": true,
			"balances": [{ "stablecoin": "USDC", "balance": "1000.00" }]
		}
	]
}

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.

{
	"blockchain": "BASE",
	"sourceCurrency": "BRL",
	"sourceAmount": "1000.00",
	"targetCurrency": "USDC"
}

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:

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.

wallet and balances fields deprecated on customers: Migrate to the new wallets array. Affected endpoints: POST /customers, GET /customers.
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.

EnhancementDeprecated

v2.2.0

Transaction limits response improved ⚡

Enhancement:

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.

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

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.
transactionLimits removed from customer listing: The GET /customers endpoint no longer returns the transactionLimits field in the response array.
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.

New FeatureEnhancement

v2.1.0

SEPA and SWIFT are live 🚀

New feature:

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.

{
	"rail": "SEPA",
	"sourceCurrency": "EUR",
	"sourceAmount": "10000.00",
	"targetCurrency": "USDC",
	"purpose": "PERSONAL_ACCOUNT"
}

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.

{
	"rail": "SWIFT",
	"sourceCurrency": "USD",
	"sourceAmount": "10000.00",
	"targetCurrency": "USDC",
	"purpose": "PERSONAL_ACCOUNT"
}

For complete coverage details, see Coverage.Enhancement:

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.

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.

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.

New FeatureEnhancement

v2.0.0

Bank Accounts are live 🎉

New feature:

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 for details.Enhancement:

PROCESSING status renamed to TRANSFERRING_STABLECOIN
state.blockchain moved to state.receipt

The new receipt object includes transactionHash and blockExplorerUrl fields for better transaction tracking.

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.

On-ramp: payment.rail moved to request level rail
Off-ramp: customerId and payment object removed, use bankAccountId only
Exchange Rate: rail and customerId parameters now required

​Preparing for our Brazil VASP license 💜

​Accepted values

​GBP accounts and FPS are live 🇬🇧

​New account statuses and lifecycle 🏦

​Limit increase requests via API 📈

​USD autoconversion rules 💵

​New error response contract 🚨

​IP allowlisting for API keys 🔒

​Stellar network support ⭐

​Autoconversion rules 🔁

​KYC reuse with Sumsub share tokens 🔁

​Account provisioning at customer creation 🏦

​Bank accounts renamed to destinations 📦

​TEMPORARY_REJECTION renamed to RFI ✏️

​Wallets only returned for APPROVED customers 👛

​Isolated retry for associated party verification 🔁

​Improving customer onboarding 🛩️

​Webhooks v2 🔔

​MXN support is now live 🇲🇽

​Sandbox magic numbers for testing 🪄

​Multiple roles for associated parties 🎭

​KYC/KYB API and idempotency support 🤯

​Individual customers and bank account holders 🥳

​Multi-blockchain support 🔥

​Transaction limits response improved ⚡

​SEPA and SWIFT are live 🚀

​Bank Accounts are live 🎉

Preparing for our Brazil VASP license 💜

Accepted values

GBP accounts and FPS are live 🇬🇧

New account statuses and lifecycle 🏦

Limit increase requests via API 📈

USD autoconversion rules 💵

New error response contract 🚨

IP allowlisting for API keys 🔒

Stellar network support ⭐

Autoconversion rules 🔁

KYC reuse with Sumsub share tokens 🔁

Account provisioning at customer creation 🏦

Bank accounts renamed to destinations 📦

`TEMPORARY_REJECTION` renamed to `RFI` ✏️

Wallets only returned for APPROVED customers 👛

Isolated retry for associated party verification 🔁

Improving customer onboarding 🛩️

Webhooks v2 🔔

MXN support is now live 🇲🇽

Sandbox magic numbers for testing 🪄

Multiple roles for associated parties 🎭

KYC/KYB API and idempotency support 🤯

Individual customers and bank account holders 🥳

Multi-blockchain support 🔥

Transaction limits response improved ⚡

SEPA and SWIFT are live 🚀

Bank Accounts are live 🎉