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:
- Create a Hosted Payments Page session and pass through all the payment information, like the amount, currency, country and reference.
- We'll use this information to render the Hosted Payments Page to which you will redirect your customer to make their payment.
- Once your customer fills in the required payment details, we will process the payment and handle the authentication flow.
- 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
POSThttps://api.checkout.com/hosted-payments
POSThttps://api.sandbox.checkout.com/hosted-payments
Header parameters
Header | Value |
---|---|
REQUIRED |
|
REQUIRED | application/json |
Body parameters
The table below describes the minimum recommended fields. For the full specification, see our API reference.
Field name | Description |
---|---|
INTEGER OPTIONAL | The payment amount. Must be greater than |
STRING REQUIRED | The payment currency. |
STRING OPTIONAL | An optional reference you can use to later identify the payment. |
OBJECT REQUIRED | The billing details. |
OBJECT REQUIRED | The customer's billing address. |
STRING OPTIONAL | The first line of the address. |
STRING OPTIONAL | The second line of the address. |
STRING OPTIONAL | The address city. |
STRING OPTIONAL | The address state. |
STRING OPTIONAL | The address zip/postal code. |
STRING REQUIRED | The address country (two-letter ISO country code). |
STRING REQUIRED | The URL to which the customer will be directed if the payment is successful. |
STRING REQUIRED | The URL to which the customer will be directed if the payment fails. |
STRING REQUIRED | The URL the customer will be directed to if they choose to cancel the payment. |
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_url
. The session ID is provided in the cko-session-id
query parameter included in the redirect URL. It should look something like this: http://example.com/success?cko-session-id=sid_ubfj2q76miwundwlk72vxt2i7.
You can set up webhooks to be notified when the payment has been approved to continue the sales fulfilment flow.
Next steps
- Learn how to refund a payment, and more.
- Set up webhooks to be notified about the status of payments.
Can we help?
Thanks for using Checkout.com. If you need help or have a question, message our Support team at support@checkout.com.