Accept gift card payments using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.
Before you begin
These instructions explain how to add gift cards to your existing API-only integration. The API-only integration works the same way for all payment methods. If you haven't done this integration yet, refer to our API-only integration guide.
Before starting your integration make sure you:
- Set up your back end implementation.
- Onboard with a gift card provider, then contact our Support Team to add the gift card to your test Customer Area.
Build your payment form for gift cards
You must build a separate integration for each gift card provider.
You can process payments for supported gift cards or manage other transactions like adding to the balance of a gift card.
If you are using the /paymentMethods request to show the available payment methods to your shopper, specify the following in your request:
- countryCode: Country where that gift card is supported, for example, NL.
- amount.currency: Any supported currency, for example, EUR.
- channel: Set to Web.
In the response, you receive the gift cards available to your shopper as elements in the paymentMethods
array, for example:
{
"name": "VVV Giftcard",
"brand": "vvvgiftcard",
"type": "giftcard"
}
Render logos and names of the available brands for the shopper to choose. When the shopper selects a type of gift card, show the payment form.
Check the balance
After the shopper enters the gift card details, check if the balance is enough to make a full payment.
-
Make a
/checkBalance
request including:Field Required Description paymentMethod.type
The brand
from the /paymentMethods response. For example, svs.paymentMethod.number
The gift card number. paymentMethod.securityCode
The card verification code or security code. paymentMethod.expiryMonth
Expiry month of the card. paymentMethod.expiryYear
Expiry year of the card. paymentMethod.holderName
Name of the shopper that the card belongs to. reference
Your reference to uniquely identify the transaction. To provide multiple references for a transaction, separate them with hyphens ("-"). Maximum length: 80 characters. curl https://pal-test.adyen.com/pal/servlet/StoredValue/v46/checkBalance \ -H "x-API-key: YOUR_X-API-KEY" \ -H "content-type: application/json" \ -d '{ "paymentMethod": { "type": "svs", "number": "6006490000000000", "securityCode": "5754" }, "reference": "YOUR_REFERENCE", "merchantAccount": "YOUR_MERCHANT_ACCOUNT" }
The response includes the balance of the gift card.
-
If the balance amount is equal to or greater than the full payment amount, then continue to make a payment.
If the balance is less than the full payment amount, create an order and ask the shopper to make partial payments with the gift card and a different payment method.
Make a payment
From your server, make a /payments request, specifying:
Field | Required | Description |
---|---|---|
paymentMethod.type |
![]() |
giftcard |
paymentMethod.brand |
![]() |
The brand from the /paymentMethods response. For example, vvvgiftcard. |
paymentMethod.number |
![]() |
The gift card number without separators. |
paymentMethod.cvc |
![]() |
The card verification code. |
The maximum payment amount for a gift card payment is EUR 50.
{
"amount":{
"currency":"EUR",
"value":1000
},
"reference":"YOUR_ORDER_NUMBER",
"paymentMethod": {
"type": "giftcard",
"brand": "givex",
"number": "62805011000000000000",
"cvc": "73737"
},
"merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}
{
"pspReference": "851572424333194G",
"resultCode": "Authorised",
"merchantReference": "YOUR_ORDER_NUMBER"
}
curl https://checkout-test.adyen.com/v68/payments \
-H "X-API-key: YOUR_X-API-KEY" \
-H "Content-Type: application/json" \
-d '{
"amount":{
"currency":"EUR",
"value":1000
},
"reference":"YOUR_ORDER_NUMBER",
"paymentMethod": {
"type": "giftcard",
"brand": "givex",
"number": "62805011000000000000",
"cvc": "73737"
},
"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 => "giftcard",
:brand => "givex",
:number => "62805011000000000000",
:cvc => "73737"
},
: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",
"number" => "62805011000000000000",
"cvc" => "73737"
),
"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"
"number": "62805011000000000000",
"cvc": "73737"
},
"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",
cvc: "73737",
number: "62805011000000000000"
},
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.
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, 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:
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.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 You can check the status of test payments in your test Customer Area > Transactions > Payments.You can test other scenarios in your live environment using real gift card details and small amounts. - Contact our Support Team to add the gift card to your live Customer Area.