HitPay Product Guide and API docs.

This page extends the Embedded QR Overview. If you haven’t set up embedded QR payments yet, start there first.

What is Borderless QR?

Once your base integration is in place, Borderless QR lets you accept payments from international customers using their local payment methods. The API automatically converts the amount and returns the converted values :

qr_amount
qr_currency
fx_rate

So you can display the conversion clearly in your UI before the customer scans. Your payouts are always in your merchant currency. HitPay handles the conversion.

Live Demo

Try the interactive demo to see Borderless QR in action — including real-time currency conversion display.

How Borderless QR Differs From Standard Embedded QR

Standard embedded QR payments work within a single currency — the merchant and customer share the same currency, so no conversion is needed. Borderless QR automatically converts the amount and generates payment codes in the customer’s local currency, enabling seamless cross-border transactions.

Feature	Overview (same-currency)	Borderless QR (cross-border)
Currency	Merchant = customer	Merchant 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
DuitNow	`duitnow`	MYR	Malaysia
ShopeePay	`shopee_pay`	Various	Multiple
VietQR	`vietqr_zalopay`	VND	Vietnam
ZaloPay	`zalopay`	VND	Vietnam

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

// After receiving the API response
const response = await apiResponse.json();

const merchantAmount = response.amount;
const merchantCurrency = response.currency.toUpperCase();
const customerAmount = response.qr_code_data.qr_amount;
const customerCurrency = response.qr_code_data.qr_currency.toUpperCase();
const fxRate = response.qr_code_data.fx_rate;

// Format display string
const displayText = `Total: ${merchantCurrency} ${merchantAmount}
Pay: ${customerCurrency} ${customerAmount}
Rate: 1 ${merchantCurrency} = ${fxRate} ${customerCurrency}`;

console.log(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 the Overview. The payment amount in the webhook payload will be in your merchant currency (the original amount you requested).

Refunds

Refund support by payment method

Singapore
Malaysia
Philippines
Indonesia

Payment Method	Refund Processing Time	Refund amount deducted from?	Max Refund Period
Cards	3 - 5 Business Days	Card Balance Cards (by Adyen) Balance	None
PayNow QR	Instant	HitPay Balance	30 Days
GrabPay	Instant	HitPay Balance	30 Days
GrabPay PayLater	Instant	HitPay Balance	30 Days
ShopeePay	Instant	HitPay Balance	30 Days
SPayLater	Instant	HitPay Balance	30 Days
ShopBack Pay	Instant	HitPay Balance	30 Days
Atome	Instant	HitPay Balance	30 Days
WeChatPay	Not Supported	-	-
UPI	Instant	HitPay Balance	30 Days
QRPH	Instant	HitPay Balance	30 Days
QRIS	Not Supported	-	-
PromptPay	Not Supported	-	-
TrueMoney	Instant	HitPay Balance	30 Days
LINE Pay	Instant	HitPay Balance	30 Days
PayCo, KakaoPay, LINEPay	Instant	HitPay Balance	30 Days
VietQR, ZaloPay	Instant	HitPay Balance	30 Days

Payment Method	Refund Processing Time	Refund amount deducted from?	Max Refund Period
Cards	3 - 5 Business Days	Stripe Balance	None
FPX	3 - 5 Business Days	Stripe Balance	30 Days
Touch 'n Go	Maximum 7 - 14 Days	HitPay Balance	30 Days
ShopeePay	Instant	HitPay Balance	30 Days
SPayLater	Instant	HitPay Balance	30 Days
GrabPay	Instant	HitPay Balance	30 Days
GrabPay PayLater	Instant	HitPay Balance	30 Days
Atome	Not Supported	-	-
WeChat Pay	Not Supported	-	-
DuitNow	Not Supported	-	-
ShopBack Pay	Instant	HitPay Balance	30 Days
MayBank QR	Maximum 7 - 14 Days	HitPay Balance	30 Days
AliPay	Instant	HitPay Balance	30 Days
QRIS	Not Supported	-	-
PromptPay	Not Supported	-	-
TrueMoney	Instant	HitPay Balance	30 Days
LINE Pay	Instant	HitPay Balance	30 Days
PayCo, KakaoPay, LINEPay	Instant	HitPay Balance	30 Days
VietQR, ZaloPay	Instant	HitPay Balance	30 Days

Payment Method	Refund Processing Time	Refund amount deducted from?	Max Refund Period
Cards	3 - 5 Business Days	HitPay Balance	None
QRPH	Not Supported	-	-
GCash	Instant	HitPay Balance	30 Days
ShopeePay	Instant	HitPay Balance	30 Days
SPayLater	Instant	HitPay Balance	30 Days
Unionbank Online	Not Supported	-	-
PESONet	Not Supported	-	-
BillEase	Instant	HitPay Balance	30 Days
GrabPay	Instant	HitPay Balance	30 Days
InstaPay	Not Supported	-	-
Over the counter payments	Not Supported	-	-
WeChatPay	Not Supported	-	-
QRIS	Not Supported	-	-
PromptPay	Not Supported	-	-
TrueMoney	Instant	HitPay Balance	30 Days
LINE Pay	Instant	HitPay Balance	30 Days
PayCo, KakaoPay, LINEPay	Instant	HitPay Balance	30 Days
VietQR, ZaloPay	Instant	HitPay Balance	30 Days

Payment Method	Refund Processing Time	Refund amount deducted from?	Max Refund Period
Cards	Instant	Doku Balance	Not Applicable
Shopee Pay	Instant	Doku Balance	Not Applicable
Ovo	Not Available	-	-
QRIS	Not Available	-	-
DOKU Wallet	Not Available	-	-
Virtual Account	Not Available	-	-
Alfamart Convenience Store	Not Available	-	-
Indomaret Convenience Store	Not Available	-	-

What happens when a refund is processed

When a charge is made in a currency other than your home currency, the refund works differently from a standard same-currency refund. Example scenario: A Singapore merchant (home currency SGD) accepts a MYR 100.00 payment from a Malaysian customer.

What the customer receives

The refund is issued in the charge currency — MYR 100.00 in this example. The customer's payment provider handles the funds in MYR, so they receive exactly what they paid.

What balance is debited

The refund is deducted from your home currency wallet. For a Singapore merchant, that means SGD is deducted — not MYR. Because the charge currency (MYR) differs from your home currency (SGD), HitPay converts the refund amount at the live exchange rate at the time of refund — not the rate from when the original charge was made. This can result in a small FX gain or loss depending on how rates have moved between the charge and refund.

If your home currency matches the charge currency (e.g., a Singapore merchant charging SGD), no currency conversion is needed and the exact charge amount is deducted from your SGD wallet.

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?

Refunds are issued in the charge currency (e.g., SGD) and deducted from your home currency wallet. If your home currency matches the charge currency (e.g., a Singapore merchant charging SGD), there is no FX conversion. If they differ, the live rate at refund time is used — not the rate from the original charge. Not all borderless QR payment methods support refunds — see the Refund support table for details.

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

Finance

Manage Payments

Integrations

Appendix

Borderless QR via API

What is Borderless QR?

Live Demo

How Borderless QR Differs From Standard Embedded 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

Refunds

Refund support by payment method

What happens when a refund is processed

What the customer receives

What balance is debited

FAQs

​What is Borderless QR?

​Live Demo

​How Borderless QR Differs From Standard Embedded 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

​Refunds

​Refund support by payment method

​What happens when a refund is processed

​What the customer receives

​What balance is debited

​FAQs

What is Borderless QR?

Live Demo

How Borderless QR Differs From Standard Embedded 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

Refunds

Refund support by payment method

What happens when a refund is processed

What the customer receives

What balance is debited

FAQs