Hosted Checkout

The Hosted Checkout integration redirects the shopper to an Adyen-hosted webpage that handles the complete payment flow for supported payment methods.

Requirements

How it works

For a Hosted Checkout integration, you must integrate the following parts:

• Your payment server: Sends the API request to create a Hosted Checkout payment session.
  • Use the /sessions endpoint on Checkout API v72 or later.
  • Use a server-side library released on March 30, 2026 or later.
• Your webhook server: Listens for webhook messages that include the outcome of each payment.

Integration steps

To integrate Hosted Checkout:

1. Install an API library on your server.
2. Configure the theme for your Hosted Checkout page.
3. Create a payment session.
4. Redirect the shopper to the Hosted Checkout page.
5. Get the payment outcome.

Shopper checkout experience

When the shopper goes to check out:

1. You redirect the shopper to an Adyen-hosted Hosted Checkout page.
2. The shopper completes the payment on the Hosted Checkout page.
3. The shopper gets redirected to your website where you show the result of the payment session.

Payments integration flow

Your website/app, your server and the Hosted Checkout page work together to complete the payment flow:

1. The shopper chooses to go to check out on your website/app.
2. Your website/app triggers your server to create a payment session.
3. Your server makes a POST /sessions request to Adyen, to create a payment session. Adyen returns the URL to the Hosted Checkout page.
4. Your server passes the URL to your website/app.
5. Your website/app redirects the shopper to the Hosted Checkout page.
6. The shopper completes the payment on the Hosted Checkout page.
7. The shopper gets redirected to your website/app with appended session data.
8. Your website/app passes appended session data to your server.
9. Your server makes a GET /sessions/{sessionId} request to Adyen. Adyen returns the result of the payment session.
10. Your server passes the result to your website/app.
11. Your website/app shows the result of the payment session to the shopper.
12. Your webhook server receives webhook message with the payment outcome.

Install an API library

Configure your theme

To create a theme, you must have one of the following user roles:

• Merchant admin
• Hosted Checkout and Pay by Link Settings

To create a new theme:

1. Log in to your Customer Area and switch to your merchant account if necessary.
2. Go to Pay by Link > Themes.
3. Select Create a new theme.
4. Enter a Theme name. This name helps you to identify different themes.
5. Enter a Display name. This name is visible to the shopper on the Hosted Checkout page.
6. Upload a brand logo.
7. If you want this to be the default theme for all Hosted Checkout pages, select Set as default. Available only on the merchant account.
8. Select Create.

Get the theme ID:

1. Go to Pay by Link > Themes.
2. Select the options icon from the theme.
3. Select Copy theme ID.
   This copies the theme ID to your system's clipboard.

Create a payment session

When the shopper goes to checkout, for example by selecting a Checkout button, make a POST /sessions request from your server, including:

Parameter	Required	Description
amount		The currency and value of the payment, in minor units. This is used to filter the list of available payment methods to your shopper.
merchantAccount		Your merchant account name.
returnUrl		URL where to redirect the shopper after they make the payment on the Hosted Checkout page. The URL can contain a maximum of 1024 characters and should include the protocol: http:// or https://. You can also include your own additional query parameters, for example, shopper ID or order reference number. If the URL to return to includes non-ASCII characters, like spaces or special letters, URL encode the value. The URL must not include personally identifiable information (PII), for example name or email address.
reference		Your unique reference for the payment. Minimum length: three characters.
countryCode		The shopper's country/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
shopperEmail		The shopper's email address. Strongly recommended because this field is used in a number of risk checks, and for 3D Secure.
shopperReference		Your unique reference for the shopper. Do not include personally identifiable information (PII), such as name or email address. Format: Minimum length: 3 characters. Case-sensitive. This field is used for the following: Risk checks. When storing the shopper's payment details: associating the token with the shopper.
mode		hosted
themeId		The theme ID of the theme to use for the Hosted Checkout page.

The /sessions response includes the URL (url) for the Hosted Checkout page.

By default, the Hosted Checkout page expires (expiresAt) 1 hour after it was created.

Redirect the shopper to the Hosted Checkout page

Redirect the shopper to the URL (url) from the /sessions response. The shopper pays on the Hosted Checkout page.

When using Hosted Checkout for a mobile browser integration, use SFSafariViewController for iOS or Chrome Custom Tabs for Android, instead of WebView objects. Some payment methods do not function correctly with WebView objects.

Get the payment outcome

After Hosted Checkout finishes the payment flow, you can show the shopper the current payment status. Adyen sends a webhook with the outcome of the payment.

Show the result of the payment session

1. After the shopper makes the payment, they are redirected back to your website.

2. Get the sessionId and sessionResult that is appended to the return URL from the Hosted Checkout page. Use it to get the outcome of the payment session.

3. Make a GET /sessions/{id}?sessionResult={sessionResult} request including the sessionId and sessionResult.

   The response includes the current status (status) of the payment.

   The information included in additionalData depends on the type of payment made.

   Possible statuses:

   status	Description
   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, such as a voucher payment.
   expired	The session expired. The shopper can no longer use the Hosted Checkout page to make a payment.

   The status included in the response does not change. Do not make the request again to check for payment status updates. Instead, check webhooks or the Transactions list in your Customer Area.

Update your order management system

Update your order management system when you get the outcome in a webhook message with eventCode: AUTHORISATION. Use the merchantReference from the webhook to match it to your order reference.

For a successful payment, the event contains success: true.

For an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.

Test and go live

Before going live, use our list of test cards and other payment methods to test your integration. We recommend testing each payment method that you intend to offer to your shoppers.

You can check the test payments in your Customer Area, under Transactions > Payments.

When you are ready to go live, you need to:

1. Apply for a live account.
2. Configure your live account. 
3. Submit a request to add payment methods in your live Customer Area .

4. Switch from test to our live endpoints.

   Make sure that all API requests you make for the same payment session use the same live endpoint region. Using different regions for requests can result in errors.

Troubleshooting

The following information can help your troubleshoot issues with your integration.

Expiration

The Hosted Checkout page expires after:

• The expiresAt from the /sessions response. The default is 1 hour after it was created.
• Our system determines that the shopper made too many payment attempts.

Payment retries

For a payment that encounters an error or fails on a redirect payment method's page, the shopper gets redirected to the Hosted Checkout page to retry the payment.

Payment errors

If the payment encounters an error, the shopper can retry the payment on the Hosted Checkout page. We send you a webhook message for each payment attempt. So, we can send you more than one webhook message that includes the same sessionId.

Supported payment methods

• ACH Direct Debit
• Affirm
• Afterpay
• Alipay
• AlipayHK
• Apple Pay
• Atome
• BACS Direct Debit
• Bancontact Card
• Bancontact Mobile (Payconiq)
• Benefit
• BLIK
• Boleto Bancário
• Cards, including 3D Secure 1 and 3D Secure 2 authentication
• Clearpay
• Credit card installments
• Stored card details
• DANA
• Dragonpay
• EPS
• Fawry
• GCash
• Gift cards
• Google Pay
• GrabPay
• iDEAL
• Indonesian bank transfers and convenience stores
• Japanese convenience stores (Konbini)/
  7-Eleven Japan
• KakaoPay
• Klarna
• KNET
• MB WAY
• MobilePay
• MOLPay
• MoMo
• Multibanco
• Oney 3x4x
• Online banking Finland
• Online banking India
• Online banking Japan
• Online banking Poland
• Napas card
• OXXO
• PayBright
• PayPal
• Paytm
• PayU
• Pix
• Ratepay
• SEPA Direct Debit
• Sofort
• Swish
• Trustly
• TWINT
• Vipps
• Wallets India
• WeChat Pay
• Zip

Next steps