Virtual account reconciliation: deposit to ledger balance

Virtual account reconciliation is matching each deposit on a customer's virtual account to its customer, the invoice or balance it settles, and the ledger entry that records it. On USD, EUR and GBP accounts the account identifies the payer. Pix (Brazil) and SPEI (Mexico) carry an identifier or memo.

This guide follows one deposit from the payer's bank to a ledger balance, for teams running named virtual accounts (local account numbers issued in the customer's own name) for their own customers. The accounting treatment is in a separate guide on reconciling stablecoin transactions.

Does a virtual account really remove the payment reference?

On USD, EUR and GBP it does, and on Pix and SPEI the reference moves into a code or a memo. On the account rails, the match moves from a field the payer types to an account number the payer must get right for the money to arrive at all. A payer can leave the reference blank, pay from a parent company or send an odd amount, and the deposit still lands on the right customer.

Pix (Brazil's instant payment system) carries the reference inside the payment code, and SPEI (Mexico's interbank transfer system) takes it as a memo.

What matches a deposit to its customer, by rail, from the Lumx documentation read on November 1, 2026.

A Pix scan is enough, because the identifier travels inside the code. SPEI takes the memo next to the CLABE (the 18-digit Mexican bank account number), and a blank or mistyped memo is the first suspect when a deposit does not match. On a shared account, every rail would behave like SPEI, and the reference would be the only key, which is the trade-off covered in named virtual accounts vs pooled accounts.

A Lumx account is issued by a banking partner in the customer's name, holds one currency, and a customer can hold several. A customer has one active autoconversion rule per USD, EUR or GBP account, because those deposits are matched to the account and a second rule would be ambiguous. Rules on BRL and MXN accounts have no such limit, since each carries its own identifier.

A worked week: seven deposits on four accounts

The matching key gets a deposit to the right customer. Everything after that is invoice logic you write.

Illustrative example. A B2B software platform has four customers, each with one named account, and seven deposits arrive in one week. Names and amounts are invented.

Deposits 1, 2 and 6 post themselves. Deposit 3 is the one the account cannot fix, and only SPEI produces it. With several autoconversion rules on one MXN account, the memo or reference picks the rule. Without it the MXN still lands on the account and converts at the normal floating rate, but no rule applies. On USD and EUR, a deposit with no on-ramp and no active rule just sits as fiat on the account until you act. Deposits 4, 5 and 7 are known customers with an open invoice question, which is easier than "who paid?". Deposit 5 is a third-party collection, which Lumx allows by design. One that looks unusual can trigger an RFI (request for information) and, as a result, a return. Deposit 4 is a timing case. The Lumx timelines are processing targets, not guarantees, and the sender's bank sets its own cut-off, so a late Friday deposit can take a business day longer. Your ledger has nothing to post until the first event arrives.

Take deposit 1 through the numbers. In the Lumx documentation's sample receipt, BRL 10,000.00 converts at a base rate of 5.25 to 1,904.76 USDC. The receipt itemizes a Lumx fee of 9.52 and a partner fee of 3.81 and ends at a final 1,891.43 USDC, an effective rate of 5.29. Invoices match on the BRL that arrived. Treasury books the 1,891.43 USDC that reached the wallet, and a ledger that mixes the sides makes every invoice look short.

The same logic applies to B2B collections on named accounts, and to a company in Brazil receiving USD payments.

Post the deposit as pending, then as available

Write the ledger entry the moment the first event arrives, mark it pending, and move it to available only on the final success event. Mixing the two shows a customer a balance for money still in transit, then makes it disappear.

Three states cover it. Pending means the deposit was processed and is converting. Available means the stablecoin reached the wallet. Reversed means the transaction failed and the pending entry is taken back. A late event for an earlier step must never move an available entry back to pending: status only advances.

Key every entry on the Lumx transaction id, because an amount-and-date key merges two same-amount deposits on one day.

A deposit matched by an autoconversion rule runs as an on-ramp, and its events start at onramp.transferring_fiat, then trading, transferring_stablecoin and success. The first event is also the first moment your ledger can write the pending entry.

What to store on every deposit row

Store the identifiers that join to your records and every amount the receipt gives you, not only the amount you expected.

Fields to keep per deposit, and why, from the Lumx webhook payload and sample receipt.

For a named-account deposit, the join to your books is the customer id plus the transaction id. The rule creates the transaction, the rule request has no metadata field, and so a rule-driven deposit carries none. The metadata field is for on-ramps your platform creates: it is set at creation and cannot be added afterwards, so rows without it are reconciled by hand.

The receipt on a successful Lumx transaction carries the amounts and rates, the fees, and the transaction hash. Read the receipt, not the request, because the request holds what was asked for and the receipt holds what happened. The webhook guide lists the payload fields.

Webhooks for speed, the API for truth

Use webhooks to move entries forward as events arrive, and the API read to settle what you are unsure about. After an outage on your side, the paginated read of transactions is the record you trust, because a ledger fed only by events will have gaps.

Expect the same event twice, so deduplicate on the webhook id. Flag any status you do not recognize instead of mapping it to the nearest known one.

Lumx retries a webhook when your endpoint does not return a 2xx response: eight attempts, from immediate to twice after 10 hours. After the last attempt the message is marked failed and can be retried from the dashboard. Each event carries the transaction id, so one deposit produces one row that moves forward. The awaiting_funds and expired statuses belong to on-ramps you create for a single expected deposit, not to rule-driven ones.

Closing the day: ledger, Lumx records and wallet

At the end of each day, check three records against each other and write down every difference with a reason. The three are your ledger, the transaction records from Lumx for that date, and the stablecoin balance in the wallet. The ledger says what you promised, the Lumx records what was processed, the wallet what arrived.

Every available entry should have a successful transaction and a hash on the receipt. Every pending entry should be inside its rail's window. Every difference should land in one of four buckets: late, failed, unmatched, or under the minimum. The payment rail timelines are Lumx processing targets, and a deposit sent late in the day, on a weekend or on a bank holiday can take a business day longer, so it is late, not broken. The US$ 50 minimum applies to every deposit, and a smaller one is not converted, and operations@lumx.io is where to ask about it. A deposit above the on-ramp limit is held as a balance until it is resolved. Unmatched means the deposit arrived but no rule applied: an MXN deposit without a memo converts at the floating rate, and a USD or EUR deposit with no active rule stays as fiat. The transaction check alone will not surface the second kind, so list the fiat balances on the accounts as part of the close.

I recommend mapping every customer id to your own customer record before the first deposit arrives, and never closing a day with an unexplained row. I would keep one suspense account for unmatched deposits, give it a named owner, and escalate any row still there after two business days.

The records for the daily check come from reading Lumx transactions with a page size of up to 100 and a cursor. The ledger and the match are yours. The docs include a prompt that builds a reconciliation ledger with late and failed as different states.

Payments that do not match the invoice need rules before launch

A virtual account tells you who paid. It does not tell you what they meant. Write the rules before the first customer pays, not per ticket.

Rules to write before launch for payments that do not match the invoice.

Each matched deposit is converted and delivered with its receipt, and the invoice rules stay in your system. Lumx sees the customer and the transaction, not your invoices.

When a virtual account is the wrong tool for reconciliation

One account per invoice is the first case. Each account goes through verification, so a new account per invoice adds a review step to every sale. For a single expected deposit with an exact amount, create an on-ramp transaction for that amount and let the payment details come back with it. That transaction has a payment window, so it can expire, and a deposit that lands after expiry is not processed and is refunded to the original sender on the same rail. That is the case your ledger maps to reversed.

Collecting for your customers' own clients through one account is the second case. Pooling several parties' funds is the nested-payments pattern, which needs written approval from Lumx compliance.

Very low volume is the third case: five deposits a month fit a spreadsheet.

What a Pix deposit looks like from account to ledger on Lumx

Lumx is stablecoin payments infrastructure for businesses that move money between Latin America and the rest of the world: one API to collect, hold, convert, and pay out in BRL, MXN, COP, USD, EUR, and GBP or in USDC and USDT, over local rails such as PIX, SPEI, PSE, Bre-B, ACH, FEDWIRE, SEPA, and Faster Payments, with SWIFT and on-behalf-of payments and collections (POBO and COBO) in USD, EUR, and GBP, plus named virtual accounts, custodial wallets, and KYB/KYC built in.

Your platform creates the customer with the currencies it needs, and the account waits for verification. BRL, MXN, EUR and GBP accounts reach active right after approval, and USD takes up to one business day, so the account.active event is the moment to show payment details. Your platform then creates an autoconversion rule on the BRL account, which returns a Pix code that embeds the identifier, and the payer scans it.

From there, the events arrive in order. Your ledger writes a pending entry on onramp.transferring_fiat, keyed on the transaction id, and posts the available entry when onramp.success arrives with the receipt. The receipt shows the Lumx fee and any partner fee separately, and Pix is instant, so pending is short. If a status or event name changes, the Lumx changelog is where renames are announced, and your state map should be checked against it.

Confirm the account you need on the coverage page, and see global payments for how collection fits with payouts. See also the named virtual accounts page.

Verified on November 1, 2026. Operational context, not legal, tax, or investment advice.

Cover photo: Amadeus Moga on Unsplash.