HTML Checkout - API Documentation

Overview

The HTML Checkout is the simplest way to accept payments. You create a standard HTML <form> on your website with the payment details as hidden fields. The form's action points to our checkout URL. When the payer clicks "Pay", the form submits and the payer is redirected to our secure payment page to complete the transaction.

No server-side code or SDK is required — just plain HTML.

ℹ️ Tip: If you want to open the checkout in a modal overlay without leaving your page, see the JS SDK documentation.

How It Works

Build a form — Create an HTML <form> with method="POST" and action set to the checkout URL.
Add hidden fields — Include your public key, amount, currency, transaction reference, and any other parameters as hidden <input> fields.
Payer submits — The payer clicks your "Pay" button, the form submits, and they are redirected to our secure payment page.
Payment — The payer selects a payment method and completes the payment on our page.
Redirect — After payment, the payer is redirected back to your redirect_url with query parameters indicating the result.
Webhook — Your callback_url receives the final transaction status server-side.

Form Action URL

Set your form's action attribute to:

https://checkout.genesyspay.com/v1/hosted/initiate

The form must use method="POST".

Quick Example

<form method="POST" action="https://checkout.genesyspay.com/v1/hosted/initiate">
  <input type="hidden" name="pub_key"      value="YOUR_PUBLIC_KEY" />
  <input type="hidden" name="amount"       value="5000" />
  <input type="hidden" name="currency"     value="CDF" />
  <input type="hidden" name="country"      value="CD" />
  <input type="hidden" name="allowed_channels" value="mobile_money" />
  <input type="hidden" name="tx_ref"       value="order-12345" />
  <input type="hidden" name="description"  value="Purchase #12345" />
  <input type="hidden" name="redirect_url" value="https://yoursite.com/payment/callback" />
  <input type="hidden" name="callback_url" value="https://yoursite.com/webhook" />
  <input type="hidden" name="payer_name"   value="John Doe" />
  <input type="hidden" name="payer_email"  value="[email protected]" />

  <button type="submit">Pay 5,000 CDF</button>
</form>

That's it. When the payer clicks the button, they are taken to the secure payment page.

Form Fields

Add each parameter as a hidden <input> inside your form:

Field Name	Type	Required	Description
`pub_key`	string	Required	Your merchant public key.
`amount`	numeric	Required	Amount to charge (min 0.01).
`currency`	string	Required	Currency code (e.g. `CDF`, `USD`).
`tx_ref`	string	Required	Your unique transaction reference (max 255 chars). Must be unique per business.
`country`	string	Optional	2 or 3-letter ISO country code to restrict available payment methods.
`allowed_channels`	string	Optional	Comma-separated list of allowed payment channels. Values: `mobile_money`, `card`. Example: `mobile_money,card`.
`method`	string	Optional	Pre-select a specific payment method slug (e.g. `airtel`). Skips the method selection screen.
`description`	string	Optional	Payment description shown to the payer (max 255 chars).
`redirect_url`	url	Optional	URL to redirect the payer back to your site after payment.
`callback_url`	url	Optional	Webhook URL to receive the final transaction status server-side.
`bearer`	string	Optional	Who pays the fees: `customer` (default) or `merchant`.
`payer_name`	string	Optional	Payer's full name (max 100 chars).
`payer_email`	email	Optional	Payer's email address (max 150 chars).
`payer_phone`	string	Optional	Payer's phone number (max 30 chars).

Complete HTML Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Checkout</title>
</head>
<body>
  <h1>Order Summary</h1>
  <p>Total: 5,000 CDF</p>

  <form method="POST" action="https://checkout.genesyspay.com/v1/hosted/initiate">
    <!-- Required fields -->
    <input type="hidden" name="pub_key"      value="pk_live_xxxxxxxxxxxx" />
    <input type="hidden" name="amount"       value="5000" />
    <input type="hidden" name="currency"     value="CDF" />
    <input type="hidden" name="tx_ref"       value="order-12345" />

    <!-- Optional fields -->
    <input type="hidden" name="country"      value="CD" />
    <input type="hidden" name="allowed_channels" value="mobile_money,card" />
    <input type="hidden" name="description"  value="Payment for Order #12345" />
    <input type="hidden" name="redirect_url" value="https://yoursite.com/payment/callback" />
    <input type="hidden" name="callback_url" value="https://yoursite.com/webhook" />
    <input type="hidden" name="bearer"       value="customer" />
    <input type="hidden" name="payer_name"   value="John Doe" />
    <input type="hidden" name="payer_email"  value="[email protected]" />
    <input type="hidden" name="payer_phone"  value="0707070707" />

    <button type="submit" style="
      background: #6366f1; color: #fff; border: none;
      padding: 12px 32px; border-radius: 6px; font-size: 16px;
      cursor: pointer;
    ">
      Pay 5,000 CDF
    </button>
  </form>
</body>
</html>

Redirect Back to Your Site

After payment, if you provided a redirect_url, the payer will be redirected with the following query parameters appended:

Parameter	Description
`status`	`success` or `failed`
`tx_ref`	Your original transaction reference.
`transaction_id`	The transaction ID (if available).

Example redirect:

https://yoursite.com/payment/callback?status=success&tx_ref=order-12345&transaction_id=TXN-REF-123

⚠️ Important: Never rely solely on the redirect parameters to confirm payment. Always verify the final status server-side using your callback_url webhook.

Session Expiry

Checkout sessions expire 30 minutes after the form is submitted. If the payer has not completed payment by then, the session becomes expired and no further payment attempts are allowed. The payer will need to submit your form again to start a new session.

Error Handling

If the form data is invalid (e.g. missing required fields, invalid currency), the payer will see an error page on our domain with a description of the issue. They will not be redirected back to your site for validation errors.

Make sure all required fields are present and correct before displaying the form to the payer.