Gift card Drop-in integration

Add gift cards to your Drop-in integration

Implementation examples
  Java Spring
  .NET
  Node.js

This page explains how to add gift cards to your existing Web Drop-in integration.

Requirements

Requirement	Description
Integration type	Make sure that you have built your Drop-in integration.
Setup steps	Before you begin, in your Customer Area add each gift card variant that you want to test.

Import resources for v6

If you are using Web Drop-in v6, import the resources you need for gift cards:


Copy code
import { AdyenCheckout, Giftcard} from '@adyen/adyen-web'

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: This is the default with Drop-in v5.0.0 or later.
/payments: If you implemented an additional use case.

Drop-in configuration

Select which endpoint you are integrating:

If you implemented an additional use case.

Required configuration

Add configuration to let the shopper make a partial payment with a gift card and pay the rest with another payment method.

Add the following events 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.
`onOrderRequest(resolve, reject, data)`	Called when the gift card balance is less than the transaction amount. Make an /orders request including: - `amount` - `merchantAccount` - `reference`.
`onOrderCancel(order)`	Called when the shopper cancels the gift card transaction. Make an /orders/cancel request.

The following example shows how to configure Drop-in:

Gift card configuration

  
const configuration = {
   // ... Other configuration.
   onOrderCancel: function(Order) {
       // Remove the remaining amount value and currency from the order
       // Make a POST /orders/cancel request
       // Call the update function and pass the order
       checkout.update(order);
   }
   const giftcardConfiguration = {
       onBalanceCheck: function (resolve, reject, data) {
           // Make a POST /paymentMethods/balance request
           resolve(BalanceResponse);
           // The balance is used to trigger the onOrderRequest function.
       }
       onOrderRequest: function (resolve, reject, data) {
           // Make a POST /orders request
           // Create an order for the total transaction amount
           resolve(OrderResponse);
       }
};

Include the giftcardConfiguration object when creating a configuration object:

AdyenCheckout configuration

 const configuration = {
  // ...  other required configuration
  paymentMethodsConfiguration: {
    giftcard: giftcardConfiguration
  }
};

Pass the Drop-in configuration object when creating your instance of AdyenCheckout:


Copy code
const checkout = await AdyenCheckout(configuration);

Show the payment result

Use the resultCode from the /payments response to show the payment result to your shopper.

You will also receive the outcome of the payment asynchronously in a webhook. For gift card payments, you can receive the following resultCode values:

resultCode	Description	Action to take
Authorised	The payment was successful.	Inform the shopper that the payment has been successful. If you are using manual capture, you also need to capture the payment.
Cancelled	The shopper cancelled the payment.	Ask the shopper whether they want to continue with the order, or ask them to select a different payment method.
Error	There was an error when the payment was being processed. For more information, check the `refusalReason` field.	Inform the shopper that there was an error processing their payment.
Refused	The payment was refused. For more information, check the `refusalReason` field.	Ask the shopper to try the payment again using a different payment method.

(Optional) Customize logos

You can specify a custom logo for a gift card brand when creating a configuration object. This example shows a custom icon for Plastix:

AdyenCheckout configuration

 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:

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

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 and add the gift card variant to your live Customer Area.
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.