> For the complete documentation index, see [llms.txt](https://developers.hyp.co.il/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.hyp.co.il/enterprise/available-payment-options/gift-cards.md).

# Gift Cards

Hyp Enterprise supports a variety of gift card brands used in Israel, issued by Finitione, Multipass, or Swish (Rav-Arnak).

<details>

<summary>Show all brands</summary>

* Issued by Finitione:
  * Discont Young (דיסקונט צעירים)
  * Finitione
  * Gold Ztfon (גולד צפון)
  * istudent (אייסטודנט)
  * Leumi Gudeis (לאומי גודיז)
  * Pais Plus - Mifal haPais Club (פיס פלוס מועדון מפעל הפיס)
  * Pais Plus Rechargeable Gift Card (פיס פלוס תו נטען)
  * Pais Plus Shovar (פיס פלוס שוברים כספיים)
  * Visa Cal (ויזה כ.א.ל.)
  * Yours Club Rechargeable Gift Card (מועדון שלך תו נטען)
  * Yours Club Shovar (cash vouchers – מועדון שלך שוברים כספיים)
  * Yours Club Shovar (for retirees – מועדון שלך לגימלאי)
* Issued by Multipass:
  * BUYME
  * Dor Hadash Ba Shovarim (דור חדש בשוברים)
  * Extra Gift Card (אקסטרה גיפט קארד)
  * HiTechZone (הייטקזון)
  * Kesharim Plus (קשרים פלוס)
  * Mega Leaan (מגה לאן)
  * Multipass (מולטיפס)
  * Power Card
  * POWER GIFT (פאוור גיפט)
  * Raayonit (רעיונית)
  * Rami Levi - Tav Male Digitali (רמי לוי - התו המלא דיגיטלי)
  * Yenot Bitan - Tav Plus (יינות ביתן - תו פלוס)
* Issued by Swish:
  * Ashmoret (אשמורת)
  * Asota (אסותא)
  * Behazdaha (בהצדעה)
  * Beyahad (ביחד)
  * Nofshonit (נופשונית)
  * Shavee (שווה)
  * Shupersal (שופרסל)

</details>

Your customers can split payments between multiple gift cards of different brands: up to five gift cards in a single purchase. If the funds available on gift cards are not enough to cover the transaction amount, the customer can add the missing funds using their regular credit card.

When the customer enters a gift card number, Hyp's payment page validates the number based on the card brand's prefix and numbering conventions.

## Prerequisites

Before you can accept gift cards, you must set up merchant accounts with each gift card provider you want to support. Each provider has different requirements for enabling its cards on your Hyp terminal:

* **Multipass**: You need to provide the following credentials to your Hyp representative:
  * `posCompanyId` (merchant ID)
  * `posId` (terminal ID)
  * `username` (client ID)
  * `Password`
* **Swish (Rav-Arnak)**: You need to provide your merchant terminal ID (`TerminalUniqueIdentifier`) to your Hyp representative.

{% hint style="info" %}
When interacting with your gift card providers, make sure to request test gift cards from them to verify the gift card payment workflow in your test environment.
{% endhint %}

Once you have the necessary credentials, [contact your Hyp representative](mailto:sales@hyp.co.il) to enable gift card support on your terminal. You should also specify which gift card brands from each provider you wish to accept.

## Payment page integration

As soon as gift cards are enabled on your terminal, the **Gift Card** button will appear on your payment pages by default.

However, there are several considerations to keep in mind when accepting gift cards.

### Capture transactions

Gift cards are best used with the [regular payment page flow](https://developers.hyp.co.il/enterprise/payment-page-integration/integrating-hyps-payment-page-and-accepting-payment.md), which performs a capture transaction (J4) and sets the `mpiValidation` parameter to `AutoComm`.

By default, [two-phase commits](https://developers.hyp.co.il/enterprise/two-phase-commits/overview.md) and [tokenization](https://developers.hyp.co.il/enterprise/additional-payment-scenarios/tokenization.md) are unavailable for payments using gift cards. If your payment page request uses any value other than `AutoComm` for `mpiValidation`, the resulting payment page will not display the gift card button, and no error will be returned.

### Two-phase commits

Even though gift cards are best suited for the regular payment page flow, they can still be integrated into [two-phase commits](https://developers.hyp.co.il/enterprise/two-phase-commits/overview.md).

In this case, gift cards will be charged at the time of authorization, while any remaining credit card balance will be charged at the time of capture. If capture is not performed, it is your responsibility to refund all gift cards that were charged at the time of authorization.

To display the gift card button on a two-phase commit payment page, add the following element inside the `doDeal` section of your payment page request:

```xml
<giftCardAllowDifferentMpiValidation>1</giftCardAllowDifferentMpiValidation>
```

### Most gift cards can't be saved

Most gift card brands cannot be tokenized and [saved for future use](https://developers.hyp.co.il/enterprise/changing-the-default-payment-page-appearance/suggesting-to-save-credit-card-data.md).

A notable exception is gift cards issued by Finitione, which behave like regular credit cards and can be saved. However, it is recommended that you do not save gift cards and instead use them only when the customer has explicitly chosen to do so.

### Separate transactions for each card

Each gift card redeemed on the payment page constitutes a separate transaction and receives a unique `tranId` identifier. At the same time, all transactions associated with a single payment involving gift cards share the same `txId` identifier.

### Refunds and cancellations

If you need to perform a [refund or cancellation](https://developers.hyp.co.il/enterprise/additional-payment-scenarios/refunds-and-cancellations.md), it must be done separately for each transaction using its respective `tranId` identifier.

Depending on the gift card provider, you may need to specify a different terminal when making refund and cancellation requests:

* For Multipass gift cards, prefix your terminal number with `mp`:

  ```xml
    ...
    <refundDeal>
        <terminalNumber>mp00000001</terminalNumber>
        <tranId>48014795</tranId>
    </refundDeal>
    ...
  ```
* For Swish (Rav-Arnak) gift cards, prefix your terminal number with `ra`.

For Finitione gift cards, use your regular terminal number without any prefix.

Keep in mind that refund policies, whether they are full, partial, or time-restricted, are determined by the gift card providers. Verify these policies with your gift card provider before going live, as Hyp will pass along any rejections or error codes received from the provider if a refund is restricted.

### Inquiring about transactions

When performing [transaction inquiries](https://developers.hyp.co.il/enterprise/inquiring-transactions/overview.md), use `txId` to inquire about all transactions associated with a payment involving gift cards and `tranId` to inquire about a specific transaction.

### All gift cards used are listed in invoices

[Invoicing](https://developers.hyp.co.il/enterprise/documents-and-invoicing/overview.md) works the same way as it does for regular credit card transactions, with one exception. Since each gift card constitutes a separate transaction, when you [create an invoice](https://developers.hyp.co.il/enterprise/documents-and-invoicing/issuing-invoices.md), you need to retrieve the `tranId` for each transaction and then list them all, separated by spaces, inside the `invoiceAtranId` element:

```xml
<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>addCgInvoice</command>
        <addCgInvoice>
            <invoiceAtranId>119284861 119385811 119290774</invoiceAtranId>
            ...
        </addCgInvoice>
    </request>
</ashrait>
```

In the payment details, the recipient will see the specific gift card or cards used, as well as the credit card, if one was also used.

### Hiding gift cards from the list of payment methods

If you want to hide gift cards from the list of additional payment methods, the [usual method for hiding payment methods](https://developers.hyp.co.il/enterprise/changing-the-default-payment-page-appearance/managing-payment-methods.md#hiding-payment-methods) does not apply. Instead, you need to [hide the HTML element](https://developers.hyp.co.il/enterprise/changing-the-default-payment-page-appearance/hiding-other-elements-from-the-page.md) that contains the gift card button:

```xml
<paymentPageData>
    <ppsJSONConfig>
        {
          "uiCustomData": {
            "customStyle": "#cg-gcs-btn-select{display: none;}"
          }
        }
    </ppsJSONConfig>
</paymentPageData>
```

Alternatively, if gift cards are the only additional payment method on your payment page, you can hide the entire section of additional payment methods like this:

```xml
<paymentPageData>
    <ppsJSONConfig>
        {
          "uiCustomData": {
            "customStyle": "#cg-pm-title,#cg-pm-options{display: none;}"
          }
        }
    </ppsJSONConfig>
</paymentPageData>
```

Keep in mind that while you can hide the gift card button, the internal gift card components themselves (such as the list of brands and the card entry form) cannot be customized. For this reason, we recommend using the default Hyp payment page design to ensure that these elements are displayed correctly and provide a smooth user experience.

### Restricting gift card providers

By default, gift cards from all supported providers are displayed on the payment page. You can choose to allow payments only with card brands from specific gift card providers. For each specified provider, all of its gift cards will be displayed on the payment page.

To do this, define a gift card settings item in the `paymentMethods` array, then set the `allowedProviders` parameter to an array of strings representing the gift card providers you want to allow:

```xml
<paymentPageData>
    <ppsJSONConfig>
        {
          "uiCustomData": {
            "paymentMethods": [
              {
                "type": "gcs",
                "allowedProviders": [
                  "multipass",
                  "swish"
                ]
              }
            ]
          }
        }
    </ppsJSONConfig>
</paymentPageData>
```

The three supported string values in the `allowedProviders` array are `multipass`, `swish`, and `finitione`.

### Limiting the total amount

You can cap the total amount that customers can pay using gift cards in a single transaction. This is useful if you want to ensure that a portion of the payment is made using another method, or if you have specific business rules regarding gift card usage limits.

To set this limit, use the `maxAmount` parameter within the gift card settings object in the `paymentMethods` array. The value should be an integer representing the amount in agorot (for example, `1000` for 10 ILS) and cannot exceed the total transaction amount.

```xml
<paymentPageData>
    <ppsJSONConfig>
        {
          "uiCustomData": {
            "paymentMethods": [
              {
                "type": "gcs",
                "maxAmount": 12000
              }
            ]
          }
        }
    </ppsJSONConfig>
</paymentPageData>
```

When the cumulative value of the gift cards entered by the customer reaches this limit, the payment page will automatically hide the option to add more cards.

### Limiting the number of gift cards in a transaction

If you want to restrict how many individual gift cards a customer can use for a single purchase, you can set a specific limit.

To define a custom limit, set the `maxGiftCardCount` parameter to a value between `1` and `4`. If you don't specify this parameter, the default limit of five cards applies.

```xml
<paymentPageData>
    <ppsJSONConfig>
        {
          "uiCustomData": {
            "paymentMethods": [
              {
                "type": "gcs",
                "maxGiftCardCount": 2
              }
            ]
          }
        }
    </ppsJSONConfig>
</paymentPageData>
```

Once the customer reaches the specified number of cards, the interface will stop offering the option to add another gift card.

### Gift card only mode

For specific promotions or specialized storefronts, you might want to restrict the payment page to only accept gift cards. In this mode, credit cards and other payment methods are disabled.

To enable this restriction, set the `giftcardOnlyMode` parameter to `true`. This tells the payment page to display only the gift card interface and hide all other payment options.

```xml
<paymentPageData>
    <ppsJSONConfig>
        {
          "uiCustomData": {
            "paymentMethods": [
              {
                "type": "gcs",
                "giftcardOnlyMode": true
              }
            ]
          }
        }
    </ppsJSONConfig>
</paymentPageData>
```

When using this mode, the total transaction amount must be fully covered by gift cards, so you cannot use the `maxAmount` parameter. However, you can still combine this with `maxGiftCardCount` to limit the number of cards allowed, or use `allowedProviders` to restrict which brands the customer can use.

## Payment experience

Here's what the gift card payment button looks like on the payment page:

![A button for gift cards on a payment page](https://3255314327-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQDmIAW4sQ20lCItJGzcS%2Fuploads%2Fgit-blob-49daefd2b3764971c87aa96e866e2003c11d4ccb%2Fgift-cards-button.png?alt=media)

When the customer clicks the button, Hyp Enterprise displays a list of supported gift card brands:

![The list of supported gift cards](https://3255314327-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQDmIAW4sQ20lCItJGzcS%2Fuploads%2Fgit-blob-bf4f690482bfcf37c197d23ae21bb134a773d7b1%2Fgift-cards-list.png?alt=media)

Clicking a brand opens a form to enter the gift card number and any additional required fields:

![A form to enter gift card details](https://3255314327-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQDmIAW4sQ20lCItJGzcS%2Fuploads%2Fgit-blob-3907686aee0aac36d393c445daaedba52ca2ec38%2Fgift-cards-entry.png?alt=media)

After validating the entered details, Hyp Enterprise shows a list of gift cards used so far. The customer can adjust the amount applied to each card or add more cards (up to five in total):

![The list of gift cards used](https://3255314327-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQDmIAW4sQ20lCItJGzcS%2Fuploads%2Fgit-blob-51d0f99e5af0df533d8289597769ad3ff53dfbc0%2Fgift-cards-used.png?alt=media)

After clicking **Continue**, if the total amount due is not fully covered by the selected gift cards, the customer can pay the remaining balance with a regular credit card.

Once the customer has completed all fields and clicked **Pay**, the payment is processed, and either the success page or the error page is displayed.

This flow works the same whether you use a full-page redirect or display the payment page in an iframe.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.hyp.co.il/enterprise/available-payment-options/gift-cards.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
