Get a payment link
Retrieves the payment link details using the payment link id
.
Path Parameters
Unique identifier of the payment link.
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
200 - OK
The request has succeeded.
Show moreShow lessallowedPaymentMethodsarray[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"]
amountobjectThe payment amount and currency.
valueintegerThe amount of the transaction, in minor units.
applicationInfoobjectInformation about your application. For more details, see Building Adyen solutions.
adyenLibraryobjectAdyen-developed software, such as libraries and plugins, used to interact with the Adyen API. For example, Magento plugin, Java API library, etc.
namestringName of the field. For example, Name of External Platform.
versionstringVersion of the field. For example, Version of External Platform.
adyenPaymentSourceobjectAdyen-developed software to get payment details. For example, Checkout SDK, Secured Fields SDK, etc.
namestringName of the field. For example, Name of External Platform.
versionstringVersion of the field. For example, Version of External Platform.
externalPlatformobjectThird-party developed platform used to initiate payment requests. For example, Magento, Zuora, etc.
integratorstringExternal platform integrator.
namestringName of the field. For example, Name of External Platform.
versionstringVersion of the field. For example, Version of External Platform.
merchantApplicationobjectMerchant developed software, such as cashier application, used to interact with the Adyen API.
namestringName of the field. For example, Name of External Platform.
versionstringVersion of the field. For example, Version of External Platform.
merchantDeviceobjectMerchant device information.
osstringOperating system running on the merchant device.
osVersionstringVersion of the operating system on the merchant device.
referencestringMerchant device reference.
shopperInteractionDeviceobjectShopper interaction device, such as terminal, mobile device or web browser, to initiate payment requests.
localestringLocale on the shopper interaction device.
osstringOperating system running on the shopper interaction device.
osVersionstringVersion of the operating system on the shopper interaction device.
billingAddressobjectThe address where to send the invoice.
citystringMax length: 3000The name of the city. Maximum length: 3000 characters.
countrystringThe 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
asZZ
.houseNumberOrNamestringMax length: 3000The number or name of the house. Maximum length: 3000 characters.
postalCodestringA maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
stateOrProvincestringThe 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.
streetstringMax length: 3000The 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
.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"]
countryCodestringThe shopper's two-letter country code.
deliverAtstringThe 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.
deliveryAddressobjectThe address where the purchased goods should be delivered.
citystringMax length: 3000The name of the city. Maximum length: 3000 characters.
countrystringThe 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
asZZ
.houseNumberOrNamestringMax length: 3000The number or name of the house. Maximum length: 3000 characters.
postalCodestringA maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
stateOrProvincestringThe 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.
streetstringMax length: 3000The 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
.descriptionstringA short description visible on the payment page. Maximum length: 280 characters.
expiresAtstringThe 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.
idstringA unique identifier of the payment link.
installmentOptionsobjectA 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.
maxValueintegerThe maximum number of installments offered for this payment method.
plansarray[string]Defines the type of installment plan. If not set, defaults to regular.
Possible values:
- regular
- revolving
preselectedValueintegerPreselected number of installments offered for this payment method.
valuesarray[integer]An array of the number of installments that the shopper can choose from. For example, [2,3,5]. This cannot be specified simultaneously with
maxValue
.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, and Zip.
amountExcludingTaxintegerItem amount excluding the tax, in minor units.
amountIncludingTaxintegerItem amount including the tax, in minor units.
descriptionstringDescription of the line item.
idstringID of the line item.
imageUrlstringLink to the picture of the purchased item.
itemCategorystringItem category, used by the payment methods PayPal and Ratepay.
productUrlstringLink to the purchased item.
quantityintegerNumber of items.
taxAmountintegerTax amount, in minor units.
taxPercentageintegerTax percentage, in minor units.
manualCapturebooleanIndicates if the payment must be captured manually.
merchantAccountstringThe merchant account identifier for which the payment link is created.
merchantOrderReferencestringThis reference allows linking multiple transactions to each other for reporting purposes (for example, order auth-rate). The reference should be unique per billing cycle.
metadataobjectMax length: 80Metadata 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.
recurringProcessingModelstringDefines 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.
referencestringA 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.
returnUrlstringWebsite 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.
reusablebooleanIndicates 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.
riskDataobjectAny risk-related settings to apply to the payment.
clientDatastringContains client-side data, like the device fingerprint, cookies, and specific browser settings.
customFieldsobjectAny custom fields used as part of the input to configured risk rules.
fraudOffsetintegerAn integer value that is added to the normal fraud score. The value can be either positive or negative.
profileReferencestringThe risk profile to assign to this payment. When left empty, the merchant-level account's default risk profile will be applied.
shopperEmailstringThe shopper's email address.
shopperLocalestringThe 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.
shopperNameobjectThe 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.
firstNamestringThe first name.
lastNamestringThe last name.
shopperReferencestringMin length: 3Max length: 256Your 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.
showRemovePaymentMethodButtonbooleanSet to false to hide the button that lets the shopper remove a stored payment method.
splitsarray[object]An array of objects specifying how to split a payment when using Adyen for Platforms, Classic Platforms integration, or Issuing.
accountstringThe 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.
amountobjectThe 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.
currencystringMin length: 3Max length: 3The three-character ISO currency code. By default, this is the original payment currency.
valueintegerThe value of the split amount, in minor units.
descriptionstringYour description for the split item.
referencestringYour unique reference for the split item.
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.
typestringThe type of the split item.
Possible values:
- Classic Platforms integration: Commission, Default, Marketplace, PaymentFee, VAT.
- Balance Platform: BalanceAccount, Commission, Default, PaymentFee, Remainder, Surcharge, Tip, VAT.
statusstringStatus 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.
storestringThe physical store, for which this payment is processed.
storePaymentMethodModestringIndicates 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 therecurringProcessingModel
parameter.
telephoneNumberstringThe shopper's telephone number.
themeIdstringA 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.
updatedAtstringThe date when the payment link status was updated.
ISO 8601 format: YYYY-MM-DDThh:mm:ss+TZD, for example, 2020-12-18T10:15:30+01:00.
urlstringThe URL at which the shopper can complete the payment.
400 - Bad Request
A problem reading or understanding the request.
Show moreShow lessadditionalDataobjectContains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestringThe error code mapped to the error message.
errorTypestringThe category of the error.
messagestringA short explanation of the issue.
pspReferencestringThe PSP reference of the payment.
statusintegerThe HTTP response status.
401 - Unauthorized
Authentication required.
Show moreShow lessadditionalDataobjectContains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestringThe error code mapped to the error message.
errorTypestringThe category of the error.
messagestringA short explanation of the issue.
pspReferencestringThe PSP reference of the payment.
statusintegerThe HTTP response status.
403 - Forbidden
Insufficient permissions to process the request.
Show moreShow lessadditionalDataobjectContains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestringThe error code mapped to the error message.
errorTypestringThe category of the error.
messagestringA short explanation of the issue.
pspReferencestringThe PSP reference of the payment.
statusintegerThe HTTP response status.
422 - Unprocessable Entity
A request validation error.
Show moreShow lessadditionalDataobjectContains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestringThe error code mapped to the error message.
errorTypestringThe category of the error.
messagestringA short explanation of the issue.
pspReferencestringThe PSP reference of the payment.
statusintegerThe HTTP response status.
500 - Internal Server Error
The server could not process the request.
Show moreShow lessadditionalDataobjectContains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestringThe error code mapped to the error message.
errorTypestringThe category of the error.
messagestringA short explanation of the issue.
pspReferencestringThe PSP reference of the payment.
statusintegerThe HTTP response status.