---
title: "Gift card Component"
description: "Add gift card payments to an existing Components integration."
url: "https://docs.adyen.com/payment-methods/gift-cards/web-component"
source_url: "https://docs.adyen.com/payment-methods/gift-cards/web-component.md"
canonical: "https://docs.adyen.com/payment-methods/gift-cards/web-component"
last_modified: "2026-06-01T15:33:15+02:00"
language: "en"
---

# Gift card Component

Add gift card payments to an existing Components integration.

[View source](/payment-methods/gift-cards/web-component.md)

![](/user/pages/reuse/development-resources/additional-info-resources/postman-logo-vertical-orange-2021.svg?decoding=auto\&fetchpriority=auto)  [Postman collection](https://www.postman.com/adyendev/workspace/adyen-apis/collection/25716737-46ad970e-dc9e-4246-bac2-769c6083e7b5)

**Implementation examples**\
![](/user/pages/reuse/development-resources/additional-info-resources/java-original.svg?decoding=auto\&fetchpriority=auto)  [Java Spring](https://github.com/adyen-examples/adyen-java-spring-online-payments/tree/main/giftcard-example)\
![](/user/pages/reuse/development-resources/additional-info-resources/dot-net-original.svg?decoding=auto\&fetchpriority=auto)  [.NET](https://github.com/adyen-examples/adyen-dotnet-online-payments/tree/main/giftcard-example)\
![](/user/pages/reuse/development-resources/additional-info-resources/nodejs-original.svg?decoding=auto\&fetchpriority=auto)  [Node.js](https://github.com/adyen-examples/adyen-node-online-payments/tree/main/giftcard-example)

This page explains how to add gift cards to your existing Web Components integration.

## Requirements

| Requirement          | Description                                                                                                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type** | Make sure that you have built your [Components integration](/online-payments/build-your-integration/sessions-flow?platform=Web\&integration=Components%2F%3Ftarget%3D_blank). |
| **Setup steps**      | Before you begin, in [your Customer Area](/payment-methods/add-payment-methods) add each gift card variant that you want to test.                                             |

## API reference

You do not need to send additional fields for gift cards. To see optional fields that you can send for all payment methods, choose the endpoint you integrated:

* [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions): This is the default with [Components v5.0.0](/online-payments/build-your-integration/sessions-flow?platform=Web\&integration=Components) or later.
* [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments): If you implemented an [additional use case](/online-payments/build-your-integration).

## Component configuration

### Step 1: Create a DOM element

Create a DOM element on your checkout page, placing it where you want the payment method form to be rendered:

```html
 <div id="giftcard-container"></div>
```

### Step 2: Create an instance of the Component

Select your integration:

### Tab: `/sessions`

Supported in [Components v5.18.0](/online-payments/release-notes#releaseNote=2022-07-12-web-componentsdrop-in-5.18.0) and later.

### Required configuration

Add configuration to let the shopper pay part of the amount with a gift card and the rest with another payment method.

Add the following event to your gift cards configuration object:

| Event name                    | Description                                                                                                                                                                                                                                                                                        |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onOrderCreated(orderStatus)` | Called when the gift card balance is less than the transaction amount. Returns an `orderStatus` object that includes the remaining amount to be paid. Use your existing instance of `AdyenCheckout` to create components for payment methods that the shopper can use to pay the remaining amount. |

The following example shows how to configure the gift card Component to allow the shopper to pay the remaining amount using iDEAL or a card.

**Gift card configuration**

```js
const giftcardConfiguration = {
    onOrderCreated: function (orderStatus) {
        // Get the remaining amount to be paid from orderStatus.
        console.log(orderStatus.remainingAmount);
        // Use your existing instance of AdyenCheckout to create payment methods components
        // The shopper can use these payment methods to pay the remaining amount
        const idealComponent = checkout.create('ideal').mount('#ideal-container');
        const cardComponent = checkout.create('card').mount('#card-container');
        // Add other payment method components that you want to show to the shopper
    }
};
```

**Example orderStatus object**

```json
{
    "amount": {
        "currency": "EUR",
        "value": 25900
    },
    "expiresAt": "2022-07-12T10:17:19.00Z",
    "orderData": "Ab02b4c0!B...",
    "pspReference": "G34Q5SC8N5PFWR82",
    "reference": "ABC123",
    "remainingAmount": {
        "currency": "EUR",
        "value": 19900
    }
}
```

#### v6.0.0 or later

Create an instance of the Component, passing:

* Your instance of `AdyenCheckout`.
* Optionally, the payment method-specific configuration.

```js
const giftcardComponent = new Giftcard(checkout, giftcardConfiguration);
```

**

#### v5.x.x or earlier

Use the `create` method of your `AdyenCheckout` instance, in this case `checkout`, to create the Component. Pass the configuration object if you created one:

```js
const giftcardComponent = checkout.create('giftcard', giftcardConfiguration);
```

### Step 3: Mount the Component

Mount the Component only after checking that gift cards is available to the shopper:

```js
giftcardComponent
   .then(() => {
       giftcardComponent.mount("#giftcard-container");
   })
   .catch(e => {
       //gift cards is not available
   });
```

### Tab: `/sessions` with your own **Pay** button

Supported in [Components v5.21.0](/online-payments/release-notes#releaseNote=2022-08-08-web-componentsdrop-in-5.21.0) and later.

### Required configuration

When using your own **Pay** button for gift cards, you must call the `balanceCheck()` method from your button implementation. If the balance of the gift card is enough to pay the full payment amount, call the `submit()` method to make the payment.

| Method name      | Description                                                                    |
| ---------------- | ------------------------------------------------------------------------------ |
| `balanceCheck()` | Checks whether the gift card balance is enough to pay the full payment amount. |
| `submit()`       | Makes a payment after the `onRequiringConfirmation` event has been called.     |

To know if the gift card balance is enough to pay the full payment amount, add the following events to your gift cards configuration object:

| Event name                    | Description                                                                                                                                                                                                                                                                                        |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onOrderCreated(orderStatus)` | Called when the gift card balance is less than the transaction amount. Returns an `orderStatus` object that includes the remaining amount to be paid. Use your existing instance of `AdyenCheckout` to create components for payment methods that the shopper can use to pay the remaining amount. |
| `onRequiringConfirmation`     | Called when the gift card balance is enough to pay the full payment amount. The shopper must then confirm that they want to make the payment with the gift card. Use the `submit()` method to make the payment.                                                                                    |

The following example shows how to configure the gift card Component to allow the shopper to pay the remaining amount using iDEAL or a card.

**Gift card configuration**

```js
const giftcardConfiguration = {
    onOrderCreated: function (orderStatus) {
        // Get the remaining amount to be paid from orderStatus.
        console.log(orderStatus.remainingAmount);
        // Use your existing instance of AdyenCheckout to create payment methods components
        // The shopper can use these payment methods to pay the remaining amount
        const idealComponent = checkout.create('ideal').mount('#ideal-container');
        const cardComponent = checkout.create('card').mount('#card-container');
        // Add other payment method components that you want to show to the shopper
    }
    onRequiringConfirmation: function() {
       document.querySelector('#button-to-confirm')
           .addEventListener('click', () => window.giftcard.submit());
   }
};
```

**Example orderStatus object**

```json
{
    "amount": {
        "currency": "EUR",
        "value": 25900
    },
    "expiresAt": "2022-07-12T10:17:19.00Z",
    "orderData": "Ab02b4c0!B...",
    "pspReference": "G34Q5SC8N5PFWR82",
    "reference": "ABC123",
    "remainingAmount": {
        "currency": "EUR",
        "value": 19900
    }
}
```

#### v6.0.0 or later

Create an instance of the Component, passing:

* Your instance of `AdyenCheckout`.
* Optionally, the payment method-specific configuration.

```js
const giftcardComponent = new Giftcard(checkout, giftcardConfiguration);
```

**

#### v5.x.x or earlier

Use the `create` method of your `AdyenCheckout` instance, in this case `checkout`, to create the Component. Pass the configuration object if you created one:

```js
const giftcardComponent = checkout.create('giftcard', giftcardConfiguration);
```

### Step 3: Mount the Component

Mount the Component only after checking that gift cards are available to the shopper:

**Gift card configuration**

```js
giftcardComponent
    .isAvailable()
    .then(() => {
        giftcardComponent.mount("#giftcard-container");
    })
    .catch(e => {
        //gift cards is not available
    });


document.querySelector('#button-to-verify').addEventListener('click',  () => window.giftcard.balanceCheck());
```

### Tab: `/payments`

If you implemented the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request, or integrated Components before [v5.18.0](/online-payments/release-notes#releaseNote=2022-07-12-web-componentsdrop-in-5.18.0).

### Required configuration

Add the following event to your gift cards configuration object:

| Event name                              | Description                                                                                                                                                             |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onBalanceCheck(resolve, reject, data)` | Called when the shopper pays with gift card. Make a [/paymentMethods/balance](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods/balance) request. |

### Accepting partial payments

Add configuration to let the shopper make a [partial payment](/online-payments/partial-payments) with a gift card and pay the rest with another payment method. Configure the gift card Component to [create an order](/online-payments/partial-payments#create-an-order) or [cancel an order](/online-payments/partial-payments#cancel-order). After an order is created, you must [make partial payments](#making-partial-payments) outside of the Component.

To configure the Component to create and cancel orders, add the following events to your gift cards configuration object:

| Event name                                  | Description                                                                                                                                                                                                          |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()`onOrderRequest(resolve, reject, data)` | Called when the gift card balance is less than the transaction amount. Make an [/orders](https://docs.adyen.com/api-explorer/Checkout/latest/post/orders) request with the `amount` of the total transaction amount. |
| `onOrderCancel(order)`                      | Called when the shopper cancels the gift card transaction. Make an [orders/cancel](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/orders/cancel) request.                                         |

The following example shows how to configure the gift card Component:

**Gift card configuration**

```js
const giftcardConfiguration = {
    onBalanceCheck: function (resolve, reject, data) {
        // Make a POST /paymentMethods/balance request
        resolve(BalanceResponse);
    }
    onOrderRequest: function (resolve, reject, data) {
        // Make a POST /orders request
        // Create an order for the total transaction amount
        resolve(OrderResponse);
    }
    onOrderCancel: function(Order) {
        // Make a POST /orders/cancel request
        // Call the update function and pass the payment methods response to update the instance of checkout
        checkout.update(paymentMethodsResponse, amount);
    }
};
```

#### v6.0.0 or later

Create an instance of the Component, passing:

* Your instance of `AdyenCheckout`.
* Optionally, the payment method-specific configuration.

```js
const giftcardComponent = new Giftcard(checkout, giftcardConfiguration);
```

**

#### v5.x.x or earlier

Use the `create` method of your `AdyenCheckout` instance, in this case `checkout`, to create the Component. Pass the configuration object if you created one:

```js
const giftcardComponent = checkout.create('giftcard', giftcardConfiguration);
```

### Step 3: Mount the Component

Mount the Component only after checking that gift cards is available to the shopper:

```js
giftcardComponent
   .isAvailable()
   .then(() => {
       giftcardComponent.mount("#giftcard-container");
   })
   .catch(e => {
       //gift cards is not available
   });
```

### Making partial payments

When balance of the shopper's gift card is less than the payment amount, no payment is made. Instead, the [`onOrderRequest` ](#on-order-request)event creates an order for the full payment amount. After the order is created, you can start making partial payments:

1. The response to the `onOrderRequest` event includes the following fields that you need for payment:

   | Field             | Description                                        |
   | ----------------- | -------------------------------------------------- |
   | `pspReference`    | The unique reference for the order.                |
   | `orderData`       | The details needed to make payments for the order. |
   | `remainingAmount` | The full payment amount.                           |

   **Example order object**

   ```json
   {
     "pspReference": "MLSPNCQ8HXSKGK82",
     "resultCode": "Success",
     "reference": "YOUR_ORDER_REFERENCE",
     "remainingAmount": {
       "value": 250,
       "currency": "EUR"
        },
     "expiresAt": "2022-01-01T14:21:00",
     "orderData": "823fh892f8f18f4...148f13f9f3f"
   }
   ```

2. Use the values from the Component and the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) endpoint to [make partial payments](/online-payments/partial-payments#make-a-payment) and complete the order outside of the Component.

### (Optional) Customize logos

You can specify a custom logo for a gift card brand when [creating a configuration object](/online-payments/build-your-integration/sessions-flow?platform=Web\&integration=Drop-in#configure). This example shows a custom icon for Plastix:

**AdyenCheckout configuration**

```js
const configuration = {
  // ...  other configuration
  paymentMethodsConfiguration: {
    giftcard: {
                brandsConfiguration: {
                    plastix: {
                        icon: 'https://mymerchant.com/icons/customIcon.svg'
                    }
                }
    }
  }
}
```

## Test and go live

Before making live gift card payments, simulate transactions:

1. Test your integration using our [test card numbers](/development-resources/test-cards-and-credentials/alternative-payment-method-credentials#gift-cards) depending on your gift card provider. When testing, you use a simulator that tries to behave and respond in the same way as an end-to-end connection.

   To simulate a scenario, send one of the following amounts in the test payment request:

   | Amount (last three digits) | `resultCode` | `refusalReason`    |
   | -------------------------- | ------------ | ------------------ |
   | 100                        | Authorised   |                    |
   | 123                        | Refused      | Refused            |
   | 124                        | Refused      | Not enough balance |
   | 125                        | Refused      | Blocked Card       |
   | 126                        | Refused      | Expired Card       |
   | 130                        | Error        | Acquirer Error     |
   | 134                        | Refused      | Invalid Pin        |
   | 135                        | Refused      | Pin tries exceeded |

   For example, send a payment amount with **100** as the last three digits, such as 1.00 or 11.00. This will result in an **Authorised** transaction.

2. Check the status of test payments in your [test Customer Area](https://ca-test.adyen.com/) > **Transactions** > **Payments**.

When you are ready to go live:

1. Onboard with a gift card provider and add the [gift card variant](/payment-methods/gift-cards#supported-gift-cards) to your [live Customer Area](https://ca-live.adyen.com/).

2. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to add the gift card to your [live Customer Area](https://ca-live.adyen.com/).

   You can test end-to-end scenarios in your live environment using real gift card details and small amounts.

## See also

* [Web Components integration guide](/online-payments/components-web)
* [Webhooks](/development-resources/webhooks)
* [API Explorer](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/overview)
