Create a payment link

post/paymentLinks

Creates a payment link to our hosted payment form where shoppers 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.

Endpoint destination URL
https://checkout-test.adyen.com/v70/paymentLinks
Click to copy

Header Parameters

Idempotency-Keystring

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Parameters

allowedPaymentMethodsarray[string]

List of payment methods to be presented to the shopper. To refer to payment methods, use their payment method type.

Example: "allowedPaymentMethods":["ideal","giropay"]

amountobjectRequired

The payment amount and currency.

applicationInfoobject

Information about your application. For more details, see Building Adyen solutions.

billingAddressobject

The address where to send the invoice.

blockedPaymentMethodsarray[string]

List of payment methods to be hidden from the shopper. To refer to payment methods, use their payment method type.

Example: "blockedPaymentMethods":["ideal","giropay"]

captureDelayHoursinteger

The delay between the authorisation and scheduled auto-capture, specified in hours.

countryCodestring
Max length: 100

The shopper's two-letter country code.

dateOfBirthstring

The shopper's date of birth.

Format ISO-8601: YYYY-MM-DD

deliverAtstring

The date and time when the purchased goods should be delivered.

ISO 8601 format: YYYY-MM-DDThh:mm:ss+TZD, for example, 2020-12-18T10:15:30+01:00.

deliveryAddressobject

The address where the purchased goods should be delivered.

descriptionstring

A short description visible on the payment page. Maximum length: 280 characters.

expiresAtstring

The date when the payment link expires.

ISO 8601 format with time zone designator Z: YYYY-MM-DDThh:mm:ss+TZD, for example, 2020-12-18T10:15:30Z.

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.

fundOriginobject

The person or entity funding the money.

fundRecipientobject

the person or entity receiving the money

installmentOptionsobject

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]

Price and product information about the purchased items, to be included on the invoice sent to the shopper. This parameter is required for open invoice (buy now, pay later) payment methods such Afterpay, Clearpay, Klarna, RatePay, Riverty, and Zip.

manualCaptureboolean

Indicates if the payment must be captured manually.

mccstring
Max length: 16

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

merchantOrderReferencestring
Max length: 1000

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.

metadataobject
Max length: 80

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

Dictates the behavior of how a potential chargeback should be booked when using Adyen Platforms.

recurringProcessingModelstring
Max length: 50

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

A reference that is used to uniquely identify the payment in future communications about the payment status.

requiredShopperFieldsarray[string]

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.

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.
returnUrlstring
Max length: 8000

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.

reusableboolean

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.

riskDataobject

Any risk-related settings to apply to the payment.

shopperEmailstring
Max length: 500

The shopper's email address.

shopperLocalestring
Max length: 32

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.

shopperNameobject

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.

shopperReferencestring
Min length: 3Max length: 256

Your reference to uniquely identify this shopper, for example user ID or account ID. Minimum length: 3 characters.

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

shopperStatementstring
Max length: 10000

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 . , ' _ - ? + * /.

showRemovePaymentMethodButtonboolean

Set to false to hide the button that lets the shopper remove a stored payment method.

socialSecurityNumberstring
Max length: 32

The shopper's social security number.

splitCardFundingSourcesboolean

Boolean value indicating whether the card payment method should be split into separate debit and credit options.

splitsarray[object]

An array of objects specifying how to split a payment when using Adyen for Platforms, Classic Platforms integration, or Issuing.

storestring

The physical store, for which this payment is processed.

storePaymentMethodModestring

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 UI lets the shopper choose if they want their payment details to be stored.
  • 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.
telephoneNumberstring
Max length: 32

The shopper's telephone number.

themeIdstring

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

threeDS2RequestDataobject

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.

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

  • 201 - Created

    The request has succeeded.

    Show moreShow less
  • 400 - Bad Request

    A problem reading or understanding the request.

    Show moreShow less
  • 401 - Unauthorized

    Authentication required.

    Show moreShow less
  • 403 - Forbidden

    Insufficient permissions to process the request.

    Show moreShow less
  • 422 - Unprocessable Entity

    A request validation error.

    Show moreShow less
  • 500 - Internal Server Error

    The server could not process the request.

    Show moreShow less