> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Borderless QR

> Extend your embedded QR integration to accept cross-border payments. Display real-time currency conversion to international customers via the API.

This page extends the [Embedded QR Overview](/apis/guide/embedded-qr-code-payments/domestic-qr). 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.

<Frame>
  <iframe src="https://v0-hitpay-borderless-qr-online-demo.vercel.app/" width="100%" height="600px" style={{ border: "none", borderRadius: "8px" }} title="Borderless QR Live Demo" />
</Frame>

***

## What Changes From the Overview

The [Overview](/apis/guide/embedded-qr-code-payments/domestic-qr) covers same-currency payments where the merchant and customer share the same currency. 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     |

<Note>
  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.
</Note>

***

## How It Works

<Steps>
  <Step title="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)
  </Step>

  <Step title="System detects currency mismatch">
    HitPay detects that your merchant currency (SGD) differs from the payment method's native currency (PHP)
  </Step>

  <Step title="Automatic currency conversion">
    The amount is automatically converted using the mid-market exchange rate
  </Step>

  <Step title="QR code generated in customer's currency">
    The QR code displays the amount in the customer's local currency (PHP)
  </Step>
</Steps>

***

## API Request

Use the same endpoint as Domestic QR: [**POST /v1/payment-requests**](/apis/payment-request/create-request)

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):

```json theme={"system"}
{
  "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:

<Accordion title="Example Response for Borderless QR Payment Request">
  ```json theme={"system"}
  {
    "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"
    }
  }
  ```
</Accordion>

### 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                 |

<Info>
  **Display both amounts to your customer.** You can show "SGD 10.00 = PHP 455.70" to help customers understand the conversion before scanning.
</Info>

***

## 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

<CodeGroup>
  ```php PHP theme={"system"}
  // 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
  ```

  ```javascript JavaScript theme={"system"}
  // 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
  ```
</CodeGroup>

<Note>
  **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.
</Note>

***

## Webhook Handling

Webhook handling is identical to the [Overview](/apis/guide/embedded-qr-code-payments/domestic-qr#step-4-handle-webhooks-server-communication). The payment amount in the webhook payload will be in your **merchant currency** (the original amount you requested).

***

## FAQs

<AccordionGroup>
  <Accordion title="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:**

    ```json theme={"system"}
    {
      "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
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>