Checkout: API Reference¶

Our Checkout reference is here to help you find those hard-to-find bits of information all in one place. Use the right-side navigation to find your way around the page.

Redirecting customers to Checkout¶

You can use a Payment Link (standard HTML form) or Payment Widget (JS) to collect and pass payment and customer details to Checkout. More about integration methods you could find here.

When the customer selects the payment option, your website should post the HTML form containing their transaction details to {BASE COM API URL}/hpp/.

The HTML form should contain the mandatory hidden input fields listed in Configuration.

You could use a secure method of obtaining a pre-created Payment Invoice ID before redirecting customers to Checkout, as described in Secure redirection method.

Secure redirection method¶

Use this method to ensure that details of the payment are communicated securely between your server and Cublox.

The redirection process is as follows:

1. Your web server makes a standard POST request with the payment parameters, using the Private API
2. The Cublox server prepares a Payment Invoice for the payment and returns a standard HTTP(S) response with it
3. Your web server takes the body of the response that contains a Payment Invoice ID value
4. With this Payment Invoice ID value, you can redirect the customer to:

{BASE COM API URL}/hpp/?cpi=<PAYMENT_INVOICE_ID>

<script src="https://unpkg.com/@paycore/merchant-widget-js@0.3.0/dist/merchantWidget.umd.js"></script>
<script>
window.widget.init({
    cpi: "<PAYMENT_INVOICE_ID>",
});
</script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>

Configuration options¶

The selected integration type determines how you set the Checkout parameters.

Parameters to include¶

<script
    src="https://unpkg.com/@paycore/merchant-widget-js@0.3.0/dist/merchantWidget.umd.js">
</script>
    
    <div id="merchant-widget-mount-point"></div>
<script>
    window.widget.init({
    public_key: "your_public_key", //replace this value with your public key
    baseUrl: "{BASE COM API URL}/hpp",
    flow: "iframe",
    selector: "merchant-widget-mount-point",
    amount: 10,
    currency: "USD",
    language: "en",
    description: "Simple description of your payment operation.",
    reference_id: "",
    expires: 1652479200,
    cpi: "",
    service: "payment_card_usd_hpp",
    metadata: {
        key: "value"
    },
    customer: {
        reference_id: "5ae4002f-5332-4a0f-b951-da4b9a1c46c4",
        email: "email@customer.com",
        phone: "123456789000000",
        metadata: {
            key: "value",
            key1: "value1"
            },
        address: {
            country: "GB",
            region: "London City",
            city: "London",
            street: "Oxford Street",
            full_address: "Postal Address",
            post_code: "SW1A2AA"
            },
        name: "New Customer"
        }
    });
</script>

<form action="{BASE COM API URL}/hpp/" method="GET">​
    <input type="hidden" name="public_key" value="your_public_key"/>  <!--> replace this value with your public key <-->
    <input type="hidden" name="reference_id" value="Test_order_01_1"/>
    <input type="hidden" name="currency" value="USD"/>
    <input type="hidden" name="service" value="payment_card_usd_hpp"/>
    <input type="hidden" name="amount" value="10.00"/>
    <input type="hidden" name="description" value="Some info about order"/>
    <input type="hidden" name="expires" value="1602414000" />
    <input type="hidden" name="customer[reference_id]" value="test12345"/>
    <input type="hidden" name="customer[name]" value="Test Customer"/>
    <input type="hidden" name="customer[address][full_address]" value="Test Address"/>
    <input type="hidden" name="customer[address][country]" value="UK"/>
    <input type="hidden" name="customer[metadata][key1]" value="value1" />
    <input type="hidden" name="customer[metadata][key1]" value="value2" />
    <input type="submit" value="PAY"/>
</form>

Bypass HPP status page¶

After completing the payment process, Checkout can redirect a customer to the given Return URL bypassing the payment status page. You can set up this option in the Account settings.

Return URL¶

Provide custom return_url so that your customers are returned to your website at the end of the payment process.

If you don't provide return_url, customers are redirected to one of Cublox's default result pages where the payment journey ends.

Cublox configures the return URL for you in your account, but you can also send return_url in Private API integration and override this option.

For example, you might want to redirect payers to a URL on your site that is specific to that person, perhaps with a session ID or other transaction-related data included in the URL.

To set the return URL for individual transactions, include the return_url variable in the payment invoice configuration.

Localisation¶

By default, it uses the client’s browser language, but you can specify the language for page display using additional attribute locale (string, the ISO 639-1 code of one of predefined languages. Avalilable values: en, uk, ru).

<script src="https://unpkg.com/@paycore/merchant-widget-js@0.3.0/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
    window.widget.init({
        public_key: "your_public_key", // replace the value with YOUR commerce public key
        baseUrl: "{BASE COM API URL}/hpp/",
        flow: "iframe",
        selector: "merchant-widget-mount-point",
        locale: "uk",
        amount: 100.00,
        currency: "USD",
        description: "Some goods"
    });
</script>

Customization¶

One of our favourite things about Checkout is its customizability. By following this styling guide, you can make changes to just about anything.

Display¶

Set in display key as an array object with the following properties:

Filtering¶

For some payment requests, you may decide to filter the payment methods that are displayed on the Checkout or bypass the Checkout entirely.

Set in display key as an array object with the following properties:

Styling¶

Checkout can be customized to fit seamlessly with your brand. You can use different selectors, properties and values.

You can define advanced styling and customization of Checkout by setting the styling property style in the configuration object.

The available options for the styling object:

<script src="https://unpkg.com/@paycore/merchant-widget-js@0.3.0/dist/merchantWidget.umd.js">
</script>

<div id="merchant-widget-mount-point"></div>
<script>
window.widget.init({
    public_key: "your_public_key", // replace the value with YOUR commerce public key
    baseUrl: "{BASE COM API URL}/hpp/",
    flow: "iframe",
    selector: "merchant-widget-mount-point",
    amount: "100.00",
    currency: "USD",
    style: {
        pay_button_label: "Pay now",
        },
    });
</script>

Metadata¶

In the example above we suppose you store the reference_id that is unique to the payment in your order table. This way, your back-end can look-up the order for this payment when Cublox sends the callbacks. Your back-end is keeping track of the payment, effectively bringing about the connection between order and payment. This approach is easiest to grasp, which is why we use it in our example.

Alternatively, you can ask Cublox to remember the unique identifier of your order by instructing the Cublox API to store it in the payment’s metadata. You would provide it while creating the payment. In our example, order_id would be a good candidate. Cublox stores the metadata for you and include the metadata in the response when you fetch the payment while processing the callbacks. It is another way to connect orders and payments. We advise using the metadata approach. It is the most popular approach and the easiest to implement.

If you want to store additional/custom data at a resource's level, you can make use of Cublox's Metadata.

For example, if you're a data service provider and want to store certain features of a particular plan, such as "Usage Limit" or "Speed within limit", you can store it in the Metadata of the plan.

Considering the same example as above, if you want to store the additional features of a particular data plan, JSON will look like:

<script src="https://unpkg.com/@paycore/merchant-widget-js@0.3.0/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
window.widget.init({
    public_key: "your_public_key", // replace the value with YOUR commerce public key
    baseUrl: "{BASE COM API URL}/hpp/",
    flow: "iframe",
    selector: "merchant-widget-mount-point",
    reference_id: "<your_unique_reference_id>",
    amount: 100.00,
    currency: "USD",
    description: "Some goods",
    metadata: {
        "usage-limit": "5GB",
        "speed-within-quota": "2MBbps",
        "post-usage-quota": "512kbps"
    }
});
</script>

<form action="{BASE COM API URL}/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="reference_id" value="<your_unique_reference_id>" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="metadata[usage-limit]" value="5GB" />
    <input type="hidden" name="metadata[speed-within-quota]" value="2MBbps" />
    <input type="hidden" name="metadata[post-usage-quota]" value="512kbps" />
    <input type="submit" value="Pay" />
</form>