Guides
API Reference

Our reference library for integrating with our API

FAQ

Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

Hosted Payments Page

Accept card payments with a Hosted Payments Page—a fast and easy way to collect your customer’s payment information, process the payment request and handle authentication.

Our Hosted Payments Page is built on our Unified Payments solution. If you are upgrading from an older integration option, take a look at our migration guide to understand the new features.

Supported payment methods

You can accept the following payment methods with Hosted Payments:

How it works

When your customer is ready to check out:

  1. Create a Hosted Payments Page session and pass through all the payment information, like the amount, currency, country and reference.
  2. We'll use this information to render the Hosted Payments Page to which you will redirect your customer to make their payment.
  3. Once your customer fills in the required payment details, we will process the payment and handle the authentication flow.
  4. And after the payment has been successfully processed, you will be notified by a webhook.


Try it out

Preview a Hosted Payments Page using one of our test cards with any future expiry date, or use the details below for a basic payment flow:

  • Card number: 4242 4242 4242 4242
  • Expiry date: Any future date
  • CVV: 100

Get started

Step 1: Register to use Hosted Payments Pages

To get started with our Hosted Payments Page, contact your Solutions Engineer or integration@checkout.com.

If you haven't already, create a free test account now. This will give you access to the Hub, where you'll find your secret_key and public_key, which you'll need to make requests to our API.

Step 2: Create a Hosted Payments Page session

To create a Hosted Payments Page on which your customers can make their payment, use the endpoint below.

The request

Endpoints

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

Header parameters

HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json

Body parameters

The table below describes the minimum recommended fields. For the full specification, see our API reference.


Testing

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


Field nameDescription

amount

INTEGER

OPTIONAL

The payment amount.

Must be greater than 1.

currency

STRING

REQUIRED

The payment currency.

reference

STRING

OPTIONAL

An optional reference you can use to later identify the payment.

billing

OBJECT

REQUIRED

The billing details.

billing.address

OBJECT

REQUIRED

The customer's billing address.

billing.address.address_line1

STRING

OPTIONAL

The first line of the address.

billing.address.address_line2

STRING

OPTIONAL

The second line of the address.

billing.address.city

STRING

OPTIONAL

The address city.

billing.address.state

STRING

OPTIONAL

The address state.

billing.address.zip

STRING

OPTIONAL

The address zip/postal code.

billing.address.country

STRING

REQUIRED

The address country (two-letter ISO country code).

success_url

STRING

REQUIRED

The URL to which the customer will be directed if the payment is successful.

failure_url

STRING

REQUIRED

The URL to which the customer will be directed if the payment fails.

cancel_url

STRING

REQUIRED

The URL the customer will be directed to if they choose to cancel the payment.
 Parameters for supported payment methods
Payment methodbilling.address.countrycurrencyreference
KNETKW - KuwaitKWD

OPTIONAL

MadaSA - Saudi ArabiaSAR

OPTIONAL

PayPalAny supportedAny supported

REQUIRED

Sofort

AT - Austria

BE - Belgium

DE - Germany

IT - Italy

NL - Netherlands

ES - Spain

EUR

OPTIONAL

Request examples

{
  "amount": 1000,
  "currency": "GBP",
  "reference": "ORD-123A",
  "billing": {
    "address": {
      "country": "GB"
    }
  },
  "customer": {
    "name": "Jack Napier",
    "email": "jokershere@gmail.com"
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure",
  "cancel_url": "https://example.com/payments/checkout"
}
{
  "amount": 1000,
  "currency": "KWD",
  "reference": "ORD-123A",
  "billing": {
    "address": {
      "country": "KW"
    }
  },
  "customer": {
    "name": "Jack Napier",
    "email": "jokershere@gmail.com"
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure",
  "cancel_url": "https://example.com/payments/checkout"
}
{
  "amount": 1000,
  "currency": "SAR",
  "reference": "ORD-123A",
  "billing": {
    "address": {
      "country": "SA"
    }
  },
  "customer": {
    "name": "Jack Napier",
    "email": "jokershere@gmail.com"
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure",
  "cancel_url": "https://example.com/payments/checkout"
}
{
  "amount": 1000,
  "currency": "EUR",
  "reference": "ORD-123A",
  "billing": {
    "address": {
      "country": "BE"
    }
  },
  "customer": {
    "name": "Jack Napier",
    "email": "jokershere@gmail.com"
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure",
  "cancel_url": "https://example.com/payments/checkout"
}

The response

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

Response example

{
  "reference": "ORD-123A",
  "_links": {
    "redirect": {
      "href": "https://pay.sandbox.checkout.com/page/xGQBg0AXl3cM"
    }
  } 
}

Step 3: Redirect your customer

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

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

Step 4: Confirm the payment status

When your customer completes the payment, they will be redirected to the success_urlThe session ID or payment ID is provided in the query parameter included in the redirect URL. It should look something either of the links below: 

  • http://example.com/success?cko-session-id=sid_ubfj2q76miwundwlk72vxt2i7
  • http://example.com/success?cko-payment-id=pay_mbabizu24mvu3mela5njyhpit4

You can set up webhooks to be notified when the payment has been approved to continue the sales fulfilment flow.

Next steps