Gift cards for API only

Add gift card payments to an existing API-only integration.

To see example code for implementing gift cards, refer to our GitHub

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.
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.

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 /paymentMethods/balance request including:

Field	Required	Description
`paymentMethod.type`		The `brand` from the /paymentMethods response. For example, givex.
`paymentMethod.number`		The gift card number.
`paymentMethod.cvc`		The card verification code or security code.
`merchantAccount`		Your merchant account.

curl https://checkout-test.adyen.com/v69/paymentMethods/balance \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
     "paymentMethod": {
       "type": "givex",
       "number": "6364530000000000",
       "cvc": "737"
     },
     "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
   }'

https://docs.adyen.com/payment-methods/gift-cards/api-only#-paymentmethods-balance-request

The response includes the balance of the gift card.

{
 "pspReference": "ZQXDPCQ8HXSKGK82",
 "resultCode": "Success",
 "balance": {
   "currency": "EUR",
   "value": 5000
 }
}

https://docs.adyen.com/payment-methods/gift-cards/api-only#-paymentmethods-balance-response

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, make an /orders request. This lets you create partial payments: a payment with the gift card, and a payment for the remaining amount using 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 or genericgiftcard.
`paymentMethod.number`		The gift card number without separators.
`paymentMethod.cvc`		The card verification code.

For some gift cards, there are regulatory limits on transaction amounts. Check with your gift card provider to learn if these limits affect you.

{
  "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);

https://docs.adyen.com/payment-methods/gift-cards/api-only#gift-card-payments-api

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.

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.

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.