# 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.

## <mark style="color:red;">1. Overview</mark> <a href="#id-1-overview" id="id-1-overview"></a>

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.

## <mark style="color:red;">2. Setup</mark> <a href="#id-2-setup" id="id-2-setup"></a>

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.

### <mark style="color:red;">2.1. Configuring GIFT\_CARD\_CONFIG</mark>

1. Log in to **Omnitron** using your own credentials.

   <figure><img src="/files/i8QWGPZddVK4HOYZ6sAp" alt=""><figcaption></figcaption></figure>
2. Navigate to **Sales Channels → Sales Channel Settings → Dynamic Settings**.

   <figure><img src="/files/SAObd0WUbnLJRQp0Qe0n" alt=""><figcaption></figcaption></figure>
3. Search for **GIFT\_CARD\_CONFIG** in the search box and click on it in the list.

   <figure><img src="/files/a1jp0vXx9vvrTA0Nqmh5" alt=""><figcaption></figcaption></figure>
4. Update the configuration on the edit screen with the following fields.

   <figure><img src="/files/Mf9qV6UvXBRpc4UMRVi7" alt=""><figcaption></figcaption></figure>

| Field                  | Description                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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:**

```json
{
  "multi_card_enabled": true,
  "max_amount_per_order": 500,
  "balance_cache_ttl": 3600,
  "otp_resend_cooldown": 120,
  "void_task_countdown": 3600
}
```

{% hint style="warning" %}
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.
{% endhint %}

### <mark style="color:red;">2.2. Registering the Gift Card Provider</mark>

{% hint style="warning" %}
The Gift Card Providers screen is not yet available in Omnitron. This section will be updated once the screen is released.
{% endhint %}

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.

1. Navigate to **Gift Card Providers** in Omnitron.
2. Click **Add Provider** and fill in the following fields.

| Field          | Description                                             |
| -------------- | ------------------------------------------------------- |
| `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:**

```json
{
  "resource_url": "https://gift-card-service.example.com",
  "config": {
    "auth": {
      "username": "your-username",
      "password": "your-password"
    }
  }
}
```

## <mark style="color:red;">3. How the Flow Works</mark> <a href="#id-3-how-the-flow-works" id="id-3-how-the-flow-works"></a>

### <mark style="color:red;">3.1. Applying a Gift Card (Non-OTP)</mark>

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.

```
check-balance → card applied to basket
```

### <mark style="color:red;">3.2. Applying a Gift Card (OTP Flow)</mark>

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.

```
check-balance → [send-otp (optional resend)] → verify-otp → card applied to basket
```

{% hint style="info" %}
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.
{% endhint %}

### <mark style="color:red;">3.3. Purchase</mark>

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.

{% hint style="info" %}
Gift card reservations with `amount=0` are skipped and no purchase request is sent.
{% endhint %}

### <mark style="color:red;">3.4. Void</mark>

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.

### <mark style="color:red;">3.5. Refund</mark>

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.

## <mark style="color:red;">4. Implementing the Extension Service</mark> <a href="#id-4-implementing-the-extension-service" id="id-4-implementing-the-extension-service"></a>

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](https://apidocs.akinon.com/flows/extension-gift-card-flows) documentation.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akinon.com/tutorials/commerce/how-to-configure-gift-card.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.