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.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
andpspReference
. Put the response in an object and callresolve
passing in the order object. -
Make another /paymentMethods request to get available payment methods.
Drop-in updates and renders the list of payment methods for the shopper and shows the remaining amount.
-
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.{ "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
: Thereference
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.
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.