Pay by Link through the API

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:

• Create a reusable payment link.
• Tokenize your shopper's payment details for future one-off payments or for subscription payments.
• Provide additional information about the product or the shopper. This is required for some payment methods, for example buy now, pay later payment methods.
• Force the expiry of a payment link, for example if you sent a new payment link to your shopper.
• Customize the payment methods, style, and language shown on the payment page.

Before you begin

Before you begin to integrate, make sure you have followed the Get started with Adyen guide to:

• Get an overview of the steps needed to accept live payments.
• Create your test account.

After you have created your test account:

• Add your terms and conditions to the Pay by Link payment page.
• Generate your API key for creating payment links.
• Set up webhooks to keep track of the payment result.
• Add payment methods to your account.

Generate your API key

1. Log in to your Customer Area.
2. Go to Developers > API credentials, and select the API credential username for your integration, for example ws@Company.[YourCompanyAccount].
3. Under Server settings > Authentication select the API key tab.
4. Select Generate API key.
5. Select the copy icon and store your API key securely in your system.
6. Select Save changes.

Set up webhooks

Webhooks 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 webhooks, and make sure that your server can process and accept webhooks.

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 Settings > 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:

• merchantAccount: the name of your merchant account.
• reference: your identifier for the transaction.
• amount: the currency and value in minor units.

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 EUR 42:

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.

Step 2: Send the payment link to your shopper

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

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

The AUTHORISATION webhook 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.

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. The status can also be paymentPending if the payment has an asynchronous flow and the shopper hasn't yet completed the payment.

Create a reusable payment link

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 following example shows how to create a reusable payment link to accept donations for the amount of USD 8.50 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. Your /paymentLinks request must include a recurringProcessingModel to indicate how you want to use the token:

Business model	recurringProcessingModel	Description
One-off payments	CardOnFile	Tokenize the customer's card details, and with future payment links present the customer's stored card on the payment page.
Subscription payments	Subscription	Tokenize the customer's card for recurring payments that occur at regular intervals without the customer being present.
Unscheduled recurring payments	UnscheduledCardOnFile	Tokenize the customer's card for recurring payments that occur on a non-fixed schedule without the customer being present. This includes automatic top-ups when the cardholder's balance drops below a certain amount.

Tokenize for future one-off 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. Send the following in your POST /paymentLinks request:

   • A unique shopperReference of at least three characters.

     Your reference must not include personally identifiable information (PII), like name or email address.

   • storePaymentMethodMode set to askForConsent to allow the shopper to decide whether to store the details. If you already have the shopper's consent, set this parameter to enabled.
   • recurringProcessingModel set to CardOnFile.

   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.
   

2. 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 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. Send the following in your POST /paymentLinks request:

   • A unique shopperReference of at least three characters.

     Your reference must not include personally identifiable information (PII), like name or email address.

   • storePaymentMethodMode set to askForConsent to allow the shopper to decide whether to store the details. If you already have the shopper's consent, set this parameter to enabled.
   • recurringProcessingModel set to Subscription.
   • 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.

Tokenize for unscheduled recurring 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 on a non-fixed schedule.

1. Send the following in your POST /paymentLinks request:

   • A unique shopperReference of at least three characters.

     Your reference must not include personally identifiable information (PII), like name or email address.

   • storePaymentMethodMode set to askForConsent to allow the shopper to decide whether to store the details. If you already have the shopper's consent, set this parameter to enabled.
   • recurringProcessingModel set to UnscheduledCardOnFile.
   • 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 automatic top-ups, for a shopper with shopperReference Shopper-C5250.

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 recurring 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
PayBright (CA)	lineItems, shopperEmail, shopperName, deliveryAddress, billingAddress
Zip (AU)	lineItems, shopperEmail, shopperName, deliveryAddress, billingAddress

Provide product information

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

The following example shows how to 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:

• If using API version v67 or later, ask the shopper to fill in this information before they complete the payment, by including requiredShopperFields in your POST /paymentLinks request.
• Collect this information yourself, and include it in your POST /paymentLinks request.

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/{linkId} request and update the status.

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

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 Settings > 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:

• allowedPaymentMethods: only payment methods that you specify here will be rendered on the payment page.
• blockedPaymentMethods: payment methods that you specify here will not be rendered on the payment page.

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 and switch to your merchant account if necessary.
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. Available only on the merchant account.
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 - Brazil	pt-BR
Portuguese - Portugal	pt-PT
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 Transactions > Payments.

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

• Payment methods
• Tokenization
• Webhooks