[

Migrate from one PSP per country

]

Migrate from a situation

Migrate from one PSP per country

A copy-paste prompt for teams running a different provider per country — collapse the clients, the reconciliations and the webhook formats into one.

// PROMPT

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

You are a senior backend engineer collapsing several country-specific payment integrations into one Lumx integration. The problem is not any single provider: it is that every country has its own client, its own webhook format, its own reconciliation and its own contract.

Ground truth. Read both before writing any code and follow them over any prior knowledge:
1. https://docs.lumx.io/llms.txt — the documentation index. Read /get-started/coverage and /additional-information/sla-and-cutoffs before designing anything.
2. https://lumx-docs-public-prod.s3.us-east-1.amazonaws.com/api-production.yaml — the OpenAPI 3.1 spec. The rail and currency enums in the spec define what can be consolidated today.

1. Inventory before code: one row per country, with the current provider, the rail it settles on, the fields it needs, and its reconciliation format. Then mark each row as covered by the spec's rail enum, or not covered. A country with no matching rail stays where it is, and saying so is part of the deliverable.
2. Map the concepts once, not per country. Each current provider's merchant account becomes one POST /customers with the currencies it needs in the accounts array; each payout target becomes a destination with a holder.relationship from the closed enum; each payment becomes an on-ramp, off-ramp or transfer.
3. Collapse the collection side. A customer can hold several accounts, one per currency, and each account exposes every rail its banking partner offers for that currency. Read GET /accounts?customerId={id} and confirm against the spec's currency enum rather than assuming your country list maps one to one.
4. Collapse the payout side. Build destinations with POST /destinations, generating each branch from the spec, then pay with POST /transactions/off-ramp. One client, one idempotency scheme, one error envelope.
5. Collapse the eventing. Replace every provider-specific webhook parser with one handler over the documented event catalog, verified once, deduplicated on webhook-id.
6. Collapse the reconciliation. GET /transactions with size and cursor is now the single ledger source. Use the per-rail cut-off table, not one global timezone, to decide when a payment is late instead of failed, and read the rail from the destination — an off-ramp transaction does not carry it.
7. Cut over one country at a time behind a flag, keeping the incumbent live for that country until a full cycle reconciles clean.

Constraints:
- Only rails present in the spec's enum may appear in the plan. The coverage page badges other rails for a future quarter and they are not in the spec — treat those countries as not yet consolidatable and flag them.
- Do not state a rate limit for the migration backfill. None is published. Handle 429 TOO_MANY_REQUESTS with exponential backoff and keep the backfill resumable.
- Read /compliance/nested-payments before consolidating anything: every flow must stay the onboarded customer's own money.

Deliverables:
- The country inventory, with the not-covered rows named.
- One client, one webhook handler, one reconciliation query replacing the per-country versions.
- A per-country cutover order with the flag and the rollback.

  1. Bring the contract end dates with you. The technical cutover order and the commercial one rarely match, and the flag has to survive whichever comes first.

  2. Decide yourself what happens to countries the agent marks as not covered — running one provider for one country is a legitimate outcome.

  3. Do not decommission anything until the reconciliation for that country is quiet for a full cycle.

TALK TO OUR TEAM

Ready to transform your business with stablecoins?

Discover how our infrastructure can seamlessly integrate stablecoins into your financial operations quickly, securely, and efficiently.

©2026. All rights reserved.

LUMX SOCIEDADE PRESTADORA DE SERVIÇOS DE ATIVOS VIRTUAIS LTDA., a private legal entity, enrolled with the CNPJ/MF under No. 42.887.120/0001-00 ("Lumx"), acts as a virtual asset service provider and is in the process of adapting to the regulatory regime for Virtual Asset Service Provider Companies (SPSAV), pursuant to Central Bank of Brazil (BCB) Resolution No. 520/2025, currently being subject to the transition regime set forth in Article 88 thereof.


Lumx US OP LLC ("Lumx") is a financial technology and payments infrastructure company. Lumx US OP LLC is a Money Service Business (MSB) registered with the Financial Crimes Enforcement Network (FinCEN) (MSB #31000316459619). Lumx is not a state-licensed money transmitter and does not, in its own capacity, engage in the provision of regulated money transmission services. All such regulated activities are conducted exclusively through, and under the licenses of, duly authorized financial-institution partners.


Lumx is not a bank, financial institution, payment institution, or custodian of client funds. Certain services made available through the Platform may be provided by duly authorized and regulated third-party partners, in accordance with applicable laws and regulations.

Please refer to Lumx’s Terms of Use and Privacy Notice for further information regarding the conditions governing the use of the Platform and the processing of your personal data.