Korba XCheckout

A hosted checkout page that lets your customers pay securely without you ever touching their payment details — just drop in a script tag and a button.

Overview

Korba XCheckout is a hosted payment page managed entirely by Korba Xchange. Instead of building your own payment form and handling sensitive card or mobile money details, you embed a small JavaScript snippet on your site. When a customer clicks Pay, XCheckout opens a secure, Korba-hosted interface that collects payment information and processes the transaction on your behalf.

Once the transaction reaches a terminal state, Korba sends the result to the callback URL you configured on the dashboard. Your server then verifies the callback and fulfils the order.

Prerequisites

Enable XCheckout before integrating. Log in to your Korba Xchange dashboard, navigate to the Developer section, and enable XCheckout for your account. From that same section you can generate your Website Token and register the Callback URL that Korba will deliver transaction results to via a GET request.

Complete these steps in the dashboard before writing any code:

Go to Dashboard → Developer → XCheckout and enable the feature.
Generate your Website Token (used as merchantID in the script).
Add your publicly accessible Callback URL — this is where Korba will deliver the payment result.

Integration

Add the XCheckout script to your page, call XCheckout.configure() with your payment details, then trigger XCheckout.pay() from a button. That is the entire integration.

<!-- 1. Load the XCheckout script -->
<script src='https://paywithkorba.s3-eu-west-1.amazonaws.com/checkout.js'></script>

<!-- 2. Configure the checkout -->
<script>
  XCheckout.configure({
    merchantID:   '<your_merchant_id>',
    orderID:      '<unique_order_id>',
    description:  'Ordered goods',
    amount:       1.2,
    redirectURL:  'http://www.yourawesomeapp.com',
  });
</script>

<!-- 3. Trigger payment on button click -->
<input type="button" value="Pay" onclick="XCheckout.pay();" />

Parameters

Pass these fields to XCheckout.configure(). All parameters are required.

Parameter	Type	Required	Description
merchantID	string	Yes	Your Website ID found in the dashboard under Developer → XCheckout. This identifies your account to the hosted checkout.
orderID	string	Yes	A unique identifier for this order from your system. Must be distinct for every payment attempt — duplicate IDs will be rejected.
description	string	Yes	A short, human-readable description of what the customer is paying for. Displayed on the checkout page.
amount	number	Yes	The amount to charge the customer. Must be a positive number (e.g. `1.2` for GHS 1.20).
redirectURL	string	Yes	The URL the customer is redirected to after the checkout flow completes, regardless of outcome. Use this page to display an order confirmation or status message.

Callback Parameters

When a transaction reaches a terminal state, Korba Xchange sends an HTTP GET request to the Callback URL you registered on the dashboard, with the result appended as query parameters. Your endpoint should return a 2xx response to acknowledge receipt.

Parameter	Type	Description
transaction_id	string	The `orderID` you supplied when configuring XCheckout. Use this to match the callback to a specific order in your system.
status	string	`SUCCESS` — payment was received. `FAILED` — payment was not completed.
message	string	A human-readable description of the transaction outcome.

Example Callback Payload

{
  "transaction_id": "ORD-20240422-001",
  "status":         "SUCCESS",
  "message":         "Transaction completed successfully"
}

{
  "transaction_id": "ORD-20240422-001",
  "status":         "FAILED",
  "message":         "Customer cancelled the payment request"
}

Security

Because your callback URL is publicly accessible, any server on the internet could send a fake request to it. Korba Xchange provides a shared secret — the Callback Token — that lets you confirm a callback genuinely came from Korba.

Always verify the X-Callback-Token header before processing a callback. Every callback Korba sends includes a custom HTTP header X-Callback-Token. Compare its value against your Callback Token from the dashboard (Developer → XCheckout). If the values do not match, discard the request — do not fulfil the order.

Your callback handler should follow this pattern:

Read the X-Callback-Token header from the incoming request.
Compare it to your stored Callback Token using a constant-time comparison to prevent timing attacks.
If the tokens match, inspect status and act accordingly (fulfil the order on SUCCESS, notify the customer on FAILED).
Return 200 OK to acknowledge the callback regardless of the outcome — Korba may retry if it does not receive a success response.

Previous Collections Next WooCommerce Plugin