HitPay Product Guide and API docs.

Introduction

Embedded QR Code Payments allow seamless integration of QR payments directly into your platform without redirecting the users away.

Core Concept

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

Create a Payment Request

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

Generate and Present the QR Code

Once the payment request is ready, generate and present the QR code to the user.

Client Scans and Initiates Payment

The client scans the QR code and initiates the payment through their banking app.

Handle Webhooks and Server Communication

After the payment is processed, handle webhooks to receive payment notifications and manage server-client communication.

Supported Methods

Please note that not all payment methods support embedded QR Codes. Here is the list of methods that support QR Codes:

Payment Method	Code
PayNow	paynow_online
ShopeePay	shopee_pay
QRIS	doku_qris (Indonesia merchants), ifpay_qris (other merchants)
WeChatPay	wechat_pay
VietQR	vietqr_payme
PromptPay	opn_prompt_pay
TrueMoney	opn_true_money_qr
GrabPay	grabpay_direct
GrabPay PayLater	grabpay_paylater
UPI	upi_qr
Gcash	gcash_offline
QRPH	qrph_netbank
Touch ‘n Go	touch_n_go
ShopBack	Coming Soon

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 a 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.

Endpoint

POST /v1/payment-requests Creates a payment request and generates a QR code for the paynow_online payment method.

Request Parameters

Parameter	Type	Description
amount	string	Required. The amount to be paid.
currency	string	Required. The currency of the payment (e.g., “sgd”).
payment_methods[]	array	Required. Specify `paynow_online` as the payment method.
generate_qr	boolean	Required. Set to `true` to generate the QR code.
name	string	Optional. The name of the customer.
email	string	Optional. The email of the customer.
phone	string	Optional. The phone number of the customer.
purpose	string	Optional. The purpose of the payment.
reference_number	string	Optional. A reference number for the payment.

Example Request

{
  "amount": "123.00",
  "currency": "sgd",
  "payment_methods": ["paynow_online"],
  "generate_qr": true,
  "expiry_date": "2024-06-01T14:37:11"
}

Response

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 Embedded 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
  }
}

Step 2: Generate and Present the QR Code

Once the payment request is created, generate the QR code using the response data and present it to the user.

Note for Sandbox Testing:In sandbox, the qr_code value returned may be a URL (e.g. https://securecheckout.sandbox.hit-pay.com/...) instead of the raw PayNow QR string. This is intended to help you test the flow using a standard QR code reader or by visiting the link directly in a browser.
In production, the qr_code will be a raw PayNow payload string that you should convert into a scannable QR code for use with banking apps.

Step 3: Client Scans and Initiates Payment

The client scans the presented QR code with their banking app and initiates the payment process.

Step 4: Handle Webhooks and Server Communication

After the payment is processed, handle webhooks to receive payment notifications and manage server-client communication to update the payment status in your system.

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;
}

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

Embedded QR Codes

Introduction

Core Concept

Create a Payment Request

Generate and Present the QR Code

Client Scans and Initiates Payment

Handle Webhooks and Server Communication

Supported Methods

Authentication

Step 1: Create a Payment Request

Endpoint

Request Parameters

Example Request

Response

Step 2: Generate and Present the QR Code

Step 3: Client Scans and Initiates Payment

Step 4: Handle Webhooks and Server Communication

What is a Webhook?

Handling the webhook

Sample Webhook Payload

Validating a Webhook

FAQs

Getting Started

Developers

Point of Sale

Online Store

Tools

Manage Payments

Integrations

Appendix

​Introduction

​Core Concept

Create a Payment Request

Generate and Present the QR Code

Client Scans and Initiates Payment

Handle Webhooks and Server Communication

​Supported Methods

​Authentication

​Step 1: Create a Payment Request

​Endpoint

​Request Parameters

​Example Request

​Response

​Step 2: Generate and Present the QR Code

​Step 3: Client Scans and Initiates Payment

​Step 4: Handle Webhooks and Server Communication

​What is a Webhook?

​Handling the webhook

​Sample Webhook Payload

​Validating a Webhook

​FAQs

Introduction

Core Concept

Supported Methods

Authentication

Step 1: Create a Payment Request

Endpoint

Request Parameters

Example Request

Response

Step 2: Generate and Present the QR Code

Step 3: Client Scans and Initiates Payment

Step 4: Handle Webhooks and Server Communication

What is a Webhook?

Handling the webhook

Sample Webhook Payload

Validating a Webhook

FAQs