Create order with Hosted Payment Page - API Details
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

This page provides details on creating sessions for the Hosted Payment Page (HPP) API.

Overview

When a Kustom Checkout order is created with the Checkout API, an HPP session can be generated. This allows displaying the Kustom Checkout interface to the consumer without iframe integration on your website.
The HPP session and order share a lifecycle, with the HPP session expiring one hour before the order session. Updates to the payment session status also affect the HPP session.

Customization

All Hosted Payment Page customizations are done during session creation. Refer to the customization guide.

Creating the Request

Payment Session URL

The URL for the payment session depends on the payment provider:

Payment Provider	URL Structure
Kustom Checkout	`https://<environment-domain>/checkout/v3/orders/<kco_order_id>`

These URLs must be obtained from your Checkout order (KCO) creation APIs. The specific environment-domain and order ID should be checked in Kustom's environment and testing documentation.

Merchant URLs

Merchant URLs are used to redirect the consumer after successful payment, rejection, or cancellation.

Empty or null values for success, cancel, back, failure, or error URLs will display a generic confirmation page.

Use placeholders like {{session_id}} or {{order_id}} for context in these URLs.

Tag	Place holder Usage
`{{session_id}}`	The identifier of the HPP Session.
`{{order_id}}`	Order identifier for KCO or KP sessions with place_order_mode (used only with KCO or KP's place_order_mode).

Branding Customization

Use optional parameters to customize the HPP's appearance and match your brand. Refer to the customization guide.

Payment Provider Specific Parameters

Kustom Checkout (KCO):

No specific parameters are required for KCO.

Interpreting the Response

On successful HPP session creation, the response contains several URLs for interacting with the payment page:

Field Key	Type	Description
`session_id`	String	HPP session ID.
`session_url`	API Endpoint URL	Used to retrieve the HPP session. Requires merchant credentials.
`distribution_url`	API Endpoint URL	Distribute the session by email/SMS. Requires merchant credentials.
`redirect_url`	Public URL	Redirects the consumer to the payment page.
`qr_code_url`	Public URL	Displays a QR code for mobile payment.
`expires_at`	Date	Session expiration time.
`distribution_module`	Object	Contains token and URLs for standalone distribution.

These URLs should be directly used by the integration layer, as their structure might change.