Hybrid Payment Ruleset

The complete set of rules governing Wallet Initiated Payment (WIP) Hybrid transactions, for both the Full and Partial flows.

This page is the authoritative reference for ECR integrators, PSPs, and WSPs working with the Aera Wallet hybrid payment flows. Every rule below is enforced by the Wallet during transaction processing — understanding them is essential to predict outcomes, build correct error handling, and reconcile sub-transaction reporting.

For walkthrough examples of each rule in action, see the Wallet Payment Scenarios documentation. For the full list of response codes referenced on this page, see Response codes.

---

📚 Table of Contents

1. What is a Hybrid payment?
2. Choosing a flow: Full vs Partial
3. Rules common to both flows
4. Interpreting transactionDetails
5. Full Hybrid Payment rules
6. Partial Hybrid Payment rules
7. Allocation and prioritization
8. Payment-method-specific rules
9. Response codes used in hybrid payments

---

What is a Hybrid payment?

A Wallet Initiated Payment (WIP) Hybrid transaction settles a single basket across multiple payment methods in one customer authentication, using whichever instruments the customer holds in their Wallet that the merchant also accepts.

Today the Wallet can hold:

• Monizze vouchers (Meal vouchers, Eco vouchers)
• Xtra (Colruyt SDD)

Bancontact is referenced in some allocation scenarios for illustration but is not yet implemented.

The ECR is always the initiator of a WIP Hybrid sale and controls:

• Which flow to use — fullPayment: true (Full) or fullPayment: false (Partial).
• The total transaction amount.
• The amount allocated per voucher category (e.g. FOOD, ECO).
• The order in which categories appear in the request — this determines the deduction order the Wallet applies first.
• Whether to include a withdrawal (cashback / cashout) — not currently supported.

The customer can choose which payment instrument is used and, in some cases, reprioritise instruments — but the ECR's category ordering and totals are non-negotiable.

---

Choosing a flow: Full vs Partial

🚧

TBD

---

Rules common to both flows

These rules apply identically regardless of whether fullPayment is true or false.

Transaction-level reporting

• The ECR receives a single root responseCode indicating success or failure of the transaction as a whole.
• The amount within the amountDetails on the root level tells what has been successfully authorized.
• The ECR also receives a transactionDetails array containing one entry for every authorisation the Wallet attempted — including attempts that failed. One entry per payment method, and, for vouchers, one entry per voucher category used.
• Every sub-transaction carries its own transactionId, responseCode, externalResponseCode, amountDetails, and scheme. Please note that transactionId can be null, for example if the authorization has failed for this sub-transaction.
• The responseCode on the root level tells the ECR the overall outcome; the per-sub-transaction responseCode tells you what actually happened to each instrument. See Interpreting transactionDetails for how to walk the array.

Amounts are in minor units

All amountDetails.amount values — at the root level and inside transactionDetails — are expressed in minor units of the currency (i.e. cents for EUR). An amount of 2455 represents €24.55.

Voucher and category rules

• A voucher sub-transaction always carries a category field indicating the voucher type used (e.g. FOOD, ECO).
• A single sub-transaction is never split across two voucher types. If an amount is allocated to both FOOD and ECO voucher types (see Multi-category amounts), it produces separate sub-transactions per voucher type.
• The ECR can sum sub-transaction amounts per voucher type to verify they match the original per-category allocation in the request.

Multi-category amounts

When an amount in the request is annotated with multiple categories (e.g. ["FOOD", "ECO"]), the Wallet decides the split between voucher types based on:

1. The WSP's configured priority.
2. The balances available on the customer's voucher instruments.

The Wallet does not report which portion of the multi-category amount went to which voucher type. The contract is that the sum of sub-transactions per voucher type matches the totals the ECR can derive from the request.

ECR controls deduction order, not customer

The customer can choose which payment instrument to use and reprioritise instruments where the WSP allows it. The customer cannot change the order in which voucher categories are deducted — that is fixed by the ECR's request order.

Cashback / cashout

Withdrawal amounts are not supported in the current version of the WIP Hybrid flows.

---

Interpreting transactionDetails

The transactionDetails array is the most important part of every hybrid response. It reports every authorisation the Wallet attempted, whether the attempt succeeded or failed. The ECR must inspect each sub-transaction's responseCode to determine what actually happened.

Every attempt is reported, with its attempted amount

For every payment method (and, for vouchers, every category) the Wallet touched during the transaction, a sub-transaction entry is produced — including:

• Successful authorisations.
• Failed authorizations that were subsequently reallocated to another payment method (Full flow).

Failed sub-transactions report the amount that was attempted against that instrument. They are never zeroed out.

📘

Why every attempt is exposed

Reporting every attempt — with the attempted amount intact — is a hard requirement, not an implementation choice. Four reasons drive it:

1. Scheme requirements. Aera is required by the payment schemes to expose what was attempted to the end customer, because the result the customer sees may differ from the payment proposal that was originally presented to them.
2. Acquirer (Xtra / Colruyt) requirements. The ECR is responsible for presenting the payment result on the customer's device. Xtra additionally surfaces the same transaction in their own app's transaction history. Both views must reconcile.
3. Aera transparency. The payment proposal and the funds actually deducted may differ — for example, when a balance changed mid-flow or a reallocation was triggered. The customer is entitled to see the difference.
4. Partial-flow correctness. In Partial Hybrid, failed amounts must be reported with their attempted value so the customer is informed of what didn't go through. Setting them to zero would breach customer-information requirements and make remaining amount impossible to reconcile against the proposal.

How to determine what was actually paid

Walk the transactionDetails array and inspect each entry's responseCode:

To compute what the customer actually paid through the Wallet:

deducted = sum of amountDetails.amount where responseCode == 68611

• In a successful Full Hybrid (responseCode == 0 at the root level), deducted is guaranteed to equal amountDetails.amount at the root level.
• In a Partial Hybrid, deducted == amountDetails.amount at the root level.
• In a failed Full Hybrid, any sub-transactions with responseCode == 68611 are cancelled with the relevant acquirers, regardless of what the array shows had succeeded along the way. Cancellation is not immediate; the underlying funds may be held briefly on the customer's instrument. See Authorisation holds and cancellation timing.

📘

For the full list of response codes referenced on this page and elsewhere, see the Wallet response codes and PSP response codes.

Worked example

Take a successful Full Hybrid payment where Monizze failed and Xtra absorbed the reallocation:

• Root: responseCode: 0, amount: 2455 (€24.55).
• transactionDetails:
  • MONIZZE FOOD — responseCode: 68612, amount: 700 → failed, reallocated.
  • XTRA — responseCode: 68611, amount: 2455 → succeeded.

Sum of successful sub-transactions: 2455. Matches amountDetails.amount on the root level: 2455. The customer was deducted €24.55 in total, all from Xtra. The Monizze entry is reported so the customer can see that a €7.00 attempt was made against their meal voucher and failed — even though the basket was ultimately covered.

---

Full Hybrid Payment rules

Activated by "fullPayment": "true" in the WIP request.

1. Coverage is binary

The whole transaction must be coverable by the available payment methods in the Wallet. If it cannot be fully covered, the transaction is returned to the ECR as failed and no funds are deducted — any authorisations that succeeded along the way are cancelled with the relevant acquirers.

2. Pre-authorisation balance check

When all payment methods involved in the transaction support balance checks (today: Monizze and Xtra), the Wallet performs a balance check before building the allocation plan.

• If the combined available balance is sufficient, the Wallet proceeds to allocation.
• If the combined available balance is insufficient, the transaction fails at this step — before the customer is shown a payment proposal — with:
  • responseCode: 1012, externalResponseCode: 68600 on the root level in the merchant callback.
  • No sub-transactions are produced, meaning no transactionDetails array is provided.
  • No amount in amountDetails.amount on the root level, since this field is only used for authorized amounts.

If at least one payment method involved does not support balance checks (e.g. Bancontact, once available), the pre-authorization balance check is skipped for the un-checkable methods and authorisation is attempted blindly.

3. Reallocation on authorisation failure

If a payment method is reached at the authorisation step and the authorisation fails, the Wallet does not give up. It reallocates the failed amount onto the next payment method down the priority list and re-attempts.

• The reallocated amount is added on top of any amount already destined for that next method.
• If the next payment method has a known balance and it does not cover both the already allocated amount and the reallocated amount. Then only the amount up to available balance will be reallocated to this payment method. The remaining amount is then reallocated to the next payment method (if any).
• If the cascade reaches the end of the priority list with funds still uncovered, the transaction is failed and all previously authorised amounts are cancelled with the relevant acquirers.

A reallocated transaction that ultimately succeeds is reported with both the failed sub-transaction (responseCode: 68612, carrying the attempted amount) and the successful downstream sub-transaction (responseCode: 68611) in transactionDetails. See Interpreting transactionDetails for how to read this correctly.

4. Successful sub-transaction totals match the root amount

When the transaction succeeds (responseCode: 0, externalResponseCode: 0), the sum of amountDetails.amount across all sub-transactions where responseCode == 68611 equals the root amountDetails.amount. Failed sub-transactions in the same array are excluded from this sum — they exist for customer transparency, not for accounting.

5. Authorisation holds and cancellation timing

When a Full Hybrid transaction fails after one or more sub-transactions have already been authorised — for example, a reallocation cascade that exhausts without coverage — the Wallet cancels each previously successful authorisation with the relevant acquirer. No funds ultimately move out of the customer's account.

Cancellation is not instantaneous. Authorisations are cancelled 90 seconds after they were made at the earliest. The exact delay is set by the acquirer and scheme rules; the payment methods Aera currently supports all use 90 seconds. This delay exists to avoid a race condition where a cancellation could collide with a capture and the customer ends up double-deducted, requiring a reversal or refund to put right.

What this means for the customer. During the cancellation window, the authorised amount is held on the payment instrument and cannot be spent. If the customer immediately re-attempts a payment using the same instrument, the available balance on that instrument will be lower for the duration of the hold. Once the cancellation processes, the held amount becomes available again as normal — no manual action required from the ECR or the customer.

What this means for the ECR. The ECR's response is final the moment the Wallet returns it; no further callback is sent when the underlying authorisations are eventually cancelled. ECR-side support and customer-care tooling should be aware that the customer's balance on cancelled instruments may briefly lag the transaction outcome.

6. No remaining amount

Remaining amount is a Partial-flow concept and is never returned in a Full flow response.

---

Partial Hybrid Payment rules

🚧

TBD

---

Allocation and prioritisation

Three things determine which payment method is asked to deduct what amount, and in what order:

1. WSP-configured priority

The WSP has the option to fix a priority order for payment methods and voucher types. In most deployments the WSP delegates this to the customer. When the WSP has not fixed an order, the customer's preferences take effect.

2. Customer-chosen order

The customer can reprioritise payment methods (e.g. put Bancontact above Xtra) from their device. The customer cannot reprioritise voucher types, only deactivate/activate them.

3. Balance-check skip

If a payment method supports balance checks and the check shows zero available balance, that method is skipped in the allocation plan — the Wallet moves on to the next method without attempting an authorisation against it.

The combined effect of these three rules produces the allocation plan the Wallet then attempts to authorise.

---

Payment-method-specific rules

Xtra (Colruyt SDD)

• Supports balance checks.
• A Wallet may onboard only one Xtra account. All other payment methods support multiple instances per Wallet. This rule is handled by CG not Aera.

Monizze

• Supports balance checks. Will not be utilized in transactions if balance check fails during distribution process.
• Multiple Monizze accounts can be onboarded to a single Wallet.
• Each Monizze account can carry both a FOOD voucher and an ECO voucher balance.
• Onboarding the same Monizze account twice into a single Wallet will just override the existing Monizze payment method.

Bancontact (planned, not yet implemented)

When live, Bancontact will follow these rules:

• No balance check support. Authorisation is attempted blindly.
• In allocation: if Monizze and Xtra together cannot cover an amount, the residual is allocated to Bancontact and authorisation is attempted blindly. This occurs only if Bancontact is prioritized below Xtra.
• In reallocation: if a customer has placed Bancontact above Xtra in their priority order, the Wallet attempts Xtra only if Bancontact fails.

---

Response codes used in hybrid payments

The codes below are the ones most commonly seen in WIP Hybrid responses. For the full catalogue, see Response codes.

Root-level codes

Sub-transaction codes (inside transactionDetails)

When a sub-transaction reports 68612 in a Full flow that ultimately succeeded, the failed amount has been reallocated successfully — the ECR sees both the failed sub-transaction (with attempted amount) and the successful downstream sub-transaction in the same response. See Interpreting transactionDetails for how to derive what was actually paid.

---

See also

• Wallet Payment Scenarios — worked examples of every rule on this page.
• Request examples — payload templates for Full and Partial Hybrid requests.
• Response codes — full code catalogue.
• Supported payment methods — current list of payment instruments and their capabilities.