Search

Are you looking for test card numbers?

Would you like to contact support?

Default icon

Pay by Link through the API

Learn how to create payment links through the API.

Release notes

Creating payment links through the API allows you to accept most payment methods, including buy now, pay later payment methods such as Klarna and Afterpay.

Using payment links to accept payments works as follows:

  1. Create a payment link.
  2. Send the payment link to your shopper.
  3. Get updates about the payment.

On this page, you'll also learn how to implement additional use cases such as:

Before you begin

If you haven't done so already, set up your Adyen test account. When you have your test account:

Generate your API key

  1. Log in to your Customer Area.
  2. Go to Developers > API credentials, and select the credential ws@Company.[YourCompanyAccount], or any other credential that you will use to make API calls.
  3. If you don't have an API key yet, generate an API key:
    1. Under Authentication, select Generate New API Key .
    2. Copy and securely store the API key in your system — you won't be able to restore it later. If your API key is lost or compromised, you need to generate a new one.
  4. In the Roles and Associated Accounts pane, check that the credential has the following role:
    • Checkout webservice role

If your API credential does not have this role, reach out to your Admin user.

Set up webhooks

Notifications allow you to get updates about the payment after you've sent the payment link to your shopper.

If you haven't done so already, set up webhook notifications, and make sure that your server can process and accept notifications.

Add payment methods to your account

If you haven't done so already, add payment methods to your merchant account. To see which payment methods are supported for Pay by Link, refer to Supported payment methods.

  1. Log in to your Customer Area.
  2. Switch to your merchant account.
  3. Go to Account > Payment methods.
  4. Select Add payment methods.
  5. Start entering the name of the payment method, then select it from the drop-down list.
  6. Select Submit.

Step 1: Create a payment link

Make a POST /paymentLinks request specifying the following:

You can also include other parameters, for example shopperLocale to specify the language of the payment page, expiresAt to change the expiry date of the payment link, or description to add a description for the product. If these are not provided, the payment page will be rendered in the language of the shopper's browser locale, without a description, and with a 24-hour expiry.

In this example, we'll show you how you can create a payment link for a shopper in the Netherlands for a purchase amount of 42 EUR:

You receive a response containing the following:

  • id: The payment link ID.
  • url: The payment link that you should send to your shopper.
  • expiresAt: Date and time when the payment link expires.
Response
{
  "amount": {
    "currency": "EUR",
    "value": 4200
  },
  "countryCode": "NL",
  "description": "Blue Bag - ModelM671",
  "expiresAt": "2020-07-25T11:32:20Z",
  "id": "PL50C5F751CED39G71",
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "reference": "YOUR_PAYMENT_REFERENCE",
  "shopperLocale": "nl-NL",
  "shopperReference": "UNIQUE_SHOPPER_ID_6728",
  "url": "https://test.adyen.link/PL45D0F79183A4CCA2"
}

Step 2: Send the payment link to your shopper

Use the url from the /paymentLinks response to redirect your shopper to the payment link.

Make sure that you don't embed the payment link in an iframe, as this might cause issues with payment methods that require a redirect.

Send the url to your shopper. When the shopper selects the link, they are redirected to an Adyen-hosted payment page. The shopper is presented with the payment methods available for the amount and countryCode specified in the request.

Step 3: Get updates about the payment

First, wait for the AUTHORISATION notification to receive the result of the payment, as well as the payment link ID. When you have the payment link ID, you can make a GET /paymentLinks/{linkId} request to get details about the payment link.

You can also view payment links in your Customer Area.

AUTHORISATION notification

The AUTHORISATION notification contains:

  • additionalData.paymentLinkId: Use this to match the payment to the payment link. For our example, this matches the payment link ID PL50C5F751CED39G71.
  • pspReference: Unique identifier for the payment.
  • success: The result of the transaction.

    success Description Action to take
    true The shopper successfully completed the payment. Inform the shopper that the payment has been successful, and proceed with the order.
    If you have enabled manual capture, you also need to capture the payment.
    false The shopper attempted to pay but the transaction failed. The payment page informs the shopper that the payment was unsuccessful, and prompts them to try again. If the shopper still doesn't make a successful payment, you may want to reach out to them to follow up.
AUTHORISATION notification
{
"notificationItems":[
 {
    "NotificationRequestItem":{
       "additionalData":{
          ...
          "paymentLinkId":"PL50C5F751CED39G71"
       },
       "amount":{
          "currency":"EUR",
          "value":4200
       },
       ...
       "eventCode":"AUTHORISATION",
       "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
       "merchantReference":"YOUR_ORDER_NUMBER",
       "pspReference":"852593065346377D",
       "success":"true"
    }
 }
]
}

Get details about a payment link

To get the details of a specific payment link, send a GET /paymentLinks/{linkId} request. Let's use our example from the previous section for a payment link with ID PL50C5F751CED39G71.

The response returns the payment link details, including the amount and the status. If the link is not expired and has not been paid, the status is active. Else, the status is completed or expired.

Response
{
    "amount": {
        "currency": "EUR",
        "value": 4200
    },
    "countryCode": "NL",
    "expiresAt": "2020-06-23T12:25:28Z",
    "id": "PL50C5F751CED39G71",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "reference": "YOUR_PAYMENT_REFERENCE",
    "shopperLocale": "nl-NL",
    "status": "active",
    "url": "https://test.adyen.link/PL50C5F751CED39G71"
}

In some cases, you may want to create a reusable link. For example, if you want to accept donations for a fixed amount from multiple shoppers, or sell event tickets. To do this, set reusable to true in your POST /paymentLinks request.

The example below shows how you would create a reusable payment link to accept donations for the amount of 8.50 USD from shoppers in the United States:

Tokenize your shopper's payment details

You can use the Pay by Link API to create a payment link that will tokenize and store your shopper's card details. The token can be used to implement:

Tokenize for future one-off payments

You should always ask for your customer's consent before tokenizing their card for future payments.

You can use the Pay by Link API to create a payment link that will tokenize and store your shopper's card details for future one-off payments. The next time the same shopper makes a purchase, their stored card details will be presented on the payment page.

  1. Make sure that in your POST /paymentLinks request, you send:

    Here's an example of how you can create a payment link for a shopper with shopperReference ShopperID-A16728.

    The shopper's card details will be tokenized after they make a successful payment.

  1. When the shopper returns for their next purchase, send the same shopperReference from the first request, and set recurringProcessingModel to CardOnFile in your POST /paymentLinks request.

    Here's an example of how you can create a payment link for the same shopper with shopperReference ShopperID-A16728.

Tokenize for subscriptions

You should always ask for your customer's consent before tokenizing their card for future payments.

You can use the Pay by Link API to create a payment link that will tokenize and store your shopper's card details for recurring payments.

  1. Make sure that in your POST /paymentLinks request, you send:

    Send the payment amount, or if you only want to tokenize the shopper's payment details without charging them, set the amount.value to 0. This is called a zero-value authorisation. Instead of a Pay button, your shoppers will see a Confirm preauthorization button on the payment page.

    Here is an example of how you can create a payment link to tokenize and store payment details for a subscription, for a shopper with shopperReference Shopper-B7183.

  2. After the shopper completes the payment or the preauthorization, make a POST /paymentMethods request to get the shopper's tokenized payment details.

  3. Send the token when you make subsequent subscription payments with a POST /payments request.

Provide additional information

Some payment methods, such as buy now, pay later payment methods, require additional information about the purchased product (lineItems) or the shopper (for example, shopperEmail). If you want to create a payment link that can support these payment methods, you need to make sure that you provide this information.

Payment method Required objects
3x 4x Oney (FR, ES) lineItems

Note: Other shopper information such as shopper name and email are collected on the payment page.
Afterpay (AU, NZ) lineItems, shopperEmail, shopperName, deliveryAddress, billingAddress
Klarna (AT, DK, FI,
DE, NO, SE, CH,
NL, GB, US)
lineItems , shopperEmail, shopperName, billingAddress
PayBright (CA) lineItems, shopperEmail, shopperName, deliveryAddress, billingAddress
Zip (AU) lineItems, shopperEmail, shopperName, deliveryAddress, billingAddress

Below, you can learn how to provide:

Provide product information

If a payment method requires lineItems, you will need to collect this information, and include it in your POST /paymentLinks request.

For example, here is how you would create a payment link that can support 3x 4x Oney (FR, ES) .

Provide shopper information

For shopper information such as name, email, or address, you can either:

This example shows how you would create a payment link that can support Klarna, and ask the shopper to fill in the required information themselves:

This example shows how you would create a payment link that can support Klarna if you have already collected the shopper's email, name, and address:

Force the expiry of a payment link

In some scenarios, you may want to force the expiry of a payment link. For example, if a shopper updates their order after you've sent them a payment link, you may want to create a new payment link with the updated amount. To avoid confusion with two payment links, set the status of the previous payment link to expired. Changing the status to expired also changes the payment link's expiry date to the current date and time.

To force the expiry, make a PATCH /paymentLinks/{id} request and update the status.

The response returns the payment link details with the updated status and expiresAt parameters.

Response
{
    "amount": {
        "currency": "EUR",
        "value": 4200
    },
    "countryCode": "NL",
    "expiresAt": "2020-06-23T13:10:33Z",
    "id": "PL50C5F751CED39G71",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "reference": "YOUR_PAYMENT_REFERENCE",
    "shopperLocale": "nl-NL",
    "status": "expired",
    "url": "https://test.adyen.link/PL45D0F79183A4CCA2"
}

Customize the payment page

Learn how to customize:

  • Which payment methods are shown on the payment page, and in which order.
  • The appearance of the payment page, using themes.
  • The language shown on the payment page.

Payment methods

The payment methods are ordered by popularity, the most popular payment methods in the shopper's country appearing at the top.

In your Customer Area, you can configure which payment methods are rendered based on the shopper's country. If you want to customize payment methods for specific transactions, you can do this by including additional parameters in your API request.

Customize based on shopper's country

To configure payment methods in your Customer Area, you must have the Change payment methods user role.

To configure which payment methods are rendered (and in which order) based on the shopper's country:

  1. Log in to your Customer Area.
  2. Go to Account > Checkout settings.
  3. Select a Shopper country.
  4. Drag the payment methods into the order you want them to appear to shoppers in this country.
  5. To hide a payment method from shoppers in this country, drag it to the Other configured payment methods box.

Customize for specific transactions

When making a POST /paymentLinks request, you can include one of the following parameters:

To refer to payment methods, use their paymentMethod.type from Payment methods overview.

Here is an example of how you can create a payment link that only allows the shopper to pay with iDEAL or card:

Themes

Themes allow you to specify a background image and a brand logo to customize the appearance of the payment page. If you create several themes, you can choose a theme when you create the payment link.

Create a new theme

To create a theme, you must have one of the following user roles:

  • Merchant admin
  • Pay by Link Settings

To create a new theme:

  1. Log in to your Customer Area.
  2. Go to Pay by Link > Themes.
  3. Select Create a new theme
  4. Enter a Theme name. This name is visible to the user creating the payment link in the Customer Area.
  5. Enter a Display name. This name is visible to the shopper.
  6. Upload a brand logo.
  7. Upload a background image.
  8. Enter a background color. This color is used instead of the background image if the shopper's internet connection is too slow.
  9. If you want this to be the default theme for all payment links, select Set as default.
  10. Select Create.

Create a payment link with a specific theme

After the theme has been created, you see a Theme ID on the Customer Area page for that theme. To use the theme for a new payment link, include the themeId in your POST /paymentLinks request.

Here is an example of how you can create a payment link with a theme:

Language and localization

The default language of the payment page is the language of the shopper's browser locale. To change the language of payment page, send the shopperLocale parameter in your POST /paymentLinks request.

Pay by Link supports the following languages:

Language shopperLocale
Arabic - International ar
Chinese - Simplified zh-CN
Chinese - Traditional zh-TW
Croatian hr-HR
Czech cs-CZ
Danish da-DK
Dutch nl-NL
English - US en-US
Finnish fi-FI
French fr-FR
German de-DE
Greek el-GR
Hungarian hu-HU
Italian it-IT
Japanese ja-JP
Korean ko-KR
Norwegian no-NO
Polish pl-PL
Portuguese pt-BR
Romanian ro-RO
Russian ru-RU
Slovak sk-SK
Slovenian sl-SI
Spanish es-ES
Swedish sv-SE

Test and go live

Before going live, use our list of test cards and other payment methods to test your integration. We recommend testing each payment method that you intend to offer to your shoppers.

You can check the test payments in your Customer Area, under TransactionsPayments.

When you are ready to go live, you need to:

  1. Apply for a live account.
  2. Configure your live account
  3. Submit a request to add payment methods in your live Customer Area .
  4. Switch from test to our live endpoints.
  5. Add your terms and conditions to your live Customer Area.

See also