Online Payments

Integrate the payment request APIs in 3 simple steps

Core Concept

At a high level, integrating payments into your system involves a 3-step process:

1. Create a Payment Request

   Create a payment request from your server using the HitPay API.

2. Present the Checkout Page

   Redirect the customer to the checkout URL or embed the Drop-in UI.

3. Handle Webhooks

   Receive and validate webhook notifications to confirm payment.

Authentication: All API requests require your API key in the header. You can find your key in the HitPay Dashboard under Settings > API Keys.

X-BUSINESS-API-KEY: your_api_key_here

API keys should be kept confidential and only stored on your servers. Do not store them on your mobile or web client.

Step 1: Create Payment Request

This is the first step of the payment flow, once you have all the details from the user and are ready to collect payments, use this API to create a payment request.

Since this is a server-to-server communication, if you have a mobile or Web client that communicates with your REST API, you must have a new endpoint E.g. /create-order, or reuse an existing endpoint. This endpoint will be responsible for making the payment request API call to hitpay.

Endpoint

Sandbox

POST https://api.sandbox.hit-pay.com/v1/payment-requests

Production

POST https://api.hit-pay.com/v1/payment-requests

Start with the sandbox endpoint for testing. When you’re ready to go live, swap to the production URL and update your API key.

Request Parameters

Mandatory fields are amount and currency. Remember to include header Content-Type: application/x-www-form-urlencoded

Parameter	Description	Example
amount	Amount related to the payment	2500.00
payment_methods[]	Choice of payment methods you want to offer the customer	paynow_online, card (Full list)
currency	Currency related to the payment	SGD
email	Buyer’s email	[e-mail]
purpose	Purpose of the Payment request	FIFA 16
name	Buyer’s name	John Doe
reference_number	Arbitrary reference number that you can map to your internal reference number. This value cannot be edited by the customer	XXXX123
redirect_url	URL where we redirect the user after a payment. Query arguments reference (payment request id) and status are sent along	https://example.com/callback
allow_repeated_payments	If set to true, multiple payments can be paid on a payment request link. Default value is false	false
expiry_date	Time after which the payment link will be expired (time in SGT). Applicable for repeated payments. Default is Null	2021-02-02 01:01:01

PHP

$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.hit-pay.com/v1/payment-requests');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append(new http\QueryString(array(
  'email' => '[e-mail]',
  'redirect_url' => 'https://test.com/success',
  'reference_number' => 'REF123',
  'currency' => 'SGD',
  'amount' => '599')));$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'X-BUSINESS-API-KEY' => 'your_api_key_here',
  'Content-Type' => 'application/x-www-form-urlencoded',
  'X-Requested-With' => 'XMLHttpRequest'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

Response

{
    "id": "90f28b43-2cff-4f86-a29e-15697424b3e7",
    "name": null,
    "email": "[e-mail]",
    "phone": null,
    "amount": "599.00",
    "currency": "SGD",
    "status": "pending",
    "purpose": null,
    "reference_number": "REF123",
    "payment_methods": [
        "paynow_online",
        "card"
    ],
    "url": "https://securecheckout.sandbox.hit-pay.com/payment-request/@business/90f28b43.../checkout",
    "redirect_url": "https://test.com/success",
    "allow_repeated_payments": false,
    "expiry_date": null,
    "created_at": "2025-07-03T02:18:49",
    "updated_at": "2025-07-03T02:18:49"
}

Step 2: Presenting the Checkout UI

After the payment request is completed, your server must return the payment_request_id and URL values to the client. There are 2 ways to present the checkout UI: “Redirect to HitPay checkout” or “Present Drop-In UI.”

Option 1: Redirect to HitPay Checkout

Navigate your user to the URL, and HitPay will take care of the rest of the flow. Once the payment is completed, the user will be navigated back to the “redirect_url” that was configured during the payment request step, along with the status.

Option 2: Present the Drop-In UI

Unlike the redirect checkout page, the drop-in is embedded into your webpage, so your customer will never have to leave your site. To present this, you will need 2 values: “default_link” and “payment_request_id.” The default link value can be found in your Dashboard > Payment Links > Default link, and this value is fixed for all your payments.

Sample code for Drop-In UI can be found here.

Drop-in UI currently does not support Apple Pay.

Step 3: Handle Successful Payment

Once the payment is completed, the user will be redirected to the redirect_url defined in step 1. While you can use this redirect to show an “Order Success” screen to your users, you should not rely on it alone to mark orders as paid. The redirect_url can be triggered by anyone, so always use webhooks to securely confirm payment before fulfilling orders.

What is a Webhook?

Webhook is a POST request sent from HitPay’s server to your server about the payment confirmation. If you are using HitPay APIs to integrate into your e-commerce checkout, you must mark your order as paid ONLY after the webhook is received and validated.

Register Your Webhook

To receive payment notifications, you need to register a webhook URL from your HitPay Dashboard:

1. Navigate to Developers > Webhook Endpoints in your dashboard
2. Click on New Webhook
3. Enter a name and your webhook URL
4. Select the payment_request.completed event
5. Save your webhook configuration

Webhook Payload

When a payment is completed, HitPay sends a JSON payload to your registered webhook URL with the following headers:

HTTP Header	Description
Hitpay-Signature	HMAC-SHA256 signature of the JSON payload, using your salt value
Hitpay-Event-Type	completed
Hitpay-Event-Object	payment_request
User-Agent	HitPay v2.0

Sample Webhook Payload

Show View full payload

{
  "id": "9e9be41b-2866-4307-8621-e35c633c431f",
  "name": "John Doe",
  "email": "[e-mail]",
  "phone": "[phone]",
  "amount": "100.00",
  "currency": "SGD",
  "status": "completed",
  "purpose": "Order #12345",
  "reference_number": "REF123",
  "payment_methods": ["card", "paynow_online"],
  "url": "https://securecheckout.hit-pay.com/payment-request/@business/9e9be41b.../checkout",
  "redirect_url": "https://example.com/success",
  "created_at": "2025-04-06T15:17:21",
  "updated_at": "2025-04-06T15:17:43",
  "payments": [
    {
      "id": "9e9be41c-2869-4b8c-8701-6c44af86b7d0",
      "status": "succeeded",
      "buyer_email": "[e-mail]",
      "currency": "sgd",
      "amount": "100.00",
      "refunded_amount": "0.00",
      "payment_type": "card",
      "fees": "4.15",
      "created_at": "2025-04-06T15:17:21",
      "updated_at": "2025-04-06T15:17:43"
    }
  ]
}

Validating the Webhook

To ensure the webhook is authentic, validate the Hitpay-Signature header:

1. Receive the JSON payload and Hitpay-Signature from the request
2. Use your salt value (from the dashboard) as the secret key
3. Compute HMAC-SHA256 of the JSON payload using your salt
4. Compare the computed signature with Hitpay-Signature - they must match

PHP

function validateWebhook($payload, $signature, $salt) {
    $computedSignature = hash_hmac('sha256', $payload, $salt);
    return hash_equals($computedSignature, $signature);
}

// Usage
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_HITPAY_SIGNATURE'];
$salt = 'your_salt_from_dashboard';

if (validateWebhook($payload, $signature, $salt)) {
    $data = json_decode($payload, true);
    // Process the payment confirmation
    // Mark order as paid
} else {
    http_response_code(401);
    exit('Invalid signature');
}

Congrats! You have now successfully completed the payment integration.

FAQs

Do I pass a webhook URL in the API request?

No. The webhook parameter in the payment request API is deprecated and should not be used.

Instead, register your webhook URL from the HitPay Dashboard:

1. Go to Developers > Webhook Endpoints
2. Click New Webhook and enter your URL
3. Subscribe to payment_request.completed and any other events you need

The dashboard-based webhook system supports JSON payloads, multiple event types (refunds, orders, invoices, transfers), and centralized management across all your payment requests.

Webhook Signature Mismatch?

Possible reasons for signature mismatch:

• Ensure you are using the correct salt value from the correct environment (Sandbox or Production)
• Make sure you are computing the HMAC-SHA256 of the raw JSON payload
• Verify the signature is being read from the Hitpay-Signature header

Facing Invalid Business API Key Error

Possible reasons for this error:

• You are using a production key in the sandbox or a sandbox key in production. Make sure the API base URL is correct.
• You are missing headers. Ensure that you include both the ‘Content-Type’ and ‘X-Requested-With’ headers. Refer to this section again.

How do I handle cancelled or abandoned QR code payments?

QR code payments (PayNow, GrabPay, etc.) cannot be cancelled once generated — unlike card payments, there is no cancel endpoint. Even if the user leaves your checkout page, they may have already scanned or screenshotted the QR code.

Recommended approach:

1. When you generate a QR code, record the creation timestamp and treat the payment as "pending" on your end.
2. If you do not receive a successful payment webhook within 10–15 minutes of QR creation, you can safely assume the payment was abandoned and cancel the order on your side.

Why 10–15 minutes?

• PayNow QR codes are valid for 5 minutes — this is the window in which the customer must scan the code.
• However, once scanned, the customer's banking app may still allow them to complete the payment after the 5-minute mark.
• A 10–15 minute buffer from QR creation accounts for this delay.

UX tip: If your platform has a "Cancel" button, you can dismiss the QR screen for a smoother user experience, but your backend should still listen for webhooks for the full buffer period in case the payment completes.

Product Checklist

Ensure the following before moving to production

• Change the base URL for all API calls to https://api.hit-pay.com/v1/
• Finish paynow and other payment methods set up in production
• Update API keys and Salt values from the production dashboard
• If you are using Drop-In UI, update the default link to the production URL

API Rate Limits

HitPay enforces the following rate limits to ensure optimal performance and prevent abuse:

• General API Rate Limit: 400 requests per minute across all endpoints
• Payment Request Endpoint: 70 requests per minute (additional limit to prevent payment request misuse)

To avoid hitting rate limits and ensure reliable payment status updates, implement webhooks instead of polling the API for payment status. Use API status checks only as a fallback mechanism when webhooks fail.

Why does my charges `webhook status` show as failed?

If you are using a payment plugin, after every successful payment, a webhook is sent to your store to acknowledge the payment confirmation. Your order is marked as paid through this webhook.

A webhook status showing as "failed" indicates that Hitpay failed to communicate with your server. This can happen for the following reasons:

• Your store may have a security feature that blocked Hitpay's request.
• Your server was unavailable during this time.

To avoid this issue, ensure that you whitelist Hitpay's IP addresses:

• Production: 3.1.13.32, 52.77.254.34
• Sandbox: 54.179.156.147

For further details, please review your store's debug logs.