Update the status of a payment link

patch/paymentLinks/{linkId}

Updates the status of a payment link. Use this endpoint to force the expiry of a payment link.

Endpoint destination URL

https://checkout-test.adyen.com/v52/paymentLinks/{linkId}

Path Parameters

Required

Optional

Unique identifier of the payment link.

Request Parameters

Required

Optional

Status of the payment link. Possible values:

expired

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 less
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"]
amountobject
The payment amount and currency.
Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
applicationInfoobject
Information about your application. For more details, see Building Adyen solutions.
Show children Hide children
adyenLibraryobject
Adyen-developed software, such as libraries and plugins, used to interact with the Adyen API. For example, Magento plugin, Java API library, etc.
Show children Hide children
namestring
Name of the field. For example, Name of External Platform.
versionstring
Version of the field. For example, Version of External Platform.
adyenPaymentSourceobject
Adyen-developed software to get payment details. For example, Checkout SDK, Secured Fields SDK, etc.
Show children Hide children
namestring
Name of the field. For example, Name of External Platform.
versionstring
Version of the field. For example, Version of External Platform.
externalPlatformobject
Third-party developed platform used to initiate payment requests. For example, Magento, Zuora, etc.
Show children Hide children
integratorstring
External platform integrator.
namestring
Name of the field. For example, Name of External Platform.
versionstring
Version of the field. For example, Version of External Platform.
merchantApplicationobject
Merchant developed software, such as cashier application, used to interact with the Adyen API.
Show children Hide children
namestring
Name of the field. For example, Name of External Platform.
versionstring
Version of the field. For example, Version of External Platform.
merchantDeviceobject
Merchant device information.
Show children Hide children
osstring
Operating system running on the merchant device.
osVersionstring
Version of the operating system on the merchant device.
referencestring
Merchant device reference.
shopperInteractionDeviceobject
Shopper interaction device, such as terminal, mobile device or web browser, to initiate payment requests.
Show children Hide children
localestring
Locale on the shopper interaction device.
osstring
Operating system running on the shopper interaction device.
osVersionstring
Version of the operating system on the shopper interaction device.
billingAddressobject
The address where to send the invoice.
Show children Hide children
citystring
Max length: 3000
The name of the city. Maximum length: 3000 characters.
countrystring
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.

houseNumberOrNamestring
Max length: 3000
The number or name of the house. Maximum length: 3000 characters.
postalCodestring
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
stateOrProvincestring
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.

streetstring
Max length: 3000
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.

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"]
countryCodestring
Max length: 100
The shopper's two-letter country code.
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.
Show children Hide children
citystring
Max length: 3000
The name of the city. Maximum length: 3000 characters.
countrystring
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.

houseNumberOrNamestring
Max length: 3000
The number or name of the house. Maximum length: 3000 characters.
postalCodestring
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
stateOrProvincestring
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.

streetstring
Max length: 3000
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.

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.
Show children Hide children
billingAddressobject
The address where to send the invoice.
Show children Hide children
citystring
Max length: 3000
The name of the city. Maximum length: 3000 characters.
countrystring
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.

houseNumberOrNamestring
Max length: 3000
The number or name of the house. Maximum length: 3000 characters.
postalCodestring
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
stateOrProvincestring
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.

streetstring
Max length: 3000
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.

shopperEmailstring
The email address of the person funding the money.
shopperNameobject
The name of the person funding the money.
Show children Hide children
firstNamestring
Max length: 80
The first name.
lastNamestring
Max length: 80
The last name.
telephoneNumberstring
The phone number of the person funding the money.
walletIdentifierstring
The unique identifier of the wallet where the funds are coming from.
fundRecipientobject
the person or entity receiving the money
Show children Hide children
IBANstring
The IBAN of the bank account where the funds are being transferred to.
billingAddressobject
The address where to send the invoice.
Show children Hide children
citystring
Max length: 3000
The name of the city. Maximum length: 3000 characters.
countrystring
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.

houseNumberOrNamestring
Max length: 3000
The number or name of the house. Maximum length: 3000 characters.
postalCodestring
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
stateOrProvincestring
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.

streetstring
Max length: 3000
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.

paymentMethodobject
The payment method used by the shopper.
Show children Hide children
brandstring
Secondary brand of the card. For example: plastix, hmclub.
cupsecureplus.smscodestringDeprecated
cvcstring
The card verification code. Only collect raw card data if you are fully PCI compliant.
encryptedCardstring
Max length: 40000
Only include this for JSON Web Encryption (JWE) implementations. The JWE-encrypted card details.
encryptedCardNumberstring
Max length: 15000
The encrypted card number.
encryptedExpiryMonthstring
Max length: 15000
The encrypted card expiry month.
encryptedExpiryYearstring
Max length: 15000
The encrypted card expiry year.
encryptedSecurityCodestring
Max length: 15000
The encrypted card verification code.
expiryMonthstring
The card expiry month. Only collect raw card data if you are fully PCI compliant.
expiryYearstring
The card expiry year. Only collect raw card data if you are fully PCI compliant.
fundingSourcestring
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.
holderNamestring
Max length: 15000
The name of the card holder.
networkPaymentReferencestring
The transaction identifier from card schemes. This is the networkTxReference from the response to the first payment.
numberstring
The card number. Only collect raw card data if you are fully PCI compliant.
recurringDetailReferencestringDeprecated in version 49
Use storedPaymentMethodId instead.
This is the recurringDetailReference returned in the response when you created the token.
shopperNotificationReferencestring
The shopperNotificationReference returned in the response when you requested to notify the shopper. Used only for recurring payments in India.
srcCorrelationIdstring
An identifier used for the Click to Pay transaction.
srcDigitalCardIdstring
The SRC reference for the Click to Pay token.
srcSchemestring
The scheme that is being used for Click to Pay.
srcTokenReferencestring
The reference for the Click to Pay token.
storedPaymentMethodIdstring
Max length: 64
This is the recurringDetailReference returned in the response when you created the token.
threeDS2SdkVersionstring
Max length: 12
Required for mobile integrations. Version of the 3D Secure 2 mobile SDK.
typestring
Default payment method details. Common for scheme payment methods, and for simple payment method details.
shopperEmailstring
The email address of the shopper.
shopperNameobject
The name of the shopper.
Show children Hide children
firstNamestring
Max length: 80
The first name.
lastNamestring
Max length: 80
The last name.
shopperReferencestring
Min length: 3Max length: 256
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.

storedPaymentMethodIdstring
Max length: 64
This is the recurringDetailReference returned in the response when you created the token.
subMerchantobject
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.
Show children Hide children
citystring
The city of the sub-merchant's address.

Format: Alphanumeric

Maximum length: 13 characters

countrystring
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

mccstring
The sub-merchant's 4-digit Merchant Category Code (MCC).

Format: Numeric

Fixed length: 4 digits

namestring
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

taxIdstring
The tax ID of the sub-merchant.

Format: Numeric

Fixed length: 11 digits for the CPF or 14 digits for the CNPJ

telephoneNumberstring
The telephone number of the shopper.
walletIdentifierstring
The unique identifier for the wallet the funds are being transferred to. You can use the shopper reference or any other identifier.
walletOwnerTaxIdstring
The tax identifier of the person receiving the funds.
walletPurposestring
The purpose of a digital wallet transaction.
idstring
A unique identifier of the payment link.
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.
Show children Hide children
maxValueinteger
The maximum number of installments offered for this payment method.
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.
Show children Hide children
amountExcludingTaxinteger
Item amount excluding the tax, in minor units.
amountIncludingTaxinteger
Item amount including the tax, in minor units.
descriptionstring
Max length: 10000
Description of the line item.
idstring
ID of the line item.
imageUrlstring
Link to the picture of the purchased item.
itemCategorystring
Item category, used by the payment methods PayPal and Ratepay.
productUrlstring
Link to the purchased item.
quantityinteger
Number of items.
taxAmountinteger
Tax amount, in minor units.
taxPercentageinteger
Tax percentage, in minor units.
manualCaptureboolean
Indicates if the payment must be captured manually.
merchantAccountstring
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.
Show children Hide children
behaviorstring
The method of handling the chargeback.

Possible values: deductFromLiableAccount, deductFromOneBalanceAccount, deductAccordingToSplitRatio.
costAllocationAccountstring
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.
targetAccountstring
The unique identifier of the balance account against which the disputed amount is booked.

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

referencestring
A reference that is used to uniquely identify the payment in future communications about the payment status.
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.
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.
Show children Hide children
firstNamestring
Max length: 80
The first name.
lastNamestring
Max length: 80
The last name.
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.

showRemovePaymentMethodButtonboolean
Set 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.
Show children Hide children
accountstring
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.

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

Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code. By default, this is the original payment currency.
valueinteger
The value of the split amount, in minor units.
descriptionstring
Your description for the split item.
referencestring
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.
typestring
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.
statusstring
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.

paid: The shopper completed the payment.

storestring
The physical store, for which this payment is processed.
storePaymentMethodboolean
When this is set to true and the shopperReference is provided, the payment details will be stored.
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.
Show children Hide children
homePhoneobject
The home phone number provided by the Cardholder.
Show children Hide children
ccstring
Min length: 1Max length: 3
Country code. Length: 1–3 characters.
subscriberstring
Max length: 15
Subscriber number. Maximum length: 15 characters.
mobilePhoneobject
The mobile phone number provided by the Cardholder.
Show children Hide children
ccstring
Min length: 1Max length: 3
Country code. Length: 1–3 characters.
subscriberstring
Max length: 15
Subscriber number. Maximum length: 15 characters.
threeDSRequestorChallengeIndstring
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

workPhoneobject
The work phone number provided by the Cardholder.
Show children Hide children
ccstring
Min length: 1Max length: 3
Country code. Length: 1–3 characters.
subscriberstring
Max length: 15
Subscriber number. Maximum length: 15 characters.
updatedAtstring
The 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.
urlstring
The URL at which the shopper can complete the payment.
400 - Bad Request
A problem reading or understanding the request.
Show more Show less
additionalDataobject
Contains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
401 - Unauthorized
Authentication required.
Show more Show less
additionalDataobject
Contains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
403 - Forbidden
Insufficient permissions to process the request.
Show more Show less
additionalDataobject
Contains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
422 - Unprocessable Entity
A request validation error.
Show more Show less
additionalDataobject
Contains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
500 - Internal Server Error
The server could not process the request.
Show more Show less
additionalDataobject
Contains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.

Update the status of a payment link

Path Parameters

Request Parameters

Response parameters

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error