HitPay Product Guide and API docs.

Introduction

Borderless QR enables you to accept payments from international customers using their local payment methods, while you receive payouts in your home currency. The system automatically handles currency conversion using real-time exchange rates.

Business Overview

Learn about Borderless QR for POS and business use cases

Domestic QR

Same-currency embedded QR payments

Difference from Domestic QR

Domestic QR generates payment codes in your merchant currency for domestic customers. Borderless QR automatically converts the amount and generates payment codes in the customer’s local currency, enabling seamless cross-border transactions.

Feature	Domestic QR	Borderless QR
Currency	Same currency (merchant = customer)	Cross-currency (merchant’s currency differs from payment method)
Exchange Rate	N/A	Mid-market rate at transaction time
Response Fields	`qr_code`, `qr_code_expiry`	Adds `qr_amount`, `qr_currency`, `fx_rate`
Use Case	Domestic payments	International tourists and cross-border customers

Supported Payment Methods

The following payment methods support cross-border QR payments:

Payment Method	Code	Native Currency	Country
PayNow	`paynow_online`	SGD	Singapore
QRPH	`qrph_netbank`	PHP	Philippines
GCash	`gcash_qr`	PHP	Philippines
PromptPay	`opn_prompt_pay`	THB	Thailand
TrueMoney	`opn_true_money_qr`	THB	Thailand
QRIS	`doku_qris` / `ifpay_qris`	IDR	Indonesia
Touch ‘n Go	`touch_n_go`	MYR	Malaysia
ShopeePay	`shopee_pay`	Various	Multiple

Only payment methods from countries different from your merchant country will trigger cross-border conversion. For example, a Singapore merchant using paynow_online (SGD) will get standard QR behavior, but using gcash_qr (PHP) will trigger Borderless QR with currency conversion.

How It Works

Select a cross-border payment method

Choose a payment method from a different country (e.g., a Singapore merchant selecting gcash_qr for Philippine customers)

System detects currency mismatch

HitPay detects that your merchant currency (SGD) differs from the payment method’s native currency (PHP)

Automatic currency conversion

The amount is automatically converted using the mid-market exchange rate

QR code generated in customer's currency

The QR code displays the amount in the customer’s local currency (PHP)

API Request

Use the same endpoint as Domestic QR: POST /v1/payment-requests The only difference is the payment method you specify. When you use a cross-border payment method, the system automatically enables Borderless QR behavior.

Request Parameters

Parameter	Type	Description
amount	string	Required. The amount in your merchant currency.
currency	string	Required. Your merchant currency (e.g., “sgd”).
payment_methods[]	array	Required. Specify exactly one cross-border payment method (e.g., `["gcash_qr"]`). Multiple methods are not supported for QR generation.
generate_qr	boolean	Required. Must be `true` to generate the QR code.
name	string	Optional. Customer name.
email	string	Optional. Customer email.
phone	string	Optional. Customer phone number.
purpose	string	Optional. Payment purpose.
reference_number	string	Optional. Your reference number.

Example Request

A Singapore merchant (SGD) accepting payment from a Philippine customer via GCash (PHP):

{
  "amount": "10.00",
  "currency": "sgd",
  "payment_methods": ["gcash_qr"],
  "generate_qr": true,
  "purpose": "Order #12345"
}

API Response

The response includes additional fields in qr_code_data for cross-border payments:

Example Response for Borderless QR Payment Request

{
  "id": "9c262fb5-f3cd-4187-8c3e-fbe20730b9c6",
  "name": null,
  "email": null,
  "phone": null,
  "amount": "10.00",
  "currency": "sgd",
  "is_currency_editable": false,
  "status": "pending",
  "purpose": "Order #12345",
  "reference_number": null,
  "payment_methods": ["gcash_qr"],
  "url": "https://securecheckout.hit-pay.com/payment-request/@merchant/9c262fb5-f3cd-4187-8c3e-fbe20730b9c6/checkout",
  "redirect_url": null,
  "webhook": null,
  "send_sms": false,
  "send_email": false,
  "sms_status": "pending",
  "email_status": "pending",
  "allow_repeated_payments": false,
  "expiry_date": null,
  "created_at": "2024-05-28T14:37:11",
  "updated_at": "2024-05-28T14:37:11",
  "qr_code_data": {
    "qr_code": "00020101021226...",
    "qr_code_expiry": null,
    "qr_image_mime": "image/png",
    "qr_amount": "455.70",
    "qr_currency": "php",
    "fx_rate": "45.57"
  }
}

Borderless QR Response Fields

The qr_code_data object includes these additional fields for cross-border payments:

Field	Type	Description
`qr_amount`	string	The converted amount in the customer’s local currency
`qr_currency`	string	The customer’s local currency code (e.g., “php”)
`fx_rate`	string	The exchange rate used for conversion

Display both amounts to your customer. You can show “SGD 10.00 = PHP 455.70” to help customers understand the conversion before scanning.

Displaying Currency Conversion

When presenting the QR code to your customer, display the currency conversion details to build trust and ensure transparency.

Response Fields to Use

Field	Example	Description
`amount` + `currency`	”10.00” + “sgd”	Your original charge amount (merchant currency)
`qr_code_data.qr_amount`	”455.70”	Converted amount the customer will pay
`qr_code_data.qr_currency`	”php”	Customer’s local currency
`qr_code_data.fx_rate`	”45.57”	Exchange rate used (1 merchant currency = X local currency)

Recommended Display Format

Show customers both amounts and the exchange rate before they scan:

Total: SGD 10.00
Pay: PHP 455.70
Rate: 1 SGD = 45.57 PHP

Code Examples

// After receiving the API response
$response = json_decode($apiResponse, true);

$merchantAmount = $response['amount'];
$merchantCurrency = strtoupper($response['currency']);
$customerAmount = $response['qr_code_data']['qr_amount'];
$customerCurrency = strtoupper($response['qr_code_data']['qr_currency']);
$fxRate = $response['qr_code_data']['fx_rate'];

// Format display string
$displayText = sprintf(
    "Total: %s %s\nPay: %s %s\nRate: 1 %s = %s %s",
    $merchantCurrency,
    $merchantAmount,
    $customerCurrency,
    $customerAmount,
    $merchantCurrency,
    $fxRate,
    $customerCurrency
);

echo $displayText;
// Output:
// Total: SGD 10.00
// Pay: PHP 455.70
// Rate: 1 SGD = 45.57 PHP

Check for borderless fields first. The qr_amount, qr_currency, and fx_rate fields only appear for cross-border payments. For same-currency payments, display only the original amount.

Webhook Handling

Webhook handling is identical to Domestic QR. The payment amount in the webhook payload will be in your merchant currency (the original amount you requested).

FAQs

Why am I getting 'The selected payment method is unavailable for your account or the currency is invalid'?

This error typically occurs when generate_qr is not set to true in your request. For Borderless QR payments, you must include "generate_qr": true in your API request body.Correct request:

{
  "amount": "10.00",
  "currency": "sgd",
  "payment_methods": ["gcash_qr"],
  "generate_qr": true
}

Other possible causes:

Multiple payment methods specified - When using generate_qr: true, you must specify exactly one payment method in the array
The payment method is not enabled in your HitPay dashboard
The payment method doesn’t support QR code generation
You’re using a sandbox API key in production or vice versa

How is the exchange rate determined?

The exchange rate is based on the mid-market exchange rate at the time the payment request is created. The mid-market rate is the average of buy and sell rates between two currencies.

What fees apply to Borderless QR payments?

Merchants are charged a 1.5% payment processing fee for cross-border QR payments, plus applicable FX fees based on your country of registration and settlement currency. Customers are not charged any additional fees.

How do refunds work?

When processing a refund, the customer receives the exact amount they originally paid in their local currency. The exchange rate from the original transaction is used—there is no recalculation based on current rates.

What if my currency matches the payment method?

If your merchant currency matches the payment method’s native currency (e.g., SGD merchant using PayNow), the response will follow standard QR behavior without the qr_amount, qr_currency, and fx_rate fields.

Do I need to calculate currency conversion myself?

No. Simply specify the amount in your merchant currency. HitPay automatically handles the conversion and returns the converted amount in the response.

What is the payout period for cross-border payments?

Cross-border payments are credited to your HitPay Balance on a T+1 calendar day basis.

Production Checklist

Before going live:

Change the base URL to https://api.hit-pay.com/v1/
Enable cross-border payment methods in your production dashboard
Update API keys and salt values from production
Register webhook URLs in production
Test the full payment flow end-to-end

Getting Started

Developers

Point of Sale

Online Store

Tools

Manage Payments

Integrations

Appendix

Borderless QR

Introduction

Business Overview

Domestic QR

Difference from Domestic QR

Supported Payment Methods

How It Works

API Request

Request Parameters

Example Request

API Response

Borderless QR Response Fields

Displaying Currency Conversion

Response Fields to Use

Recommended Display Format

Code Examples

Webhook Handling

FAQs

Getting Started

Developers

Point of Sale

Online Store

Tools

Manage Payments

Integrations

Appendix

​Introduction

Business Overview

Domestic QR

​Difference from Domestic QR

​Supported Payment Methods

​How It Works

​API Request

​Request Parameters

​Example Request

​API Response

​Borderless QR Response Fields

​Displaying Currency Conversion

​Response Fields to Use

​Recommended Display Format

​Code Examples

​Webhook Handling

​FAQs

Introduction

Difference from Domestic QR

Supported Payment Methods

How It Works

API Request

Request Parameters

Example Request

API Response

Borderless QR Response Fields

Displaying Currency Conversion

Response Fields to Use

Recommended Display Format

Code Examples

Webhook Handling

FAQs