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. We've created a table that lists supported payment methods, languages and other features.

New payment methods supported

Hosted Payments Page now support five more payment methods.

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 with the demo below. You can try it with one of our test cards, or Sofort test details.

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

Use the following details to test a Sofort payment flow:

  1. Enter 88888888 in the 'Bank name, BLZ, IBAN or BIC' field. Click Next.
  2. Enter 88888888 in the 'Account number' field.
  3. Enter 123456 in the PIN field. Click Next.
  4. Select any account. Click Next.
  5. Enter 12345 in the TAN field. Click Next.


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

Sessions expire

Hosted Payments Page sessions expire after 30 minutes.

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

The request

For the full specification, see our API reference.

Endpoints

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

Testing

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

Request example

{
  "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"
}

Alternative payment methods

We've listed the available alternative payment methods for the Hosted Payments Page below.

Different payment methods have different required and optional fields when making a request. We've listed these below.

You can view a request example with all of these fields on our API reference.

Payment methodField requirements

KNET

  • billing.address.countryKW for Kuwait.
  • currency to KWD.

Mada

  • billing.address.countrySA for Saudi Arabia
  • currencySAR.

PayPal

  • reference is required.
  • billing.address.country and currency is required and can be any that are supported.

Sofort

iDEAL

  • currency should be set to EUR
  • billing.address.countryNL for Netherlands

Bancontact

  • billing.address.countryBE for Belgium.
  • currencyEUR.
  • customer.name is required.

EPS

  • billing.address.countryAT for Austria.
  • currencyEUR.

Giropay

  • billing.address.countryDE for Germany.
  • currencyEUR.

Multibanco

  • billing.address.countryPT for Portugal.
  • currencyEUR.
  • customer.name is required.

Przelewey24

  • billing.address.countryPL for Poland.
  • currencyEUR or PLN.
  • customer.name is required.
  • customer.email is required.

Response example

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

{
  "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