Mix Payment

What is Mix Payment ?

HiPay Mix Payment allows you to offer your customers the option to pay for a single purchase using several complementary payment methods: for example, a gift card combined with a credit card.

  • Gift cards Illicado, Epay combined with a credit card
  • Flexible amounts The customer chooses the exact amount to use from their gift card
  • +40% average cart value Case measured at Aubert: gift cards increase the cart value

Mix Payment is only available via Hosted Page or iFrame. Hosted Fields integration is not supported.

Activation Prerequisites

  • Activation request to your HiPay PayOps team A validation by the Risk department is systematically performed before activation.
  • Dedicated escrow account A specific HiPay technical account for Mix Payment is required. It is configured by HiPay.
  • At least one gift card payment method activated Illicado and/or Epay (gift cards) must be activated on your merchant account.
  • At least one complementary payment method Credit card (Visa, Mastercard, CB, AMEX), PayPal, Bancontact, Alma, or Paysafecard.

How does it work?

The HiPay Hosted Page automatically detects if the gift card balance is insufficient to cover the total amount, and then offers the complementary payment methods.

  • Gift card balance ≥ total amount → Standard payment (no Mix Payment)
  • Gift card balance < total amount → Mix Payment triggered automatically
  • Gift card balance = €0 → Transaction declined + Forced Mix Payment

Features available to the customer

  • Real-time balance check
  • Choice of the exact amount to use from the gift card
  • Addition of up to 10 gift cards
  • Removal of an added gift card
  • 1-click payment

Payment Flow

    1. Cart confirmation The customer validates their cart on your website.
    2. Redirection to the Hosted Page The customer is redirected to the secure HiPay payment page.
    3. Gift card entry Entry of the gift card number and PIN code. The balance is checked in real-time.
    4. Complementary method entry If the balance is insufficient, the buyer enters their credit card or chooses another complementary method.
    5. Single click on Pay The secure sequence is triggered automatically.
    6. Automatic secure sequence Credit Card Verification → Credit Card Authorization → Gift Card Capture → Credit Card Capture. If the credit card fails, the gift card is never charged.
    7. Confirmation Confirmation page summarizing all transactions. Notification sent to your URL.

Back-Office Management Each Mix Payment transaction generates a parent transaction and several child transactions (one per payment method used).

    • Parent Transaction Global summary — total amount — order_id
      • Child Trx 1 Gift card 1
      • Child Trx 2 Gift card 2
      • Child Trx 3 Credit card

Refunds Possible on the parent transaction and the child transactions. An additional parameter in the refund API allows you to target a specific child transaction.

Chargebacks Processed only on the disputed card. No impact on the other child transactions.

FAQ – Frequently Asked Questions

How many gift cards can be used per transaction? Up to 10 gift cards per transaction (configurable limit).

Does Mix Payment work with all my payment methods? No. It only works with compatible payment methods: Illicado, Epay, and activated complementary methods (eg. Credit card, PayPal, Bancontact, Alma).

What happens if the gift card is expired? Illicado cards can be used up to 1 month after their expiration date. Epay cards are immediately declined if expired.

Are refunds automatic? Yes. Via the HiPay refund API, child transactions are automatically identified and refunded. You can also target a specific child transaction with a dedicated parameter.

Is Mix Payment available on mobile? Yes, via the mobile-adapted Hosted Page or the iFrame integrated into your checkout process.

How to activate Mix Payment? Contact your HiPay PayOps team. Activation requires a Risk validation and the configuration of a dedicated escrow account.

Developer guide

Overview

Mix Payment via API Order allows you to orchestrate the multi-method payment flow yourself by directly using the HiPay Gateway REST API. You have two main endpoints available:

    • POST /rest/v3/gift-card/consult Gift card balance consultation
    • POST /rest/v1/order Creation of a payment transaction (mix or standard)

Mix Payment via API Order (headless mode) is distinct from Mix Payment via Hosted Page. In API Order mode, you manage the flow yourself through several successive calls.

Technical Prerequisites

    • Merchant credentials (Basic Auth) provided by HiPay for each merchant account.
    • Multiple payment products activated At least one gift card (illicado or epay) AND a complementary method (eg. visa, mastercard, paypal, bancontact, alma).
    • Maximum payment attempts > 1 In the account configuration (BO Console, ‘Maximum number of payment attempts per session’ field), the value must be > 1 to allow sub-transactions.

Gift Card Balance Consultation API

Check the available balance and the limit of a gift card before creating the order, in order to calculate the amount_to_capture for the complementary credit card.


See API Gateway – POST /rest/v3/gift-card/consult

Note: In the event of an error during consultation (invalid card, network timeout…), the API returns a balance of 0 to prevent an impossible payment. Your integration must handle this scenario.

Calculating amount_to_capture
amount_to_capture = total_order_amount - min(balance, ceiling)

Example:

    • Order amount = €80
    • Card balance = €45
    • Ceiling = €50
    • → min(45, 50) = €45
    • → amount_to_capture = 80 – 45 = €35 (to be charged to the credit card)

The amount_to_capture field is added to the API Order call for the credit card. It indicates the amount you actually want to capture on this payment method (which is less than the total order amount).

Parameter Type Required Description
amount_to_capture float Optional Amount to capture on this payment method. If provided and > 0, it automatically triggers the Mix Payment logic on the Gateway side.

If amount_to_capture = amount (total order amount), the parameter is automatically ignored by the Gateway to prevent an error.

Expected Behavior

    • amount_to_capture < amount → The Gateway authorizes and captures only the specified amount. Generates a child transaction for this payment method.

    • amount_to_capture = amount → Ignored. Treated as a standard order (full capture).

    • amount_to_capture = 0 or absent → No Mix Payment. Full capture of the order amount.

    • amount_to_capture > amount → Error returned by the API.

API Order Call, Complete Flow

The Mix Payment flow in API Order mode occurs in 3 to 4 successive calls.

1. Gift card balance consultation

POST /rest/v3/gift-card/consult
{
  "payment_product": "illicado",
  "card_number": "9250004783000002633",
  "card_cvv": "485"
}
// → { "balance": 45.00, "ceiling": 50.00 }
// → amount_to_capture for the credit card = 80 - 45 = €35

2. Credit card Order — Authorization mode with amount_to_capture

POST /rest/v1/order
{
  "orderid": "ORDER_001",
  "operation": "Authorization",
  "payment_product": "visa",
  "cardtoken": "tok_xxxxxxx",
  "amount": 80.00,
  "amount_to_capture": 35.00,
  "currency": "EUR",
  "description": "Order 001"
}
// → Status "AUTHORIZED" (€35 authorized)
// → Retrieve the transaction_reference for maintenance

3. Gift card Order (same orderid)

POST /rest/v1/order
{
  "orderid": "ORDER_001",
  "operation": "Sale",
  "payment_product": "illicado",
  "prepaid_card_number": "9250004783000002633",
  "prepaid_card_security_code": "485",
  "amount": 80.00,
  "currency": "EUR",
  "description": "Order 001"
}
// → Status "CAPTURED" (€45 captured on the gift card)

Important: The exact same orderid is used for all mix-payment calls. Do not modify the amount field between calls.

4. Credit Card Authorization Capture

POST /rest/v1/maintenance
{
  "operation": "capture",
  "transaction_reference": "TXN_CB_XXXXXX",
  "amount": 35.00
}
// → Credit card captured. Mix Payment complete!

In case of failure at step 3 (gift card): Call the maintenance API with operation: "cancel" on the credit card transaction to cancel the authorization. The credit card is never charged.

Payment products eligible for Mix Payment

The following payment methods can be used as a complement in a Mix Payment via API Order:

    • Visa (Credit card) : visa
    • Mastercard (Credit card) : mastercard
    • American Express (Credit card) : american-express
    • Carte Bancaire (CB) (Credit card) : cb
    • PayPal (E-wallet) : paypal
    • Bancontact (Local card) : bancontact
    • Alma (BNPL) : alma
    • Paysafecard (Prepaid) : paysafecard

Compatible gift cards (first payment):

    • Illicado (€50 limit / card) : illicado
    • Gift Cards (compatible with Epay and Oney) : carte-cadeau

Best practices

1️⃣ Always check the balance before the order Call /rest/v3/gift-card/consult before creating the order. This allows you to calculate amount_to_capture and anticipate scenarios with insufficient balance.

2️⃣ Recommended order: Credit card first, gift card second Start with the credit card order in Authorization mode (amount_to_capture). Then charge the gift card. If the gift card fails, cancel the credit card authorization. This avoids any manual refunds.

3️⃣ Keep the same orderid between calls The Gateway identifies sub-transactions via the orderid. Never modify this field between calls for the same mix-payment.

4️⃣ Do not modify the amount field between calls The total order amount must remain constant across all calls. Only amount_to_capture varies.

5️⃣ Handle gift card error cases In the event of a gift card failure (timeout, insufficient balance), immediately call the cancel operation on the credit card authorization to prevent a blocking pre-authorization.

6️⃣ Respect Illicado card limits Illicado cards have a €50 limit per transaction. Use the ceiling field returned by /gift-card/consult to calculate the exact amount.