HitPay Product Guide and API docs.

Core Concept

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

Create a Payment Request

The first step is to create a payment request in your system.

Present the Checkout Page

Once the payment request is ready, present the checkout page to the user.

Handle Webhooks

After the payment is processed, handle webhooks to receive payment notifications.

Authentication

Before integration, it’s essential to understand how Hitpay APIs are authenticated. Hitpay utilizes API keys to grant access to the API. You can locate this key in your dashboard under “API keys.” Hitpay requires the API key to be included in all API requests to the server. This key should be placed in a header that follows the format shown below: X-BUSINESS-API-KEY: meowmeowmeow

$request->setHeaders(array(
  'X-BUSINESS-API-KEY' => 'meowmeowmeow',
  'Content-Type' => 'application/x-www-form-urlencoded',
  'X-Requested-With' => 'XMLHttpRequest'
));

API keys should be kept confidential and only stored on your servers. Do not store it 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

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

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, wechat, alipay, grabpay, fave_duit, shopback, atome (Local Payment Methods) (Cross-border Payment Methods)
currency	Currency related to the payment	SGD
email	Buyer’s email	foo@example.com
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
webhook	URL where our server does a POST request after a payment is completed	https://example.com/webhook
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

$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' => 'tom@test.com',
  'redirect_url' => 'https://test.com/success',
  'reference_number' => 'REF123',
  'webhook' => 'https://test.com/webhook',
  'currency' => 'SGD',
  'amount' => '599')));$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'X-BUSINESS-API-KEY' => 'meowmeowmeow',
  '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": "tom@test.com",
    "phone": null,
    "amount": "599.00",
    "currency": "SGD",
    "status": "pending",
    "purpose": null,
    "reference_number": null,
    "payment_methods": [
        "paynow_online",
        "card",
        "wechat",
        "alipay"
    ],
    "url": "https://securecheckout.sandbox.hit-pay.com/payment-request/@amazone-prime-pte-ltd/90f28b43-2cff-4f86-a29e-15697424b3e7/checkout",
    "redirect_url": "https://test.com/success",
    "webhook": "https://test.com/webhook",
    "send_sms": true,
    "send_email": true,
    "sms_status": "pending",
    "email_status": "pending",
    "allow_repeated_payments": true,
    "expiry_date": null,
    "created_at": "2020-07-03T02:18:49",
    "updated_at": "2020-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.”

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. PayNow Checkout Page

Step 3: Handle Successful payment

Once the payment is completed, the user will be redirected to “redirect_url” defined in step 1.

You might be tempted to just use the “redirect_url” to mark your order as completed and show an “Order Success” screen to your users but this could be a security issue. You must always use the “Webhook” to confirm your order.

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.

Handling the webhook

Create an endpoint (E.g. /payment-confirmation/webhook) in your server that accepts POST requests. This request is application/x-www-form-urlencoded.
Validate the webhook data using your salt value
Return HTTP status code 200 to Hitpay
Mark your order as paid
Sample webhook payload data

Sample Webhook Payload

payment_id=92965a2d-ece3-4ace-1245-494050c9a3c1&payment_request_id=92965a20-dae5-4d89-a452-5fdfa382dbe1&reference_number=ABC123&phone=&amount=599.00&currency=SGD&status=completed&hmac=330c34a6a8fb9ddb75833620dedb94bf4d4c2e51399d346cbc2b08c381a1399c

Webhook fields Following fields are sent with the webhook request:

Parameter	Description
payment_id	Payment ID
payment_request_id	Payment request ID
phone	Buyer’s phone number
amount	Amount related to the payment
currency	Currency related to the payment
status	Payment status (completed / failed)
reference_number	Arbitrary reference number mapped during payment request creation
hmac	Message Authentication code of this webhook request

Validating a Webhook

To validate a webhook payload from HitPay, follow these steps:

Payload Extraction: Extract the key-value pairs from the webhook payload. For example:

payment_id=92965a2d-ece3-4ace-1245-494050c9a3c1&payment_request_id=92965a20-dae5-4d89-a452-5fdfa382dbe1&reference_number=ABC123&phone=&amount=599.00&currency=SGD&status=completed&hmac=330c34a6a8fb9ddb75833620dedb94bf4d4c2e51399d346cbc2b08c381a1399c

Exclude HMAC and Values: Remove the "hmac" key and its corresponding value from the extracted payload. For example:
Concatenation and Sorting: Concatenate the keys and values from the remaining key-value pairs without using "&" and "=", and arrange them in alphabetical order of the keys. For example:

amount1.00currencySGDpayment_id91d94138-b0b5-4ba0-b78c-babc59776876payment_request_id91d94124-0d1c-4fb4-921e-51953793106cphonereference_number201000000Dstatuscompleted

Signature Generation: Use the HMAC-SHA256 algorithm along with the secret salt from your dashboard to generate a signature for the concatenated string. This signature will be unique to this payload.
Comparison and Validation: Compare the generated signature with the HMAC value present in the original payload, both values must match.

By following these steps, you can ensure the authenticity and integrity of the webhook payload received from HitPay. This process guarantees that the payload can be trusted and processed securely. Sample Code

function generateSignatureArray($secret, array $args) {   
  $hmacSource = [];        
  foreach ($args as $key => $val) {
    $hmacSource[$key] = "{$key}{$val}";
  }
  ksort($hmacSource);
  $sig            = implode("", array_values($hmacSource));
  $calculatedHmac = hash_hmac('sha256', $sig, $secret); 

  return $calculatedHmac;
}

Congrats! You have now successfully completed the payment integration.

Native QR Code

This API in currently in public BETA

The Native QR Code feature enables the generation of QR codes that can be scanned using various banking apps, facilitating a seamless payment experience for users. This functionality is particularly beneficial for mobile-based transactions where users can easily scan a code to initiate payments. Additionally, the use of native QR codes allows for embedding payment options directly into various customer-facing materials without the need for redirecting users through a payment request URL (Hosted Checkout), simplifying the payment process significantly. Specify paynow_online as the payment method, set generate_qr to true, and manage expiration settings if needed. The response will include a qr_code_data object, which contains the data to be converted into a scannable QR code (qr_code).

Example Response for Native QR Code Payment Request

Copy
Ask AI
{
"id": "9c262fb5-f3cd-4187-8c3e-fbe20730b9c6",
"name": null,
"email": null,
"phone": null,
"amount": "123.00",
"currency": "sgd",
"is_currency_editable": false,
"status": "pending",
"purpose": null,
"reference_number": null,
"payment_methods": [
  "paynow_online"
],
"url": "https://securecheckout.hit-pay.com/payment-request/@nitinmuthyala/9c262fb5-f3cd-4187-8c3e-fbe20730b9c6/checkout",
"redirect_url": null,
"webhook": null,
"send_sms": true,
"send_email": false,
"sms_status": "pending",
"email_status": "pending",
"allow_repeated_payments": false,
"expiry_date": null,
"address": null,
"line_items": null,
"executor_id": null,
"created_at": "2024-05-28T14:37:11",
"updated_at": "2024-05-28T14:37:11",
"qr_code_data": {
  "qr_code": "00020101021226550009SG.PAYNOW010120210201605883W030100414202405281445315204000053037025406123.005802SG5905Nitin6009Singapore62290125DICNP17168782314914MWULPX63043561",
  "qr_code_expiry": null
}
}

FAQs

Webhook Signature Mismatch?

Facing Invalid Business API Key Error

Product Checklist

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

Getting Started

Developers

Point of Sale

Online Store

Tools

Manage Payments

Integrations

Appendix

Online Payments

Core Concept

Create a Payment Request

Present the Checkout Page

Handle Webhooks

Authentication

Step 1: Create Payment Request

Endpoint

Request Parameters

Response

Step 2: Presenting the Checkout UI

Step 3: Handle Successful payment

What is a Webhook?

Handling the webhook

Sample Webhook Payload

Validating a Webhook

Native QR Code

FAQs

Getting Started

Developers

Point of Sale

Online Store

Tools

Manage Payments

Integrations

Appendix

​Core Concept

Create a Payment Request

Present the Checkout Page

Handle Webhooks

​Authentication

​

​Step 1: Create Payment Request

​Endpoint

​Request Parameters

​Response

​Step 2: Presenting the Checkout UI

​Step 3: Handle Successful payment

​What is a Webhook?

​Handling the webhook

​Sample Webhook Payload

​Validating a Webhook

​Native QR Code

​FAQs

Core Concept

Authentication

Step 1: Create Payment Request

Endpoint

Request Parameters

Response

Step 2: Presenting the Checkout UI

Step 3: Handle Successful payment

What is a Webhook?

Handling the webhook

Sample Webhook Payload

Validating a Webhook

Native QR Code

FAQs