Sample - Adyen Checkout API
POST/paymentLinks

Create a payment link

Creates a payment link to a Pay by Link page where the shopper can pay. The list of payment methods presented to the shopper depends on the currency and country parameters sent in the request.

For more information, refer to Pay by Link documentation.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 42 body fields
Idempotency-Keystringoptional
A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).
allowedPaymentMethodsarray<string>optional
List of payment methods to be presented to the shopper. To refer to payment methods, use their [payment method type](https://docs.adyen.com/payment-methods/payment-method-types). Example: `"allowedPaymentMethods":["ideal","applepay"]`
amountobjectrequired
The payment amount and currency.
applicationInfoobjectoptional
Information about your application. For more details, see [Building Adyen solutions](https://docs.adyen.com/development-resources/building-adyen-solutions).
billingAddressobjectoptional
The address where to send the invoice.
blockedPaymentMethodsarray<string>optional
List of payment methods to be hidden from the shopper. To refer to payment methods, use their [payment method type](https://docs.adyen.com/payment-methods/payment-method-types). Example: `"blockedPaymentMethods":["ideal","applepay"]`
captureDelayHoursintegeroptional
The delay between the authorisation and scheduled auto-capture, specified in hours.
countryCodestringoptional
The shopper's two-letter country code.
dateOfBirthstringoptional
The shopper's date of birth. Format [ISO-8601](https://www.w3.org/TR/NOTE-datetime): YYYY-MM-DD
deliverAtstringoptional
The date and time when the purchased goods should be delivered. [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format: YYYY-MM-DDThh:mm:ss+TZD, for example, **2020-12-18T10:15:30+01:00**.
deliveryAddressobjectoptional
The address where the purchased goods should be delivered.
descriptionstringoptional
A short description visible on the payment page. Maximum length: 280 characters.
expiresAtstringoptional
The date when the payment link expires. [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format with time zone offset: YYYY-MM-DDThh:mm:ss+TZD, for example, **2020-12-18T10:15:30+01:00**. The maximum expiry date is 70 days after the payment link is created. If not provided, the payment link expires 24 hours after it was created.
fundOriginobjectoptional
The person or entity funding the money.
fundRecipientobjectoptional
the person or entity receiving the money
installmentOptionsobjectoptional
A set of key-value pairs that specifies the installment options available per payment method. The key must be a payment method name in lowercase. For example, **card** to specify installment options for all cards, or **visa** or **mc**. The value must be an object containing the installment options.
lineItemsarray<object>optional
Price and product information about the purchased items, to be included on the invoice sent to the shopper. > This field is required for 3x 4x Oney, Affirm, Afterpay, Clearpay, Klarna, Ratepay, and Riverty.
manualCapturebooleanoptional
Indicates if the payment must be [captured manually](https://docs.adyen.com/online-payments/capture).
mccstringoptional
The [merchant category code](https://en.wikipedia.org/wiki/Merchant_category_code) (MCC) is a four-digit number, which relates to a particular market segment. This code reflects the predominant activity that is conducted by the merchant.
merchantAccountstringrequired
The merchant account identifier for which the payment link is created.
merchantOrderReferencestringoptional
This reference allows linking multiple transactions to each other for reporting purposes (for example, order auth-rate). The reference should be unique per billing cycle.
metadataobjectoptional
Metadata consists of entries, each of which includes a key and a value. Limitations: * Maximum 20 key-value pairs per request. Otherwise, error "177" occurs: "Metadata size exceeds limit" * Maximum 20 characters per key. Otherwise, error "178" occurs: "Metadata key size exceeds limit" * A key cannot have the name `checkout.linkId`. Any value that you provide with this key is going to be replaced by the real payment link ID.
platformChargebackLogicobjectoptional
Dictates the behavior of how a potential chargeback should be booked when using Adyen Platforms.
recurringProcessingModelstringoptional
Defines a recurring payment type. Required when `storePaymentMethodMode` is set to **askForConsent** or **enabled**. Possible values: * **Subscription** – A transaction for a fixed or variable amount, which follows a fixed schedule. * **CardOnFile** – With a card-on-file (CoF) transaction, card details are stored to enable one-click or omnichannel journeys, or simply to streamline the checkout process. Any subscription not following a fixed schedule is also considered a card-on-file transaction. * **UnscheduledCardOnFile** – An unscheduled card-on-file (UCoF) transaction is a transaction that occurs on a non-fixed schedule and/or has variable amounts. For example, automatic top-ups when a cardholder's balance drops below a certain amount.
Allowed:CardOnFileSubscriptionUnscheduledCardOnFile
referencestringrequired
A reference that is used to uniquely identify the payment in future communications about the payment status.
requiredShopperFieldsarray<string>optional
List of fields that the shopper has to provide on the payment page before completing the payment. For more information, refer to [Provide shopper information](https://docs.adyen.com/unified-commerce/pay-by-link/payment-links/api#shopper-information). Possible values: * **billingAddress** – The address where to send the invoice. * **deliveryAddress** – The address where the purchased goods should be delivered. * **shopperEmail** – The shopper's email address. * **shopperName** – The shopper's full name. * **telephoneNumber** – The shopper's phone number.
returnUrlstringoptional
Website URL used for redirection after payment is completed. If provided, a **Continue** button will be shown on the payment page. If shoppers select the button, they are redirected to the specified URL.
reusablebooleanoptional
Indicates whether the payment link can be reused for multiple payments. If not provided, this defaults to **false** which means the link can be used for one successful payment only.
riskDataobjectoptional
Any risk-related settings to apply to the payment.
shopperEmailstringoptional
The shopper's email address.
shopperLocalestringoptional
The language to be used in the payment page, specified by a combination of a language and country code. For example, `en-US`. For a list of shopper locales that Pay by Link supports, refer to [Language and localization](https://docs.adyen.com/unified-commerce/pay-by-link/payment-links/api#language).
shopperNameobjectoptional
The shopper's full name. This object is required for some payment methods such as AfterPay, Klarna, or if you're enrolled in the PayPal Seller Protection program.
shopperReferencestringoptional
Your reference to uniquely identify this shopper, for example user ID or account ID. The value is case-sensitive and must be at least three characters. > Your reference must not include personally identifiable information (PII) such as name or email address.
shopperStatementstringoptional
The text to be shown on the shopper's bank statement. We recommend sending a maximum of 22 characters, otherwise banks might truncate the string. Allowed characters: **a-z**, **A-Z**, **0-9**, spaces, and special characters **. , ' _ - ? + * /**.
showRemovePaymentMethodButtonbooleanoptional
Set to **false** to hide the button that lets the shopper remove a stored payment method.
Default:true
socialSecurityNumberstringoptional
The shopper's social security number.
splitCardFundingSourcesbooleanoptional
Boolean value indicating whether the card payment method should be split into separate debit and credit options.
Default:false
splitsarray<object>optional
An array of objects specifying how to split a payment when using [Adyen for Platforms](https://docs.adyen.com/platforms/process-payments#providing-split-information), [Classic Platforms integration](https://docs.adyen.com/classic-platforms/processing-payments#providing-split-information), or [Issuing](https://docs.adyen.com/issuing/manage-funds#split).
storestringoptional
The physical store, for which this payment is processed.
storePaymentMethodModestringoptional
Indicates if the details of the payment method will be stored for the shopper. Possible values: * **disabled** – No details will be stored (default). * **askForConsent** – If the `shopperReference` is provided, the Drop-in/Component shows a checkbox where the shopper can select to store their payment details for card payments. * **enabled** – If the `shopperReference` is provided, the details will be stored without asking the shopper for consent. When set to **askForConsent** or **enabled**, you must also include the `recurringProcessingModel` parameter.
Allowed:askForConsentdisabledenabled
telephoneNumberstringoptional
The shopper's telephone number. The phone number must include a plus sign (+) and a country code (1-3 digits), followed by the number (4-15 digits). If the value you provide does not follow the guidelines, we do not submit it for authentication. > Required for Visa and JCB transactions that require 3D Secure 2 authentication, if you did not include the `shopperEmail`.
themeIdstringoptional
A [theme](https://docs.adyen.com/unified-commerce/pay-by-link/payment-links/api#themes) to customize the appearance of the payment page. If not specified, the payment page is rendered according to the theme set as default in your Customer Area.
threeDS2RequestDataobjectoptional
The cardholder phone number need to be part of the authentication message for payment data. It is a requirement for Visa Secure Authentication Data Field Mandate effective August 2024.

6 status codes
201Created - the request has succeeded.
allowedPaymentMethodsarray<string>optional
List of payment methods to be presented to the shopper. To refer to payment methods, use their [payment method type](https://docs.adyen.com/payment-methods/payment-method-types). Example: `"allowedPaymentMethods":["ideal","applepay"]`
amountobjectrequired
The payment amount and currency.
applicationInfoobjectoptional
Information about your application. For more details, see [Building Adyen solutions](https://docs.adyen.com/development-resources/building-adyen-solutions).
billingAddressobjectoptional
The address where to send the invoice.
blockedPaymentMethodsarray<string>optional
List of payment methods to be hidden from the shopper. To refer to payment methods, use their [payment method type](https://docs.adyen.com/payment-methods/payment-method-types). Example: `"blockedPaymentMethods":["ideal","applepay"]`
captureDelayHoursintegeroptional
The delay between the authorisation and scheduled auto-capture, specified in hours.
countryCodestringoptional
The shopper's two-letter country code.
dateOfBirthstringoptional
The shopper's date of birth. Format [ISO-8601](https://www.w3.org/TR/NOTE-datetime): YYYY-MM-DD
deliverAtstringoptional
The date and time when the purchased goods should be delivered. [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format: YYYY-MM-DDThh:mm:ss+TZD, for example, **2020-12-18T10:15:30+01:00**.
deliveryAddressobjectoptional
The address where the purchased goods should be delivered.
descriptionstringoptional
A short description visible on the payment page. Maximum length: 280 characters.
expiresAtstringoptional
The date when the payment link expires. [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format with time zone offset: YYYY-MM-DDThh:mm:ss+TZD, for example, **2020-12-18T10:15:30+01:00**. The maximum expiry date is 70 days after the payment link is created. If not provided, the payment link expires 24 hours after it was created.
fundOriginobjectoptional
The person or entity funding the money.
fundRecipientobjectoptional
the person or entity receiving the money
idstringrequired
A unique identifier of the payment link.
installmentOptionsobjectoptional
A set of key-value pairs that specifies the installment options available per payment method. The key must be a payment method name in lowercase. For example, **card** to specify installment options for all cards, or **visa** or **mc**. The value must be an object containing the installment options.
lineItemsarray<object>optional
Price and product information about the purchased items, to be included on the invoice sent to the shopper. > This field is required for 3x 4x Oney, Affirm, Afterpay, Clearpay, Klarna, Ratepay, and Riverty.
manualCapturebooleanoptional
Indicates if the payment must be [captured manually](https://docs.adyen.com/online-payments/capture).
mccstringoptional
The [merchant category code](https://en.wikipedia.org/wiki/Merchant_category_code) (MCC) is a four-digit number, which relates to a particular market segment. This code reflects the predominant activity that is conducted by the merchant.
merchantAccountstringrequired
The merchant account identifier for which the payment link is created.
merchantOrderReferencestringoptional
This reference allows linking multiple transactions to each other for reporting purposes (for example, order auth-rate). The reference should be unique per billing cycle.
metadataobjectoptional
Metadata consists of entries, each of which includes a key and a value. Limitations: * Maximum 20 key-value pairs per request. Otherwise, error "177" occurs: "Metadata size exceeds limit" * Maximum 20 characters per key. Otherwise, error "178" occurs: "Metadata key size exceeds limit" * A key cannot have the name `checkout.linkId`. Any value that you provide with this key is going to be replaced by the real payment link ID.
platformChargebackLogicobjectoptional
Dictates the behavior of how a potential chargeback should be booked when using Adyen Platforms.
recurringProcessingModelstringoptional
Defines a recurring payment type. Required when `storePaymentMethodMode` is set to **askForConsent** or **enabled**. Possible values: * **Subscription** – A transaction for a fixed or variable amount, which follows a fixed schedule. * **CardOnFile** – With a card-on-file (CoF) transaction, card details are stored to enable one-click or omnichannel journeys, or simply to streamline the checkout process. Any subscription not following a fixed schedule is also considered a card-on-file transaction. * **UnscheduledCardOnFile** – An unscheduled card-on-file (UCoF) transaction is a transaction that occurs on a non-fixed schedule and/or has variable amounts. For example, automatic top-ups when a cardholder's balance drops below a certain amount.
Allowed:CardOnFileSubscriptionUnscheduledCardOnFile
referencestringrequired
A reference that is used to uniquely identify the payment in future communications about the payment status.
requiredShopperFieldsarray<string>optional
List of fields that the shopper has to provide on the payment page before completing the payment. For more information, refer to [Provide shopper information](https://docs.adyen.com/unified-commerce/pay-by-link/payment-links/api#shopper-information). Possible values: * **billingAddress** – The address where to send the invoice. * **deliveryAddress** – The address where the purchased goods should be delivered. * **shopperEmail** – The shopper's email address. * **shopperName** – The shopper's full name. * **telephoneNumber** – The shopper's phone number.
returnUrlstringoptional
Website URL used for redirection after payment is completed. If provided, a **Continue** button will be shown on the payment page. If shoppers select the button, they are redirected to the specified URL.
reusablebooleanoptional
Indicates whether the payment link can be reused for multiple payments. If not provided, this defaults to **false** which means the link can be used for one successful payment only.
riskDataobjectoptional
Any risk-related settings to apply to the payment.
shopperEmailstringoptional
The shopper's email address.
shopperLocalestringoptional
The language to be used in the payment page, specified by a combination of a language and country code. For example, `en-US`. For a list of shopper locales that Pay by Link supports, refer to [Language and localization](https://docs.adyen.com/unified-commerce/pay-by-link/payment-links/api#language).
shopperNameobjectoptional
The shopper's full name. This object is required for some payment methods such as AfterPay, Klarna, or if you're enrolled in the PayPal Seller Protection program.
shopperReferencestringoptional
Your reference to uniquely identify this shopper, for example user ID or account ID. The value is case-sensitive and must be at least three characters. > Your reference must not include personally identifiable information (PII) such as name or email address.
shopperStatementstringoptional
The text to be shown on the shopper's bank statement. We recommend sending a maximum of 22 characters, otherwise banks might truncate the string. Allowed characters: **a-z**, **A-Z**, **0-9**, spaces, and special characters **. , ' _ - ? + * /**.
showRemovePaymentMethodButtonbooleanoptional
Set to **false** to hide the button that lets the shopper remove a stored payment method.
Default:true
socialSecurityNumberstringoptional
The shopper's social security number.
splitCardFundingSourcesbooleanoptional
Boolean value indicating whether the card payment method should be split into separate debit and credit options.
Default:false
splitsarray<object>optional
An array of objects specifying how to split a payment when using [Adyen for Platforms](https://docs.adyen.com/platforms/process-payments#providing-split-information), [Classic Platforms integration](https://docs.adyen.com/classic-platforms/processing-payments#providing-split-information), or [Issuing](https://docs.adyen.com/issuing/manage-funds#split).
statusstringrequired
Status of the payment link. Possible values: * **active**: The link can be used to make payments. * **expired**: The expiry date for the payment link has passed. Shoppers can no longer use the link to make payments. * **completed**: The shopper completed the payment. * **paymentPending**: The shopper is in the process of making the payment. Applies to payment methods with an asynchronous flow.
Allowed:activecompletedexpiredpaidpaymentPending
storestringoptional
The physical store, for which this payment is processed.
storePaymentMethodModestringoptional
Indicates if the details of the payment method will be stored for the shopper. Possible values: * **disabled** – No details will be stored (default). * **askForConsent** – If the `shopperReference` is provided, the Drop-in/Component shows a checkbox where the shopper can select to store their payment details for card payments. * **enabled** – If the `shopperReference` is provided, the details will be stored without asking the shopper for consent. When set to **askForConsent** or **enabled**, you must also include the `recurringProcessingModel` parameter.
Allowed:askForConsentdisabledenabled
telephoneNumberstringoptional
The shopper's telephone number. The phone number must include a plus sign (+) and a country code (1-3 digits), followed by the number (4-15 digits). If the value you provide does not follow the guidelines, we do not submit it for authentication. > Required for Visa and JCB transactions that require 3D Secure 2 authentication, if you did not include the `shopperEmail`.
themeIdstringoptional
A [theme](https://docs.adyen.com/unified-commerce/pay-by-link/payment-links/api#themes) to customize the appearance of the payment page. If not specified, the payment page is rendered according to the theme set as default in your Customer Area.
threeDS2RequestDataobjectoptional
The cardholder phone number need to be part of the authentication message for payment data. It is a requirement for Visa Secure Authentication Data Field Mandate effective August 2024.
updatedAtstringoptional
The date when the payment link status was updated. [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format: YYYY-MM-DDThh:mm:ss+TZD, for example, **2020-12-18T10:15:30+01:00**.
urlstringrequired
The URL at which the shopper can complete the payment.
400Bad Request - a problem reading or understanding the request.
additionalDataobjectoptional
Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
errorCodestringoptional
The error code mapped to the error message.
errorTypestringoptional
The category of the error.
messagestringoptional
A short explanation of the issue.
pspReferencestringoptional
The PSP reference of the payment.
statusintegeroptional
The HTTP response status.
401Unauthorized - authentication required.
additionalDataobjectoptional
Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
errorCodestringoptional
The error code mapped to the error message.
errorTypestringoptional
The category of the error.
messagestringoptional
A short explanation of the issue.
pspReferencestringoptional
The PSP reference of the payment.
statusintegeroptional
The HTTP response status.
403Forbidden - insufficient permissions to process the request.
additionalDataobjectoptional
Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
errorCodestringoptional
The error code mapped to the error message.
errorTypestringoptional
The category of the error.
messagestringoptional
A short explanation of the issue.
pspReferencestringoptional
The PSP reference of the payment.
statusintegeroptional
The HTTP response status.
422Unprocessable Entity - a request validation error.
additionalDataobjectoptional
Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
errorCodestringoptional
The error code mapped to the error message.
errorTypestringoptional
The category of the error.
messagestringoptional
A short explanation of the issue.
pspReferencestringoptional
The PSP reference of the payment.
statusintegeroptional
The HTTP response status.
500Internal Server Error - the server could not process the request.
additionalDataobjectoptional
Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
errorCodestringoptional
The error code mapped to the error message.
errorTypestringoptional
The category of the error.
messagestringoptional
A short explanation of the issue.
pspReferencestringoptional
The PSP reference of the payment.
statusintegeroptional
The HTTP response status.

Error handling

A 400 is returned: Bad Request - a problem reading or understanding the request. A 401 is returned: Unauthorized - authentication required. A 403 is returned: Forbidden - insufficient permissions to process the request. A 422 is returned: Unprocessable Entity - a request validation error. A 500 is returned: Internal Server Error - the server could not process the request.