Gift Card Drop-in integration

Add Gift Card to your Drop-in integration

Our Web Drop-in renders the available gift cards in your payment form, and securely collects any sensitive gift card information, so it doesn't touch your server.

Before you begin

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

Before starting your integration make sure you:

Make sure that you have set up your back end implementation, and added Drop-in to your payments form.
Onboard with a gift card provider, then contact our Support Team to add the gift card to your test Customer Area.

Show the available gift cards in your payment form

Drop-in uses the countryCode and the amount.currency from the /paymentMethods request to show the available payment methods to your shopper.

To show available gift cards in your payment form, specify in your /paymentMethods request one of the following combinations:

Specify in your /paymentMethods request:
- countryCode: Country where the type of gift card is supported, for example, NL.
- amount.currency: Any supported currency, for example EUR.

Additional required Drop-in configuration

When you configure Drop-in, you must include the amount parameter.

Events

There are also three events you must implement for gift cards when you configure Drop-in.

Event name	Description
`onBalanceCheck(resolve, reject, data)`	Called when the shopper pays with a gift card.
`onOrderRequest(resolve, reject, data)`	Called when the gift card amount is less than the transaction amount.
`onOrderCancel(order)`	Called when the shopper cancels the gift card transaction.

Make a payment

When the shopper selects the Redeem button, Drop-in calls the onBalanceCheck event.

a. Make a /paymentMethods/balance request to check the balance.

b. Put the response in an object and call resolve passing in the balance object.
https://docs.adyen.com/payment-methods/gift-cards/web-drop-in#onbalancecheck-event
onBalanceCheck event
onBalanceCheck: function (resolve, reject, data) { // call /paymentMethods/balance resolve(balanceResponse); };
If the balance on the gift card is not enough to complete the payment, then skip step c and continue to step 2.

c. Drop-in renders a Pay button. When the shopper selects Pay, Drop-in calls the onSubmit event to make a /payments request to complete the payment.

The payment is complete, and you can continue to present the payment result.
Drop-in calls the onOrderRequest event if the balance is less than the transaction amount.

Make an /orders request. The shopper can make a partial payment with the gift card and can use another payment method to pay the remaining amount or cancel the transaction.

The response contains orderData and pspReference. Put the response in an object and call resolve passing in the order object.
https://docs.adyen.com/payment-methods/gift-cards/web-drop-in#onorderresponse-event
onOrderResponse event
onOrderResponse: function (resolve, reject, data) { // call /paymentMethods/balance resolve(orderResponse); }
Make another /paymentMethods request to get available payment methods.
https://docs.adyen.com/payment-methods/gift-cards/web-drop-in#make-another-payment-methods-request
Make another payment methods request
const orderPaymentMethods = await getPaymentMethods({ order: { orderData: result.order.orderData, pspReference: result.order.pspReference } });
Drop-in updates and renders the list of payment methods for the shopper and shows the remaining amount.
https://docs.adyen.com/payment-methods/gift-cards/web-drop-in#update-amount
Update amount
checkout.update({ paymentMethodsResponse: orderPaymentMethods, order });

After the shopper selects an additional payment method to pay the remaining amount, Drop-in renders a Pay button. When the shopper selects Pay, Drop-in calls the onSubmit event to make a /payments request to complete the payment.

https://docs.adyen.com/payment-methods/gift-cards/web-drop-in#gift-card-payments-web

request
response

{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "{hint:state.data.paymentMethod from onChange}paymentMethod{/hint}": {
    "type": "giftcard",
    "brand": "givex",
    "encryptedCardNumber": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedSecurityCode": "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
  },
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}

{
  "pspReference": "851572424333194G",
  "resultCode": "Authorised",
  "merchantReference": "YOUR_ORDER_NUMBER"
}

curl https://checkout-test.adyen.com/v66/payments \
-H "X-API-key: YOUR_X-API-KEY" \
-H "Content-Type: application/json" \
-d '{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "{hint:state.data.paymentMethod from onChange}paymentMethod{/hint}": {
    "type": "giftcard",
    "brand" "givex",
    "encryptedCardNumber": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedSecurityCode": "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
  },
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}'

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR_X-API-KEY"

response = adyen.checkout.payments({
  :amount => {
    :currency => "EUR",
    :value => 1000
  },
  :reference => "YOUR_ORDER_NUMBER",
  :paymentMethod => {
    :type => "givex",
    :encryptedCardNumber => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    :encryptedSecurityCode => "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
  },
  :merchantAccount => "YOUR_MERCHANT_ACCOUNT"
})

// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = array(
  "amount" => array(
    "currency" => "EUR",
    "value" => 1000
  ),
  "reference" => "YOUR_ORDER_NUMBER",
  "paymentMethod" => array(
    "type" => "giftcard",
    "brand" => "givex",
    "encryptedCardNumber" => "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedSecurityCode" => "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
  ),
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);
$result = $service->payments($params);

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'

result = adyen.checkout.payments({
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "paymentMethod": {
    "type": "giftcard",
    "brand" "givex",
    "encryptedCardNumber": "adyenjs_0_1_18$k7s65M5V0KdPxTErhBIPoMPI8HlC..",
    "encryptedSecurityCode": "adyenjs_0_1_24$XUyMJyHebrra/TpSda9fha978+.."
  },
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
})

// Set your X-API-KEY with the API key from the Customer Area.
const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
const config = new Config();
config.apiKey = "[API_KEY]";
config.merchantAccount = "[YOUR_MERCHANT_ACCOUNT]";
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
checkout.payments({
    amount: { currency: "EUR", value: 1000 },
    paymentMethod: {
        type: "giftcard",
        brand: "givex",
        encryptedSecurityCode: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
        encryptedCardNumber: "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
    },
    reference: "YOUR_ORDER_NUMBER",
    merchantAccount: config.merchantAccount,
}).then(res => res);

The /payments response contains:

pspReference: Our unique identifier for the transaction.
resultCode: Use this to present the payment result to your shopper.
merchantReference: The reference from the /payments request.

Cancel the gift card transaction

After checking the balance of a gift card, the shopper can cancel the transaction if the gift card balance is less than the transaction amount.

When the shopper cancels, call the onOrderCancel event and pass in the order object from the /orders response.

https://docs.adyen.com/payment-methods/gift-cards/web-drop-in#onordercancel-event

onOrderCancel event

function onOrderCancel(order) {
 // call /orders/cancel
}

Present the payment result

Use the resultCode from the /payments response to present the payment result to your shopper.
You will also receive the outcome of the payment asynchronously in a webhook notification. 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.

Test and go live

Before making live gift card payments:

Test your integration using our test card numbers.
You can check the status of test payments in your test Customer Area > Transactions > Payments.
Contact our Support Team to add the gift card to your live Customer Area.

Are you looking for test card numbers?

Would you like to contact support?