Schemas and Reconciliation

Virtual accounts can be structured according to different operational schemas. These schemas define the strategy for assigning account details to transactions, submerchants, or users. Understanding these schemas is essential for designing an effective payment infrastructure and implementing the correct reconciliation logic to identify the source and purpose of each incoming payment.

Virtual Account Schemas

A schema defines the relationship between virtual accounts and the entities they represent. Choose a schema based on your business model to determine the optimal payment tracking and reconciliation strategy.

1. Per Transaction

In the Per Transaction schema, you create one unique Virtual Account per transaction. It is used only once, and then deleted.

How it Works

1. You create a Virtual Account before initiating a transaction.
2. Once the payer transfers the funds, you receive a webhook containing all the information necessary for reconciliation.
3. You delete the account after the payment is completed.

Reconciliation

Matching is extremely simple: You reconcile the payment by comparing the Virtual Account number returned in the webhook with the Virtual Account you created for that transaction.

2. Per Submerchant

In this schema, you assign one Virtual Account per submerchant, branch, or business unit. For example, a marketplace could assign one Virtual Account to each seller.

How it works

1. Every submerchant receives its own dedicated Virtual Account.
2. All incoming payments through that account belong to that specific submerchant.
3. To identify individual transactions, you use additional webhook fields.

Reconciliation

You match payments by first identifying the Virtual Account and then confirming the specific transaction using one or more of these fields:

• amount
• payer.name / payer.lastName
• payer.document.id (when available)
• payer.email (when available)
• payer.bank.account.number
• date.creationDate or date.processedDate
• tracking object

This schema is ideal for marketplaces, multi-branch businesses, or any structure where payments must be grouped by entity.

3. Per User

In this schema, each end user receives one permanent Virtual Account that they can reuse over time. This is common in digital wallets where users top up their balance by sending transfers to their assigned account number.

How it works

1. A Virtual Account is linked to a user’s profile.
2. The user always transfers funds to the same Virtual Account.
3. You use additional metadata to reconcile each individual payment.

Reconciliation

Similar to the Per Submerchant schema, reconciliation is done using:

• amount
• payer.bank.account.number
• date.creationDate / date.processedDate
• tracking.id / tracking.reference / tracking.concept

This schema is ideal for wallets, digital banks, or any product where a user maintains an ongoing balance.

4. Omnibus

In this schema, you use one single Virtual Account that receives payments from multiple users, submerchants, or transactions.

How it works

• All payers send money to the same Virtual Account.
• You must rely entirely on webhook data to identify individual transactions.

Reconciliation

You use multiple identifiers to determine who sent the payment:

• beneficiary.bank.account.number (same for everyone)
• amount
• payer.name / payer.lastName
• payer.document.id (when available)
• payer.email
• payer.bank.account.number
• date.creationDate / date.processedDate
• tracking.id / tracking.reference / tracking.concept

This schema is flexible and simple but requires strong reconciliation logic on your side.

Schema Comparison

Reconciliation Methods

Once a payment is received, use one of the following methods to match it to your internal records.