Inline Checkout SDK

Hitchpay Inline SDK allows customers to complete payments inside a pop-up modal, without leaving the merchant’s page.

Use this to

• Add a "Pay with HitchPay" button to any page with minimal setup
• Collect payment via a modal for bank transfer/mobile money, or a full-page redirect for card and cross-border methods
• Confirm every payment server-side, regardless of which payment method the customer used

1. Include the script

Load inline.js from the HitchPay payment host root — not under /checkout.

<script src="https://payment.hitchpay.ng/inline.js"></script>

2. Trigger a payment

Option A — call pay() from your own button

<button onclick="payWithHitchpay()">Pay with HitchPay</button>

<script>
function payWithHitchpay() {
  HitchPayCheckout.pay({
    client_id: "hitchpay_client_xxxxxxxx",   // from your dashboard
    amount: "15000",
    email: "[email protected]",
    currency: "NGN",
    reference: "YOUR-ORDER-123",              // your own order id
    callback: "https://your-site.com/confirm",
    onSuccess: function (res) { console.log("Success:", res.reference); },
    onCancel:  function ()    { console.log("Cancelled"); },
    onError:   function (err) { console.error("Error:", err); }
  });
}
</script>

Option B — declarative button (no JS)

<button
  class="hitchpay-button"
  data-client_id="hitchpay_client_xxxxxxxx"
  data-amount="5000"
  data-email="[email protected]"
  data-currency="NGN"
  data-reference="YOUR-ORDER-123"
  data-callback="https://your-site.com/confirm"
>
  Pay with HitchPay
</button>

Options

client_id

Handling the result — important

Payment methods fall into two categories, and they report success differently:

Redirect-based methods send the customer to a provider's hosted page (Stripe, Peach, etc.), which replaces your page. Your onSuccess handler no longer exists when payment finishes, so it cannot fire for these methods.

After the customer completes payment on the hosted page, they're returned to your callback url — the same behavior for card and cross-border redirects. Confirm the outcome with a webhook or a status lookup, not the return URL alone.

Confirm every payment server-side with webhooks

Register a webhook URL in your dashboard. HitchPay posts a server-to-server notification on success regardless of what the customer's browser does. The payload includes your merchant_reference (the reference you passed).

This is the reliable confirmation — see Payment Success Event / Payment Failed Event in the global Webhooks section.

onSuccess (inline methods only)

Fires for bank transfer / mobile money. The response includes your reference:

onSuccess: function (res) {
  // res.reference === "YOUR-ORDER-123"
}

Return URL (callback)

After payment, the customer is sent to your callback url with your reference appended as a query param, so your page can greet the returning customer:

https://your-site.com/confirm?external_reference=YOUR-ORDER-123

Verifying a transaction's status

You can query a transaction server-side at any time — by the HitchPay reference or by your own reference (the reference you passed). This is the same lookup documented on the Verify Payment page in this section; included here for convenience since it's the confirmation method for redirect-based checkouts.

GET /v1/payments/verify/:reference
Authorization: Bearer <access_token>

:reference accepts either identifier.

cURL — by your own order reference

curl https://sandbox.hitchpay.ng/v1/payments/verify/YOUR-ORDER-123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

cURL — by the HitchPay reference

curl https://sandbox.hitchpay.ng/v1/payments/verify/HCHK2D004085F6 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "status": "successful",
  "response_code": "01",
  "amount": 15000,
  "amount_paid": 15000,
  "currency": "NGN",
  "reference": "HCHK2D004085F6",
  "external_reference": "YOUR-ORDER-123",
  "paid_at": "2026-07-25T20:14:00.000Z",
  "payment_channel": "stripe",
  "customer": { "email": "[email protected]", "name": "Jane Doe" },
  "merchant": { "name": "Acme Ltd", "email": "[email protected]" }
}

status is one of pending, successful, failed, or partial. The lookup is scoped to your account, so you only ever see your own transactions.

For the full request/response reference (headers, all fields, error codes), see the Verify Payment page in this section.