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.
Servers
- https://checkout-test.adyen.com/v71
Request headers
Name | Type | Required | Description |
---|---|---|---|
Content-Type |
String | Yes |
The media type of the request body.
Default value: "application/json" |
Idempotency-Key |
String | No |
A unique identifier for the message with a maximum of 64 characters (we recommend a UUID). |
Request body fields
Name | Type | Required | Description |
---|---|---|---|
fundOrigin |
Object | No |
The person or entity funding the money. |
fundOrigin.shopperEmail |
String | No |
The email address of the person funding the money. |
fundOrigin.shopperName |
Object | No |
The name of the person funding the money. |
fundOrigin.shopperName.lastName |
String | Yes |
The last name. |
fundOrigin.shopperName.firstName |
String | Yes |
The first name. |
fundOrigin.billingAddress |
Object | No |
The address where to send the invoice. |
fundOrigin.billingAddress.postalCode |
String | Yes |
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries. |
fundOrigin.billingAddress.stateOrProvince |
String | No |
The two-character ISO 3166-2 state or province code. For example, CA in the US or ON in Canada.
|
fundOrigin.billingAddress.country |
String | Yes |
The two-character ISO-3166-1 alpha-2 country code. For example, US.
|
fundOrigin.billingAddress.houseNumberOrName |
String | Yes |
The number or name of the house. Maximum length: 3000 characters. |
fundOrigin.billingAddress.street |
String | Yes |
The name of the street. Maximum length: 3000 characters.
|
fundOrigin.billingAddress.city |
String | Yes |
The name of the city. Maximum length: 3000 characters. |
fundOrigin.telephoneNumber |
String | No |
The phone number of the person funding the money. |
fundOrigin.walletIdentifier |
String | No |
The unique identifier of the wallet where the funds are coming from. |
requiredShopperFields[] |
Array | No |
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:
|
shopperReference |
String | No |
Your reference to uniquely identify this shopper, for example user ID or account ID. Minimum length: 3 characters.
|
mcc |
String | No |
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. |
description |
String | No |
A short description visible on the payment page. Maximum length: 280 characters. |
storePaymentMethodMode |
String | No |
Indicates if the details of the payment method will be stored for the shopper. Possible values:
Possible values:
|
shopperName |
Object | No |
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. |
shopperName.lastName |
String | Yes |
The last name. |
shopperName.firstName |
String | Yes |
The first name. |
metadata |
Object | No |
Metadata consists of entries, each of which includes a key and a value. Limitations:
|
installmentOptions |
Object | No |
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. |
shopperStatement |
String | No |
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 . , ' _ - ? + * /. |
merchantAccount |
String | Yes |
The merchant account identifier for which the payment link is created. |
shopperLocale |
String | No |
The language to be used in the payment page, specified by a combination of a language and country code. For example, For a list of shopper locales that Pay by Link supports, refer to Language and localization. |
telephoneNumber |
String | No |
The shopper's telephone number. |
blockedPaymentMethods[] |
Array | No |
List of payment methods to be hidden from the shopper. To refer to payment methods, use their payment method type. Example: |
recurringProcessingModel |
String | No |
Defines a recurring payment type. Required when
Possible values:
|
manualCapture |
Boolean | No |
Indicates if the payment must be captured manually. |
splits[] |
Array | No |
An array of objects specifying how to split a payment when using Adyen for Platforms, Classic Platforms integration, or Issuing. |
splits[].account |
String | No |
The unique identifier of the account to which the split amount is booked. Required if
|
splits[].description |
String | No |
Your description for the split item. |
splits[].amount |
Object | No |
The amount of the split item.
|
splits[].amount.value |
Integer | Yes |
The value of the split amount, in minor units. |
splits[].amount.currency |
String | No |
The three-character ISO currency code. By default, this is the original payment currency. |
splits[].type |
String | Yes |
The part of the payment you want to book to the specified Possible values for the Balance Platform:
Possible values for the Classic Platforms integration: Commission, Default, MarketPlace, PaymentFee, VAT. Possible values:
|
splits[].reference |
String | No |
Your unique reference for the part of the payment booked to the specified This is required if For the other types, we also recommend providing a unique reference so you can reconcile the split and the associated payment in the transaction overview and in the reports. |
expiresAt |
String | No |
The date when the payment link expires. ISO 8601 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. |
returnUrl |
String | No |
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. |
reference |
String | Yes |
A reference that is used to uniquely identify the payment in future communications about the payment status. |
socialSecurityNumber |
String | No |
The shopper's social security number. |
store |
String | No |
The physical store, for which this payment is processed. |
lineItems[] |
Array | No |
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. |
lineItems[].size |
String | No |
Size of the item. |
lineItems[].description |
String | No |
Description of the line item. |
lineItems[].brand |
String | No |
Brand of the item. |
lineItems[].taxAmount |
Integer | No |
Tax amount, in minor units. |
lineItems[].quantity |
Integer | No |
Number of items. |
lineItems[].productUrl |
String | No |
Link to the purchased item. |
lineItems[].amountExcludingTax |
Integer | No |
Item amount excluding the tax, in minor units. |
lineItems[].imageUrl |
String | No |
Link to the picture of the purchased item. |
lineItems[].marketplaceSellerId |
String | No |
Marketplace seller id. |
lineItems[].id |
String | No |
ID of the line item. |
lineItems[].amountIncludingTax |
Integer | No |
Item amount including the tax, in minor units. |
lineItems[].itemCategory |
String | No |
Item category, used by the payment methods PayPal and Ratepay. |
lineItems[].receiverEmail |
String | No |
Email associated with the given product in the basket (usually in electronic gift cards). |
lineItems[].sku |
String | No |
Stock keeping unit. |
lineItems[].manufacturer |
String | No |
Manufacturer of the item. |
lineItems[].taxPercentage |
Integer | No |
Tax percentage, in minor units. |
lineItems[].upc |
String | No |
Universal Product Code. |
lineItems[].color |
String | No |
Color of the item. |
platformChargebackLogic |
Object | No |
Dictates the behavior of how a potential chargeback should be booked when using Adyen Platforms. |
platformChargebackLogic.costAllocationAccount |
String | No |
The unique identifier of the balance account to which the chargeback fees are booked. By default, the chargeback fees are booked to your liable balance account. |
platformChargebackLogic.targetAccount |
String | No |
The unique identifier of the balance account against which the disputed amount is booked. Required if |
platformChargebackLogic.behavior |
String | No |
The method of handling the chargeback. Possible values: deductFromLiableAccount, deductFromOneBalanceAccount, deductAccordingToSplitRatio. Possible values:
|
merchantOrderReference |
String | No |
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. |
deliveryAddress |
Object | No |
The address where the purchased goods should be delivered. |
deliveryAddress.postalCode |
String | Yes |
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries. |
deliveryAddress.stateOrProvince |
String | No |
The two-character ISO 3166-2 state or province code. For example, CA in the US or ON in Canada.
|
deliveryAddress.country |
String | Yes |
The two-character ISO-3166-1 alpha-2 country code. For example, US.
|
deliveryAddress.houseNumberOrName |
String | Yes |
The number or name of the house. Maximum length: 3000 characters. |
deliveryAddress.street |
String | Yes |
The name of the street. Maximum length: 3000 characters.
|
deliveryAddress.city |
String | Yes |
The name of the city. Maximum length: 3000 characters. |
deliverAt |
String | No |
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. |
fundRecipient |
Object | No |
the person or entity receiving the money |
fundRecipient.walletPurpose |
String | No |
The purpose of a digital wallet transaction. Possible values:
|
fundRecipient.paymentMethod |
Object | No |
The payment method used by the shopper. |
fundRecipient.paymentMethod.srcTokenReference |
String | No |
The reference for the Click to Pay token. |
fundRecipient.paymentMethod.encryptedSecurityCode |
String | No |
The encrypted card verification code. |
fundRecipient.paymentMethod.cvc |
String | No |
The card verification code. Only collect raw card data if you are fully PCI compliant. |
fundRecipient.paymentMethod.brand |
String | No |
Secondary brand of the card. For example: plastix, hmclub. |
fundRecipient.paymentMethod.number |
String | No |
The card number. Only collect raw card data if you are fully PCI compliant. |
fundRecipient.paymentMethod.expiryMonth |
String | No |
The card expiry month. Only collect raw card data if you are fully PCI compliant. |
fundRecipient.paymentMethod.fundingSource |
String | No |
The funding source that should be used when multiple sources are available. For Brazilian combo cards, by default the funding source is credit. To use debit, set this value to debit. Possible values:
|
fundRecipient.paymentMethod.srcCorrelationId |
String | No |
An identifier used for the Click to Pay transaction. |
fundRecipient.paymentMethod.encryptedExpiryYear |
String | No |
The encrypted card expiry year. |
fundRecipient.paymentMethod.srcScheme |
String | No |
The scheme that is being used for Click to Pay. |
fundRecipient.paymentMethod.encryptedExpiryMonth |
String | No |
The encrypted card expiry month. |
fundRecipient.paymentMethod.networkPaymentReference |
String | No |
The transaction identifier from card schemes. This is the |
fundRecipient.paymentMethod.srcDigitalCardId |
String | No |
The SRC reference for the Click to Pay token. |
fundRecipient.paymentMethod.threeDS2SdkVersion |
String | No |
Required for mobile integrations. Version of the 3D Secure 2 mobile SDK. |
fundRecipient.paymentMethod.recurringDetailReference |
String | No |
This is the |
fundRecipient.paymentMethod.cupsecureplus.smscode |
String | No | |
fundRecipient.paymentMethod.shopperNotificationReference |
String | No |
The |
fundRecipient.paymentMethod.holderName |
String | No |
The name of the card holder. |
fundRecipient.paymentMethod.type |
String | No |
Default payment method details. Common for scheme payment methods, and for simple payment method details. Possible values:
Default value: "scheme" |
fundRecipient.paymentMethod.storedPaymentMethodId |
String | No |
This is the |
fundRecipient.paymentMethod.encryptedCardNumber |
String | No |
The encrypted card number. |
fundRecipient.paymentMethod.checkoutAttemptId |
String | No |
The checkout attempt identifier. |
fundRecipient.paymentMethod.expiryYear |
String | No |
The card expiry year. Only collect raw card data if you are fully PCI compliant. |
fundRecipient.shopperReference |
String | No |
Required for recurring payments. Your reference to uniquely identify this shopper, for example user ID or account ID. Minimum length: 3 characters.
|
fundRecipient.shopperEmail |
String | No |
The email address of the shopper. |
fundRecipient.subMerchant |
Object | No |
Required for back-to-back/purchase-driven-load transactions, where the funds are taken from the shopper's stored card when the wallet balance is insufficient. The final merchant who will receive the money, also known as a sub-merchant. |
fundRecipient.subMerchant.mcc |
String | No |
The sub-merchant's 4-digit Merchant Category Code (MCC).
|
fundRecipient.subMerchant.name |
String | No |
The name of the sub-merchant. Based on scheme specifications, this value will overwrite the shopper statement that will appear in the card statement.
|
fundRecipient.subMerchant.taxId |
String | No |
The tax ID of the sub-merchant.
|
fundRecipient.subMerchant.country |
String | No |
The three-letter country code of the sub-merchant's address. For example, BRA for Brazil.
|
fundRecipient.subMerchant.city |
String | No |
The city of the sub-merchant's address.
|
fundRecipient.shopperName |
Object | No |
The name of the shopper. |
fundRecipient.shopperName.lastName |
String | Yes |
The last name. |
fundRecipient.shopperName.firstName |
String | Yes |
The first name. |
fundRecipient.walletOwnerTaxId |
String | No |
The tax identifier of the person receiving the funds. |
fundRecipient.IBAN |
String | No |
The IBAN of the bank account where the funds are being transferred to. |
fundRecipient.billingAddress |
Object | No |
The address where to send the invoice. |
fundRecipient.billingAddress.postalCode |
String | Yes |
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries. |
fundRecipient.billingAddress.stateOrProvince |
String | No |
The two-character ISO 3166-2 state or province code. For example, CA in the US or ON in Canada.
|
fundRecipient.billingAddress.country |
String | Yes |
The two-character ISO-3166-1 alpha-2 country code. For example, US.
|
fundRecipient.billingAddress.houseNumberOrName |
String | Yes |
The number or name of the house. Maximum length: 3000 characters. |
fundRecipient.billingAddress.street |
String | Yes |
The name of the street. Maximum length: 3000 characters.
|
fundRecipient.billingAddress.city |
String | Yes |
The name of the city. Maximum length: 3000 characters. |
fundRecipient.storedPaymentMethodId |
String | No |
This is the |
fundRecipient.telephoneNumber |
String | No |
The telephone number of the shopper. |
fundRecipient.walletIdentifier |
String | No |
The unique identifier for the wallet the funds are being transferred to. You can use the shopper reference or any other identifier. |
reusable |
Boolean | No |
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. |
captureDelayHours |
Integer | No |
The delay between the authorisation and scheduled auto-capture, specified in hours. |
threeDS2RequestData |
Object | No |
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. |
threeDS2RequestData.threeDSRequestorChallengeInd |
String | No |
Indicates whether a challenge is requested for this transaction. Possible values:
Possible values:
|
threeDS2RequestData.workPhone |
Object | No |
The work phone number provided by the Cardholder. |
threeDS2RequestData.workPhone.cc |
String | No |
Country code. Length: 1–3 characters. |
threeDS2RequestData.workPhone.subscriber |
String | No |
Subscriber number. Maximum length: 15 characters. |
threeDS2RequestData.mobilePhone |
Object | No |
The mobile phone number provided by the Cardholder. |
threeDS2RequestData.mobilePhone.cc |
String | No |
Country code. Length: 1–3 characters. |
threeDS2RequestData.mobilePhone.subscriber |
String | No |
Subscriber number. Maximum length: 15 characters. |
threeDS2RequestData.homePhone |
Object | No |
The home phone number provided by the Cardholder. |
threeDS2RequestData.homePhone.cc |
String | No |
Country code. Length: 1–3 characters. |
threeDS2RequestData.homePhone.subscriber |
String | No |
Subscriber number. Maximum length: 15 characters. |
billingAddress |
Object | No |
The address where to send the invoice. |
billingAddress.postalCode |
String | Yes |
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries. |
billingAddress.stateOrProvince |
String | No |
The two-character ISO 3166-2 state or province code. For example, CA in the US or ON in Canada.
|
billingAddress.country |
String | Yes |
The two-character ISO-3166-1 alpha-2 country code. For example, US.
|
billingAddress.houseNumberOrName |
String | Yes |
The number or name of the house. Maximum length: 3000 characters. |
billingAddress.street |
String | Yes |
The name of the street. Maximum length: 3000 characters.
|
billingAddress.city |
String | Yes |
The name of the city. Maximum length: 3000 characters. |
countryCode |
String | No |
The shopper's two-letter country code. |
showRemovePaymentMethodButton |
Boolean | No |
Set to false to hide the button that lets the shopper remove a stored payment method. Default value: true |
applicationInfo |
Object | No |
Information about your application. For more details, see Building Adyen solutions. |
applicationInfo.merchantApplication |
Object | No |
Merchant developed software, such as cashier application, used to interact with the Adyen API. |
applicationInfo.merchantApplication.name |
String | No |
Name of the field. For example, Name of External Platform. |
applicationInfo.merchantApplication.version |
String | No |
Version of the field. For example, Version of External Platform. |
applicationInfo.externalPlatform |
Object | No |
Third-party developed platform used to initiate payment requests. For example, Magento, Zuora, etc. |
applicationInfo.externalPlatform.integrator |
String | No |
External platform integrator. |
applicationInfo.externalPlatform.name |
String | No |
Name of the field. For example, Name of External Platform. |
applicationInfo.externalPlatform.version |
String | No |
Version of the field. For example, Version of External Platform. |
applicationInfo.merchantDevice |
Object | No |
Merchant device information. |
applicationInfo.merchantDevice.osVersion |
String | No |
Version of the operating system on the merchant device. |
applicationInfo.merchantDevice.os |
String | No |
Operating system running on the merchant device. |
applicationInfo.merchantDevice.reference |
String | No |
Merchant device reference. |
applicationInfo.adyenLibrary |
Object | No |
Adyen-developed software, such as libraries and plugins, used to interact with the Adyen API. For example, Magento plugin, Java API library, etc. |
applicationInfo.adyenLibrary.name |
String | No |
Name of the field. For example, Name of External Platform. |
applicationInfo.adyenLibrary.version |
String | No |
Version of the field. For example, Version of External Platform. |
applicationInfo.shopperInteractionDevice |
Object | No |
Shopper interaction device, such as terminal, mobile device or web browser, to initiate payment requests. |
applicationInfo.shopperInteractionDevice.osVersion |
String | No |
Version of the operating system on the shopper interaction device. |
applicationInfo.shopperInteractionDevice.locale |
String | No |
Locale on the shopper interaction device. |
applicationInfo.shopperInteractionDevice.os |
String | No |
Operating system running on the shopper interaction device. |
applicationInfo.adyenPaymentSource |
Object | No |
Adyen-developed software to get payment details. For example, Checkout SDK, Secured Fields SDK, etc. |
applicationInfo.adyenPaymentSource.name |
String | No |
Name of the field. For example, Name of External Platform. |
applicationInfo.adyenPaymentSource.version |
String | No |
Version of the field. For example, Version of External Platform. |
allowedPaymentMethods[] |
Array | No |
List of payment methods to be presented to the shopper. To refer to payment methods, use their payment method type. Example: |
themeId |
String | No |
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. |
shopperEmail |
String | No |
The shopper's email address. |
amount |
Object | Yes |
The payment amount and currency. |
amount.value |
Integer | Yes |
The amount of the transaction, in minor units. |
amount.currency |
String | Yes |
The three-character ISO currency code. |
splitCardFundingSources |
Boolean | No |
Boolean value indicating whether the card payment method should be split into separate debit and credit options. Default value: false |
riskData |
Object | No |
Any risk-related settings to apply to the payment. |
riskData.customFields |
Object | No |
Any custom fields used as part of the input to configured risk rules. |
riskData.profileReference |
String | No |
The risk profile to assign to this payment. When left empty, the merchant-level account's default risk profile will be applied. |
riskData.clientData |
String | No |
Contains client-side data, like the device fingerprint, cookies, and specific browser settings. |
riskData.fraudOffset |
Integer | No |
An integer value that is added to the normal fraud score. The value can be either positive or negative. |
dateOfBirth |
String | No |
The shopper's date of birth. Format ISO-8601: YYYY-MM-DD |
How to start integrating
- Add HTTP Task to your workflow definition.
- Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
- Click Test request to test run your request to the API and see the API's response.