# Manage your Hosted Payments Page On this page, find out how to: - [Create a Hosted Payments Page](#Create_a_Hosted_Payments_Page). - [Check the status of a Hosted Payments Page](#Check_the_status_of_a_Hosted_Payments_Page). --- ## Before you start - Make sure you've registered to begin using Hosted Payments Page. Contact your Solution Engineer or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). During integration, you can specify your payment capture and 3D Secure settings. - Create your [secret and public API keys](https://www.checkout.com/docs/resources/api-authentication/api-keys.md) in the Dashboard. - [Configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md) to be notified when the payment is approved, so you can continue the sales fulfillment flow. --- ## Create a Hosted Payments Page ### Step 1: Create a new Hosted Payments Page 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 the [API reference](https://api-reference.checkout.com/#tag/Hosted-Payments-Page). > **Note** > > Checkout.com does not support Hosted Payments Pages embedded within an iframe. > **Information** > > You can [enable Remember Me](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/enable-remember-me.md) to allow customers to save their card details during checkout. The next time the customer shops at any merchant that has Remember Me enabled, we display their saved card details. ### Endpoints > **Note** > > http://localhost/ can only be used for the URL fields during testing and does not work in production. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/hosted-payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/hosted-payments` ### Payment method field requirements Some payment methods may require you to provide additional fields or specific values when you perform a payment request. Refer to the [API reference](https://api-reference.checkout.com/tag/Hosted-Payments-Page/#operation/createAHostedPaymentsSession) for more details. | Payment method | Field requirements | | --- | --- | | Card payments | No additional requirements. | | Apple Pay | - Apple Pay is processed as a card transaction.
- `currency` and `billing.address.country` must be [supported by Apple Pay](https://support.apple.com/en-gb/102775). | | Google Pay | - Google Pay is processed as a card transaction.
- `currency` and `billing.address.country` must be [supported by Google Pay](https://support.google.com/googlepay/answer/12429287?hl=en-GB). | | AlipayCN | - `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` | | AlipayHK | - `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` | | Bacs | - `billing.address.country` value must be `GB`, for the United Kingdom
- `currency` value must be `GBP`
- `payment_type` must be set to `Regular` or `Recurring`
- `amount` must be provided | | 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 | | Bizum | - `billing.address.country` value must be `ES`, for Spain
- `currency` value must be `EUR` | | BLIK | - `billing.address.country` value must be `PL`, for Poland
- `currency` value must be `PLN`
- `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
- `US` for United States




- `currency` value must be one of:
- `AUD`
- `CHF`
- `CZK`
- `DKK`
- `EUR`
- `GBP`
- `NOK`
- `PLN`
- `SEK`
- `USD` | | 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 | | MobilePay | - `billing.address.country` value must be one of:
- `DK` for Denmark
- `FI` for Finland
- `currency` value must be one of:
- `EUR`
- `DKK` | | Multibanco | - `customer.name` must be provided
- `billing.address.country` value must be `PT`, for Portugal
- `currency` value must be `EUR` | | Octopus | - `billing.address.country` value must be `HK`, for Hong Kong
- `currency` value must be `HKD`
- `payment_type` must be set to `Regular` | | PayNow | - `billing.address.country` value must be `SG`, for Singapore
- `currency` value must be `SGD`
- `payment_type` must be set to `Regular` | | PayPal | - `products[]` must be provided
- `currency` and `billing.address.country` must be [supported by PayPal](https://www.paypal.com/uk/webapps/mpp/country-worldwide) | | 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.address_line1` must be provided
- `billing.address.city` must be provided
- `billing.address.country` value must be set to a country in the [Single Euro Payments Area (SEPA)](https://www.ecb.europa.eu/paym/integration/retail/sepa/html/index.en.html)
- `billing.address.zip` must be provided
- `currency` value must be `EUR` | | stc pay | - `billing.address.country` must be set to `SA`
- `currency` value must be `SAR`
- `reference` must be provided | | Swish | - `billing.address.country` must be set to `SE`
- `currency` value must be `SEK`
- `payment_type` must be set to `Regular` | | Tabby | - `billing.address.country` value must be one of:
- `AE` for United Arab Emirates
- `SA` for Saudi Arabia
- `KW` for Kuwait
- `currency` value must be one of:
- `AED`
- `SAR`
- `KWD`




- `reference` must be provided




- The following shipping information must be provided:
- `shipping.address_line1`
- `shipping.city`
- `shipping.zip`




- `products[]` must be provided
- For each `product` in `products[]`, the following must be provided:
- `name`
- `price`
- `quantity` | | Tamara | - `reference` must be provided.
- `products[]` must be provided.
- `billing.address.address_line1` and `billing.address.city` must be provided.

- For each `item` in `items[]`, the following must be provided:
- `name`
- `unit_price`
- `quantity`

- Provide shipping information in the following fields:
- `shipping.address.address_line1`
- `shipping.address.city`
- `shipping.address.country`

- `billing.address.country` must be one of:
- `SA` for Saudi Arabia
- `AE` for United Arab Emirates

- `currency` must be one of:
- `SAR`
- `AED`

Tamara performs a credit assessment on each customer during the sign up and checkout process. In some cases, such as for marketplaces, travel, or high-risk industries, Tamara may require additional data to improve their risk assessment. This can include the following fields:

- `customer.summary.first_transaction_date`
- `customer.summary.is_premium_customer`
- `customer.summary.is_returning_customer`
- `customer.summary.last_payment_amount`
- `customer.summary.last_payment_date`
- `customer.summary.lifetime_value`
- `customer.summary.registration_date`
- `customer.summary.total_order_count` | | 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` | | TWINT | - `billing.address.country` value must be `CH`, for Switzerland
- `currency` value must be `CHF`
- `payment_type` must be set to `Regular`
- `reference` must be provided | | Venmo | - `billing.address.country` must be `US`, for the United States
- `currency` value must be `USD` | | Vipps | - `billing.address.country` value must be one of:
- `NO` for Norway
- `SE` for Sweden
- `currency` value must be one of:
- `NOK`
- `SEK` | | WeChat Pay | - `amount` must be provided
- `payment_type` value must be `Regular` | ### Request example ```json { "amount": 1000, "currency": "GBP", "reference": "ORD-123A", "billing": { "address": { "country": "GB" } }, "customer": { "name": "Ali Farid", "email": "ali.farid@example.com", "phone": { "country_code": "+44", "number": "7946 0000" } }, "success_url": "https://example.com/payments/success", "failure_url": "https://example.com/payments/failure", "cancel_url": "https://example.com/payments/cancel" } ``` ### Response example The response includes the `redirect` link to which you redirect your customer to finalize the payment. ```json { "id": "hpp_xGQBg0AXl3cM", "reference": "ORD-123A", "_links": { "self": { "href": "https://{prefix}.api.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM" }, "redirect": { "href": "https://pay.checkout.com/page/hpp_xGQBg0AXl3cM" } } } ``` ### Step 2: Redirect your customer Redirect the customer to the `_links.redirect` URL you received in the Create Hosted Payments Page response, using either a server-side or client-side call. **Server-side redirect** ```js res.redirect(hostedPaymentsResponse._links.redirect.href); ``` **Client-side redirect** ```js window.location.href(hostedPaymentsResponse._links.redirect.href); ``` ### Step 3: Confirm the payment status When your customer completes the payment, they're 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. For example: - `https://example.com/success?cko-session-id=sid_ubj2q76miwundwlk72vxt2i7` - `https://example.com/success?cko-payment-id=pay_mbabizu24mvu3mela5njyhpit4` > **Note** > > Do not rely only on the front-end redirection as confirmation that the payment was successful. Confirm the payment status from the relevant webhooks before you finalize the order or fulfill the sale. > > See the webhooks section of each [payment method](https://www.checkout.com/docs/payments/add-payment-methods.md) for the relevant webhooks to subscribe to. --- ## Check the status of a Hosted Payments Page 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. For example, `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. ### Endpoints For a full explanation of the fields, see the [API reference](https://api-reference.checkout.com/). > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `GET` `https://{prefix}.api.checkout.com/hosted-payments/{id}` **Sandbox** `GET` `https://{prefix}.api.sandbox.checkout.com/hosted-payments/{id}` ### Response examples **Payment Pending** ```json { "id": "hpp_xGQBg0AXl3cM", "status": "Payment Pending", "payment_id": "undefined", "amount": 200, "currency": "GBP", "reference": "ORD-123A", "description": "Payment for Gold Necklace", "expires_on": "2021-08-20T20:25:28+08:00", "customer": { "name": "John Smith", "email": "john.smith@example.com" }, "billing": { "address": { "address_line1": "123 High St.", "address_line2": "Flat 456", "city": "London", "zip": "SW1A 1AA", "country": "GB" }, "phone": { "country_code": "+44", "number": "1234567890" } }, "products": [ { "name": "Gold Necklace", "quantity": 1, "price": 200 } ], "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM" }, "redirect": { "href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM" } } } ``` **Payment Received** ```json { "id": "hpp_xGQBg0AXl3cM", "status": "Payment Received", "payment_id": "pay_mbabizu24mvu3mela5njyhpit4", "amount": 200, "currency": "GBP", "reference": "ORD-123A", "description": "Payment for Gold Necklace", "expires_on": "2021-08-20T20:25:28+08:00", "customer": { "name": "John Smith", "email": "john.smith@example.com" }, "billing": { "address": { "address_line1": "123 High St.", "address_line2": "Flat 456", "city": "London", "zip": "SW1A 1AA", "country": "GB" }, "phone": { "country_code": "+44", "number": "1234567890" } }, "products": [ { "name": "Gold Necklace", "quantity": 1, "price": 200 } ], "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM" }, "redirect": { "href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM" }, "payment": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4" }, "payment_actions": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions" } } } ``` **Expired** ```json { "id": "hpp_xGQBg0AXl3cM", "status": "Expired", "payment_id": "undefined", "amount": 200, "currency": "GBP", "reference": "ORD-123A", "description": "Payment for Gold Necklace", "expires_on": "2021-08-20T20:25:28+08:00", "customer": { "name": "John Smith", "email": "john.smith@example.com" }, "billing": { "address": { "address_line1": "123 High St.", "address_line2": "Flat 456", "city": "London", "zip": "SW1A 1AA", "country": "GB" }, "phone": { "country_code": "+44", "number": "1234567890" } }, "products": [ { "name": "Gold Necklace", "quantity": 1, "price": 200 } ], "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM" }, "redirect": { "href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM" } } } ``` --- ## Next steps **[Customize your Hosted Payments Page](https://www.checkout.com/docs/integrate/hosted-payments-page/customize-your-hosted-payments-page.md)** Find out how your Hosted Payments Page can be customized.