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

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.

Required for the US and Canada.

fundOrigin.billingAddress.country String Yes

The two-character ISO-3166-1 alpha-2 country code. For example, US.

If you don't know the country or are not collecting the country from the shopper, provide country as ZZ.

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.

The house number should not be included in this field; it should be separately provided via houseNumberOrName.

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:

  • 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.
shopperReference String No

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.

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:

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

Possible values:

  • "askForConsent"
  • "disabled"
  • "enabled"
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:

  • 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.
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, en-US.

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: "blockedPaymentMethods":["ideal","giropay"]

recurringProcessingModel String No

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.

Possible values:

  • "CardOnFile"
  • "Subscription"
  • "UnscheduledCardOnFile"
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 type is MarketPlace or BalanceAccount.

  • Classic Platforms integration: The accountCode of the account to which the split amount is booked.
  • Balance Platform: The balanceAccountId of the account to which the split amount is booked.
splits[].description String No

Your description for the split item.

splits[].amount Object No

The amount of the split item.

  • Required for all split types in the Classic Platforms integration.
  • Required if type is BalanceAccount, Commission, Default, or VAT in your Balance Platform integration.
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 account.

Possible values for the Balance Platform:

  • BalanceAccount: books part of the payment (specified in amount) to the specified account.
  • Transaction fees types that you can book to the specified account:
    • AcquiringFees: the aggregated amount of the interchange and scheme fees.
    • PaymentFee: the aggregated amount of all transaction fees.
    • AdyenFees: the aggregated amount of Adyen's commission and markup fees.
    • AdyenCommission: the transaction fees due to Adyen under blended rates.
    • AdyenMarkup: the transaction fees due to Adyen under Interchange ++ pricing.
    • Interchange: the fees paid to the issuer for each payment made with the card network.
    • SchemeFee: the fees paid to the card scheme for using their network.
  • Commission: your platform's commission on the payment (specified in amount), booked to your liable balance account.
  • Remainder: the amount left over after a currency conversion, booked to the specified account.
  • TopUp: allows you and your users to top up balance accounts using direct debit, card payments, or other payment methods.
  • VAT: the value-added tax charged on the payment, booked to your platforms liable balance account.
  • Commission: your platform's commission (specified in amount) on the payment, booked to your liable balance account.
  • Default: in very specific use cases, allows you to book the specified amount to the specified account. For more information, contact Adyen support.

Possible values for the Classic Platforms integration: Commission, Default, MarketPlace, PaymentFee, VAT.

Possible values:

  • "MarketPlace"
  • "SchemeFee"
  • "Surcharge"
  • "Commission"
  • "PaymentFee"
  • "AdyenCommission"
  • "Tip"
  • "AdyenMarkup"
  • "Remainder"
  • "Interchange"
  • "AcquiringFees"
  • "AdyenFees"
  • "BalanceAccount"
  • "Default"
  • "VAT"
splits[].reference String No

Your unique reference for the part of the payment booked to the specified account.

This is required if type is MarketPlace (Classic Platforms integration) or BalanceAccount (Balance Platform).

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 behavior is deductFromOneBalanceAccount.

platformChargebackLogic.behavior String No

The method of handling the chargeback.

Possible values: deductFromLiableAccount, deductFromOneBalanceAccount, deductAccordingToSplitRatio.

Possible values:

  • "deductAccordingToSplitRatio"
  • "deductFromOneBalanceAccount"
  • "deductFromLiableAccount"
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.

Required for the US and Canada.

deliveryAddress.country String Yes

The two-character ISO-3166-1 alpha-2 country code. For example, US.

If you don't know the country or are not collecting the country from the shopper, provide country as ZZ.

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.

The house number should not be included in this field; it should be separately provided via houseNumberOrName.

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:

  • "transferOwnWallet"
  • "transferDifferentWallet"
  • "transferSameWallet"
  • "unidentifiedBoleto"
  • "identifiedBoleto"
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:

  • "credit"
  • "debit"
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 networkTxReference from the response to the first payment.

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 recurringDetailReference returned in the response when you created the token.

fundRecipient.paymentMethod.cupsecureplus.smscode String No
fundRecipient.paymentMethod.shopperNotificationReference String No

The shopperNotificationReference returned in the response when you requested to notify the shopper. Used only for recurring payments in India.

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:

  • "bcmc"
  • "giftcard"
  • "card"
  • "scheme"
  • "networkToken"

Default value: "scheme"

fundRecipient.paymentMethod.storedPaymentMethodId String No

This is the recurringDetailReference returned in the response when you created the token.

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.

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

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

  • Format: Numeric
  • Fixed length: 4 digits
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.

  • Format: Alphanumeric
  • Maximum length: 22 characters
fundRecipient.subMerchant.taxId String No

The tax ID of the sub-merchant.

  • Format: Numeric
  • Fixed length: 11 digits for the CPF or 14 digits for the CNPJ
fundRecipient.subMerchant.country String No

The three-letter country code of the sub-merchant's address. For example, BRA for Brazil.

  • Format: ISO 3166-1 alpha-3
  • Fixed length: 3 characters
fundRecipient.subMerchant.city String No

The city of the sub-merchant's address.

  • Format: Alphanumeric
  • Maximum length: 13 characters
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.

Required for the US and Canada.

fundRecipient.billingAddress.country String Yes

The two-character ISO-3166-1 alpha-2 country code. For example, US.

If you don't know the country or are not collecting the country from the shopper, provide country as ZZ.

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.

The house number should not be included in this field; it should be separately provided via houseNumberOrName.

fundRecipient.billingAddress.city String Yes

The name of the city. Maximum length: 3000 characters.

fundRecipient.storedPaymentMethodId String No

This is the recurringDetailReference returned in the response when you created the token.

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:

  • 01 — No preference
  • 02 — No challenge requested
  • 03 — Challenge requested (3DS Requestor preference)
  • 04 — Challenge requested (Mandate)
  • 05 — No challenge (transactional risk analysis is already performed)
  • 06 — Data Only

Possible values:

  • "06"
  • "05"
  • "04"
  • "03"
  • "02"
  • "01"
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.

Required for the US and Canada.

billingAddress.country String Yes

The two-character ISO-3166-1 alpha-2 country code. For example, US.

If you don't know the country or are not collecting the country from the shopper, provide country as ZZ.

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.

The house number should not be included in this field; it should be separately provided via houseNumberOrName.

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: "allowedPaymentMethods":["ideal","giropay"]

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

  1. Add HTTP Task to your workflow definition.
  2. 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.
  3. Click Test request to test run your request to the API and see the API's response.