How to Configure Gift Card Payment
This document provides a step-by-step guide on how to configure and integrate the Gift Card Payment Flow in Commerce. The Gift Card Payment Flow connects Commerce to an external gift card provider through a standardised extension interface, allowing customers to redeem gift cards during checkout — with optional OTP verification support.
This integration is particularly useful for providers that manage their own card balance logic, require OTP-based identity verification, or need idempotent refund handling.
1. Overview
When a customer applies a gift card during checkout, Commerce communicates with the configured provider through a standardised interface. The provider handles card balance queries, optional OTP verification, and payment transactions. Commerce orchestrates the flow and applies the result to the basket.
Key characteristics of this flow:
Provider abstraction: Each provider implements its own gift card logic; Commerce communicates through a fixed interface without provider-specific changes.
OTP support: Providers that require OTP verification are fully supported. The user must verify their identity before the card can be charged.
Multi-card support: Multiple gift cards can be applied to a single order when enabled.
Idempotent refunds: Refund operations are safe to retry; the provider is expected to handle duplicate requests gracefully.
Automatic void on failure: If an order cannot be created after a successful gift card charge, Commerce schedules an automatic void to clean up the orphaned transaction.
2. Setup
Configuring the gift card feature requires two steps: setting the behavioural parameters via the GIFT_CARD_CONFIG dynamic setting, and registering the gift card provider through the Omnitron provider management screen.
2.1. Configuring GIFT_CARD_CONFIG
Log in to Omnitron using your own credentials.
Navigate to Sales Channels → Sales Channel Settings → Dynamic Settings.
Search for GIFT_CARD_CONFIG in the search box and click on it in the list.
Update the configuration on the edit screen with the following fields.
multi_card_enabled
Set to true to allow more than one gift card per order. When false, a second card is rejected if one is already applied.
max_amount_per_order
Maximum total gift card amount per order (in the order's currency). 0 means unlimited.
balance_cache_ttl
Duration in seconds that a queried card balance is kept in cache. Should be long enough to cover the full application flow including OTP verification.
otp_resend_cooldown
Minimum seconds a user must wait before requesting a new OTP.
void_task_countdown
Delay in seconds before Commerce automatically voids an orphaned gift card charge when order creation fails.
Example configuration:
Set balance_cache_ttl high enough to cover the entire gift card application flow — from card entry through OTP verification to amount confirmation. A value lower than the expected user interaction time will cause the reservation to expire and the user will need to re-add the card.
2.2. Registering the Gift Card Provider
The Gift Card Providers screen is not yet available in Omnitron. This section will be updated once the screen is released.
The gift card provider connection details (service URL and authentication credentials) are managed through the Gift Card Providers screen in Omnitron. This is separate from Dynamic Settings.
Navigate to Gift Card Providers in Omnitron.
Click Add Provider and fill in the following fields.
resource_url
Base URL of the gift card provider's extension service.
username
Username for HTTP Basic Authentication.
password
Password for HTTP Basic Authentication.
Example provider configuration:
3. How the Flow Works
3.1. Applying a Gift Card (Non-OTP)
When a customer enters a gift card number, Commerce calls the provider's check-balance endpoint. If the provider does not require OTP, the response includes the card balance and a purchaseToken directly. The card is reserved in the basket and the customer can proceed to payment.
3.2. Applying a Gift Card (OTP Flow)
If the provider requires OTP verification, check-balance returns otpRequired: true and an otpRef. Commerce prompts the user to enter the OTP sent to their masked phone number. The user may request the OTP to be resent; Commerce enforces the otp_resend_cooldown between consecutive resend requests. Once the user submits the correct OTP, verify-otp returns the purchaseToken and the card is reserved.
The card balance and currency may be returned in either check-balance or verify-otp depending on the provider. If the provider returns currency, it must match the order currency — a mismatch causes the transaction to be rejected.
3.3. Purchase
When the order is placed, Commerce charges each applied gift card by calling the purchase endpoint with the corresponding purchaseToken. If multiple gift cards are applied, a separate purchase request is sent per card. If any charge fails, all previously successful charges for that order are automatically voided.
Gift card reservations with amount=0 are skipped and no purchase request is sent.
3.4. Void
The void endpoint is used to reverse a purchase transaction. If the order has not yet been created at the time of the void, orderNumber is sent as null.
Commerce does not halt the flow on void errors — the void is best-effort. However, the provider is still expected to return a successful response.
If order creation fails after a successful gift card charge (e.g. due to a server error or timeout), Commerce schedules a background void task after void_task_countdown seconds to clean up the orphaned transaction automatically.
3.5. Refund
Partial and full refunds are supported. Commerce calls the refund endpoint with the original transactionId, the refund amount, and the order number. The provider is expected to handle duplicate refund requests idempotently.
4. Implementing the Extension Service
To integrate a gift card provider, you need to implement an HTTP service that Commerce will call during checkout, cancellation, and refund flows. Once the service is deployed, register its URL and credentials through the Gift Card Providers screen in Omnitron. For the full API specification — including endpoint definitions, request/response field descriptions, OTP flow details, and error handling — refer to the Extension Gift Card Gateway Flows documentation.
Last updated
Was this helpful?