Gift card Component

Add gift card payments to an existing Components integration.

On this page, you can find additional configuration for adding gift cards to your Components integration.

Before you begin

This page assumes you've already:

Built a Components integration.
Added each gift card variant that you want to test in your Customer Area.

You can test a limited number of gift card variants and simulate gift card payments. When testing, you use a simulator that tries to behave and respond in the same way as an end-to-end connection with a gift card provider. Before you go live, you must onboard with a gift card provider and add the gift card variant to your live Customer Area.

API reference

You don't 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: This is the default with Components v5.0.0 or later.
/payments: If you implemented an advanced use case, or integrated Components before v5.0.0.

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:

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

Step 2: Create an instance of the Component

Select your integration:

Supported in Components v5.18.0 and later.

Required configuration

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.

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
    }
};

https://docs.adyen.com/payment-methods/gift-cards/web-component#gift-card-configuration

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

https://docs.adyen.com/payment-methods/gift-cards/web-component#example-orderstatus-object

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

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:

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

Supported in Components v5.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.

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());
   }
};

https://docs.adyen.com/payment-methods/gift-cards/web-component#gift-card-configuration

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

https://docs.adyen.com/payment-methods/gift-cards/web-component#example-orderstatus-object

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

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:

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

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

https://docs.adyen.com/payment-methods/gift-cards/web-component#gift-card-configuration

If you implemented an advanced use case, or integrated Components before v5.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 request.

(Optional) Accepting partial payments

If you want to accept partial payments, you can configure the gift card Component to create an order or cancel an order. After an order is created, you must make 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 request with the `amount` of the total transaction amount.
`onOrderCancel(order)`	Called when the shopper cancels the gift card transaction. Make an orders/cancel request.

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

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);
    }
};

https://docs.adyen.com/payment-methods/gift-cards/web-component#gift-card-configuration

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

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:

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

(Optional) Making partial payments

When balance of the shopper's gift card is less than the payment amount, no payment is made. Instead, the onOrderRequest event creates an order for the full payment amount. After the order is created, you can start making partial payments:

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
{ "pspReference": "MLSPNCQ8HXSKGK82", "resultCode": "Success", "reference": "YOUR_ORDER_REFERENCE", "remainingAmount": { "value": 250, "currency": "EUR" }, "expiresAt": "2022-01-01T14:21:00", "orderData": "823fh892f8f18f4...148f13f9f3f" }
https://docs.adyen.com/payment-methods/gift-cards/web-component#example-order-object
Use the values from the Component and the /payments endpoint to make partial payments and complete the order outside of the Component.

(Optional) Customize logos

Test and go live

Before making live gift card payments, simulate transactions:

Test your integration using our test card numbers depending on your gift card provider. 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.

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

You can check the status of test payments in your test Customer Area > Transactions > Payments.

When you are ready to go live:

Onboard with a gift card provider.
Contact our Support Team to add the gift card to your live Customer Area.
You can test end-to-end scenarios in your live environment using real gift card details and small amounts.

Are you looking for test card numbers?

Would you like to contact support?

Gift card Component

Before you begin

API reference

Component configuration

Step 1: Create a DOM element

Step 2: Create an instance of the Component

Required configuration

Step 3: Mount the Component

Required configuration

Step 3: Mount the Component

Required configuration

(Optional) Accepting partial payments

Step 3: Mount the Component

(Optional) Making partial payments

(Optional) Customize logos

Test and go live

See also