Skip to content
HitchPay API Docs

Checkout Payments

Initiate Payment

Create a hosted checkout session and get a payment reference and payment URL.

POST /v1/payments/initiate

Initiate a new payment session. Returns a unique reference and payment_url for the customer to complete payment on HitchPay's hosted checkout.

Request

Body Parameters

Parameter Type Required Description
amount number ✅ Amount to charge. Must be greater than zero
currency string ✅ ISO currency code — NGN, USD, KES, or GHS
reference string ✅ Unique merchant-generated reference for idempotency
callback_url string (URL) ✅ URL to redirect the customer after payment. HitchPay appends reference and status
allow_currency_selection boolean ✅ If true, customer can select their preferred pay currency
customer.name string ✅ Customer's full name
customer.email string ✅ Customer's email address
customer.phone string ✅ Customer's phone number

Code Samples

const axios = require("axios");

const response = await axios.post(
  "https://sandbox.hitchpay.ng/v1/payments/initiate",
  {
    amount: 100,
    currency: "USD",
    reference: "REF_001",
    callback_url: "https://yourapp.com/callback",
    allow_currency_selection: true,
    customer: {
      name: "John Doe",
      email: "[email protected]",
      phone: "08012345678"
    }
  },
  {
    headers: {
      Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
      "Content-Type": "application/json"
    }
  }
);

console.log(response.data);
<?php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/payments/initiate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "amount" => 100,
    "currency" => "USD",
    "reference" => "REF_001",
    "callback_url" => "https://yourapp.com/callback",
    "allow_currency_selection" => true,
    "customer" => [
      "name"  => "John Doe",
      "email" => "[email protected]",
      "phone" => "08012345678"
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
import requests

url = "https://sandbox.hitchpay.ng/v1/payments/initiate"

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}

data = {
    "amount": 100,
    "currency": "USD",
    "reference": "REF_001",
    "callback_url": "https://yourapp.com/callback",
    "allow_currency_selection": True,
    "customer": {
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "08012345678"
    }
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Response

200 — Success

{
  "status": "success",
  "message": "Payment initiated successfully.",
  "data": {
    "reference": "HCHK248EBF3863",
    "payment_url": "https://checkout.hitchpay.ng/pay/HCHK248EBF3863"
  }
}

400 — Bad Request

{
  "status": "error",
  "code": "INVALID_REQUEST",
  "message": "Missing required fields"
}

Payment Flow

  1. Call this endpoint → receive payment_url and reference
  2. Redirect customer to payment_url
  3. Customer completes payment on HitchPay's hosted checkout
  4. Customer is redirected to your callback_url with ?reference=...&status=...
  5. Always verify final status via GET /v1/payments/verify/{reference}

Questions? Email [email protected]. Also on GitBook.