Manage your Hosted Payments Page

Last updated: December 18, 2024

On this page, find out how to:

Have you registered to begin using Hosted Payments Page? Contact your Solution Engineer or [email protected]. During integration, you'll be able to specify your payment capture and 3D Secure settings.
Create your secret and public API keys in the Dashboard.
Set up webhooks to be notified when the payment has been approved, so you can continue the sales fulfillment flow.

When a customer purchases something from you, you can create a Hosted Payments Page session by using the

post

/hosted-payments endpoint and providing us with details of the purchase.

To get a detailed view of all required and optional fields, see our API reference.

Note

Checkout.com does not support Hosted Payments Pages embedded within an iframe.

If you've enabled Remember Me to let customers save and reuse their details for faster checkout:

To display Remember Me on the checkout screen, you must provide the display_name and customer.email fields in the request
To help with profile creation and retrieval, request a phone number from the customer and provide it in the customer.phone field

Note

http://localhost/ can only be used for the URL fields during testing and will not work in production.

post

https://api.checkout.com/hosted-payments

Some payment methods may require you to provide additional fields or specific values when you perform a payment request. Refer to the API reference for more details.

Payment method	Field requirements
Card payments	No additional requirements.
Apple Pay	Apple Pay is processed as a card transaction.
Google Pay	Google Pay is processed as a card transaction.
Alipay CN	`customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `CN`, for China `currency` value must be one of: `CNY` `HKD` `SGD`
Alipay HK	`customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `HK`, for Hong Kong `currency` value must be one of: `HKD` `SGD`
Alma	`billing.address.country` value must be `FR`, for France `currency` value must be `EUR`
Bancontact	`customer.name` must be provided `billing.address.country` value must be `BE`, for Belgium `currency` value must be `EUR`
Benefit Payment Gateway	`billing.address.country` value must be `BH`, for Bahrain `currency` value must be `BHD` `reference` must be provided
Dana	`customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `ID`, for Indonesia `currency` value must be one of: `IDR` `HKD` `SGD`
EPS	`billing.address.country` value must be `AT`, for Austria `currency` value must be `EUR`
GCash	`customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `PH`, for the Philippines `currency` value must be one of: `PHP` `HKD` `SGD`
iDEAL	`billing.address.country` value must be `NL`, for Netherlands `currency` value must be `EUR`
Kakao Pay	`customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `KR`, for South Korea `currency` value must be one of: `KRW` `HKD` `SGD`
Klarna	`products[]` must be provided `customer.name` must be provided `billing.address.country` value must be one of: `AT`, for Austria `AU`, for Australia `BE`, for Belgium `CH`, for Switzerland `CZ`, for Czech Republic `DE`, for Germany `DK`, for Denmark `ES`, for Spain `FR`, for France `FI`, for Finland `GB`, for United Kingdom `GR`, for Greece `IE`, for Ireland `IT`, for Italy `NL`, for Netherlands `NO`, for Norway `PL`, for Poland `PT`, for Portugal `SE`, for Sweden `currency` value must be one of: `AUD` `CHF` `CZK` `DKK` `EUR` `GBP` `NOK` `PLN`
KNET	`billing.address.country` value must be `KW`, for Kuwait `currency` value must be `KWD` `locale` value must be `ar` – if no value is provided, the `en-GB` locale is used by default
MB WAY	`billing.address.country` value must be `PT`, for Portugal `currency` value must be `EUR` `reference` must be provided
Multibanco	`customer.name` must be provided `billing.address.country` value must be `PT`, for Portugal `currency` value must be `EUR`
Przelewy24	`customer.name` must be provided `customer.email` must be provided `billing.address.country` value must be `PL`, for Poland `currency` value must be `EUR` or `PLN`
QPay	`billing.address.country` value must be `QA`, for Qatar `currency` value must be `QAR` `description` must be provided
SEPA Direct Debit	`billing.address.country` value must be set to a country in the Single Euro Payments Area (SEPA) `currency` value must be `EUR`
stc pay	`billing.address.country` must be set to `SA` `currency` value must be `SAR` `reference` must be provided
Touch 'n Go	`customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `MY`, for Malaysia `currency` value must be one of: `MYR` `HKD` `SGD`
TrueMoney	`customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `TH`, for Thailand `currency` value must be one of: `THB` `HKD` `SGD`
Venmo	`billing.address.country` must be `US`, for the United States `currency` value must be `USD`


1{
2  "amount": 1000,
3  "currency": "GBP",
4  "reference": "ORD-123A",
5  "billing": {
6    "address": {
7      "country": "GB"
8    }
9  },
10  "customer": {
11    "name": "John Smith",
12    "email": "[email protected]"
13  },
14  "success_url": "https://example.com/payments/success",
15  "failure_url": "https://example.com/payments/failure",
16  "cancel_url": "https://example.com/payments/cancel"
17}

The response will include the redirect link to which you should redirect your customer to finalize the payment.


1{
2  "id": "hpp_xGQBg0AXl3cM",
3  "reference": "ORD-123A",
4  "_links": {
5    "self": {
6      "href": "https://api.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
7    },
8    "redirect": {
9      "href": "https://pay.checkout.com/page/hpp_xGQBg0AXl3cM"
10    }
11  }
12}

Redirect the customer to the _links.redirect URL you received in the response above, using either a server-side or client-side call.


1res.redirect(hostedPaymentsResponse._links.redirect.href);


1window.location.href(hostedPaymentsResponse._links.redirect.href);

When your customer completes the payment, they will be redirected to the success URL. The session ID (cko-session-id) or payment ID (cko-payment-id) is provided in the query parameter included in the redirect URL. It will look something this:

https://example.com/success?cko-session-id=sid_ubj2q76miwundwlk72vxt2i7
https://example.com/success?cko-payment-id=pay_mbabizu24mvu3mela5njyhpit4

You can set up webhooks to be notified when the payment has been approved, so you can continue the sales fulfillment flow.

To keep track of the payments you request as a Hosted Payments Page, you can check the status using the id returned when you created the session. It will look like hpp_xGQBg0AXl3cM.

There are three statuses:

Payment Pending: The Hosted Payments Page can accept a payment from the customer. A payment may have been attempted by the customer but not completed successfully.
Payment Received: A payment has been received successfully using this Hosted Payments Page.
Expired: The Hosted Payments Page has expired and can no longer be accessed.

For a full explanation of the fields, see our API reference.

get

https://api.checkout.com/hosted-payments/{id}


1{
2  "id": "hpp_xGQBg0AXl3cM",
3  "status": "Payment Pending",
4  "payment_id": "undefined",
5  "amount": 200,
6  "currency": "GBP",
7  "reference": "ORD-123A",
8  "description": "Payment for Gold Necklace",
9  "expires_on": "2021-08-20T20:25:28+08:00",
10  "customer": {
11    "name": "John Smith",
12    "email": "[email protected]"
13  },
14  "billing": {
15    "address": {
16      "address_line1": "123 High St.",
17      "address_line2": "Flat 456",
18      "city": "London",
19      "zip": "SW1A 1AA",
20      "country": "GB"
21    },
22    "phone": {
23      "country_code": "+44",
24      "number": "1234567890"
25    }
26  },
27  "products": [
28    {
29      "name": "Gold Necklace",
30      "quantity": 1,
31      "price": 200
32    }
33  ],
34  "_links": {
35    "self": {
36      "href": "https://api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
37    },
38    "redirect": {
39      "href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
40    }
41  }
42}


1{
2  "id": "hpp_xGQBg0AXl3cM",
3  "status": "Payment Received",
4  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
5  "amount": 200,
6  "currency": "GBP",
7  "reference": "ORD-123A",
8  "description": "Payment for Gold Necklace",
9  "expires_on": "2021-08-20T20:25:28+08:00",
10  "customer": {
11    "name": "John Smith",
12    "email": "[email protected]"
13  },
14  "billing": {
15    "address": {
16      "address_line1": "123 High St.",
17      "address_line2": "Flat 456",
18      "city": "London",
19      "zip": "SW1A 1AA",
20      "country": "GB"
21    },
22    "phone": {
23      "country_code": "+44",
24      "number": "1234567890"
25    }
26  },
27  "products": [
28    {
29      "name": "Gold Necklace",
30      "quantity": 1,
31      "price": 200
32    }
33  ],
34  "_links": {
35    "self": {
36      "href": "https://api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
37    },
38    "redirect": {
39      "href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
40    },
41    "payment": {
42      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
43    },
44    "payment_actions": {
45      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
46    }
47  }
48}


1{
2  "id": "hpp_xGQBg0AXl3cM",
3  "status": "Expired",
4  "payment_id": "undefined",
5  "amount": 200,
6  "currency": "GBP",
7  "reference": "ORD-123A",
8  "description": "Payment for Gold Necklace",
9  "expires_on": "2021-08-20T20:25:28+08:00",
10  "customer": {
11    "name": "John Smith",
12    "email": "[email protected]"
13  },
14  "billing": {
15    "address": {
16      "address_line1": "123 High St.",
17      "address_line2": "Flat 456",
18      "city": "London",
19      "zip": "SW1A 1AA",
20      "country": "GB"
21    },
22    "phone": {
23      "country_code": "+44",
24      "number": "1234567890"
25    }
26  },
27  "products": [
28    {
29      "name": "Gold Necklace",
30      "quantity": 1,
31      "price": 200
32    }
33  ],
34  "_links": {
35    "self": {
36      "href": "https://api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
37    },
38    "redirect": {
39      "href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
40    }
41  }
42}

Customize your Hosted Payments Page

Find out how your Hosted Payments Page can be customized.

Manage your Hosted Payments Page

Before you begin

Create a Hosted Payments Page

Step 1: Create a new Hosted Payments Page

Note

Endpoints

Note

Payment method field requirements

Request example

Response example

Step 2: Redirect your customer

Step 3: Confirm the payment status

Check the status of a Hosted Payments Page

Endpoints

Response examples

Next steps

Customize your Hosted Payments Page