Hosted Payment Page

This page will take you through the Hosted Payment Page API and explain how to interact with it and its concepts. Please make sure to understand why you should use the Hosted Payment Page and the Overview of the system before reading this documentation. The Hosted Payment Page works with a Payment Provider from the Kustom ecosystem, and you will need to create a KCO Order before being able to create an HPP Session. A different integration guide is available for both platforms.

Ecosystem overview: components and objects

Hosted Payment Page (HPP) requires that you integrate different server-side REST APIs from the Kustom environment and thus requires no client-side integration. The different APIs correspond to different Kustom products and have some defined objects that interact with each other.

1. Payment Provider API

The Hosted Payment Page supports Kustom Checkout , which will be referred to in this documentation as the Payment Provider.

a. Kustom Checkout REST API: create Checkout Order

• KCO Order: a Checkout Order on Kustom Checkout API. It contains everything regarding the transaction and has a 48 hours lifetime. A KCO Session is considered as incomplete until the Consumer has not succeed in getting a valid payment. The KCO API has mechanisms to let you accept or not a payment and then automatically proceeds to the creation of the OM Order.

KCO Order will be referred to as Payment Session in the documentation.

2. Hosted Payment Page REST API

The Hosted Payment Page REST API can be used to let Kustom host the client-side integration of Kustom Checkout for you. You will have to create a Session and then distribute it.

3. Order Management REST API: capture payment

a. OM Order: a due payment from the Consumer for defined goods. It is created using a KP Authorization Token with the KP Session or automatically by Kustom Checkout when a KCO Order is completed. The OM Order will allow you to capture the payment when goods or service have been delivered, and manage the post purchase experience of the Consumer.

HPP Session

Session Lifecycle

Session Lifetime

KP Session, KCO Order  has an expiration time, but the expiration is driven by the Payment Session which usually expires 48 hours after its creation. A Consumer will be able to pay on HPP until 1 hour before the Payment Session expiration.

Kustom uses HTTP’s Basic auth to authenticate requests from Merchants. Use your API Credentials to add the corresponding HTTP headers to your requests, the credentials consist of two elements:

• Username: a username linked to your Merchant ID at Kustom
• Password: a unique password that is associated with the username

Use your credentials to generate the token: Base64(username:password)

Kustom offers a test environment named Playground and a Production environment. The different APIs are available on each environment. URL structures are the same for both environment, targeted environment will be defined by the domain you are using. To be able to test your integration, you will need a Test Account.

You can find more in our [ environments and testing guidelines].

The HPP API follows the same rules as other Kustom public APIs, we try to update our APIs regularly in a non breaking way, ensuring backward compatibility. You can find more in our API updates guidelines and see how we define backward compatibility and non-breaking changes.

• Accept any 2xx codes as success, do not code for a specific error response code
• Interpret any 4xx as an error, do not code for a specific error response code