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

# USD-Denominated Payments

> Learn about HaiPay USD-Denominated Payments — merchants price and settle in USD while end users pay in their local currency, with HaiPay handling the currency conversion automatically.

## What is USD-Denominated Payments?

USD-Denominated Payments is HaiPay's cross-currency payment capability: **merchants price and settle in USD, while end users pay in their local currency (e.g., IDR, MYR, THB)**.

> [!TIP]
>
> **Two core concepts:**
>
> * **Presentment Currency**: The currency the end user sees and pays in at checkout. With USD-Denominated Payments, the presentment currency is USD.
> * **Settlement Currency**: The currency the merchant actually receives in their account. With USD-Denominated Payments, the settlement currency is also USD.
>
> The payment is processed through local payment rails behind the scenes, but both the merchant and the end user see the transaction denominated in USD throughout.

### Business value

* **One-stop USD collection and withdrawal for merchants** — no need to hold accounts in multiple local currencies
* **End users see USD pricing** — lowers the barrier for cross-border shoppers and eliminates mental currency conversion

### How it works

```mermaid theme={null}
sequenceDiagram
    participant M as Merchant
    participant H as HaiPay
    participant P as Payment Processing
    participant U as End User

    M->>H: Create collection order in USD
    H->>H: Query real-time exchange rate
    H->>P: Process payment
    P->>U: User completes payment
    U-->>P: Payment completed
    P-->>H: Payment success
    H-->>M: Order succeeded, USD balance credited
```

## Supported regions and payment methods

USD-Denominated Payments covers multiple regions, each providing corresponding USD bank codes. Below is a reference list of supported regions (refer to each region's documentation for the definitive list):

| Region | Local Currency | Supported Payment Methods | USD bankCode Examples |
| - | - | - | - |
| Indonesia | IDR | QR, E-wallets, VA Bank Transfer | `ID_QRIS_USD`, `ID_DANA_USD`, `ID_BRI_USD` |
| Japan | JPY | E-wallets, Bank Transfer | `JP_AU_PAY_USD`, `JP_GMO_AOZORA_USD` |
| Malaysia | MYR | Bank Transfer | `TNG_USD`, `BOOST_USD`, `FPX_USD` |
| Thailand | THB | QR, E-wallets | `TH_QR_USD`, `TH_TM_USD` |
| Vietnam | VND | QR, Bank Transfer | `VN_QR_USD`, `VN_BANK_USD` |
| South Korea | KRW | E-wallets, Bank Transfer | `KAKAOPAY_USD`, `KR_BANK_USD` |
| Singapore | SGD | QR | `PAYNOW_USD` |
| Global | — | Credit Card (VISA/MC/JCB), Google Pay, Apple Pay | `CREDIT_CARD`, `GOOGLE_PAY`, `APPLE_PAY` |

> For the full list, refer to each region's [payment method documentation](https://doc.haipay.net/docs/en/api/version2/cashin_code_list.md).

## Collection

### Flow overview

```mermaid theme={null}
flowchart LR
    A[Merchant creates USD order] --> B[HaiPay queries exchange rate]
    B --> C[Convert to local currency amount]
    C --> D[User pays in local currency]
    D --> E[Payment callback success]
    E --> F[Merchant USD balance credited]
```

### Integration steps

> **Step 1: Obtain the appId for USD**
>
> In the merchant portal under **Business Management → Payment Product Configuration**, obtain the appId and key pair for **USD**.
>
> > [!WARNING]
> >
> > The USD appId is separate from local currency appIds — do not mix them. Using the wrong appId will return error code `4011`.

> **Step 2: Select the USD payment method for the target region**
>
> Based on the end user's region, select the corresponding USD payment code (inBankCode). USD payment codes are typically formed by appending a `_USD` suffix to the local currency code (e.g., `ID_DANA_USD`, `TH_TM_USD`). Some bank codes do not include a region prefix (e.g., `TNG_USD`, `PAYNOW_USD`):
>
> | Region | Local Currency Code | USD Code |
> | - | - | - |
> | Indonesia | `DANA` | `ID_DANA_USD` |
> | Indonesia | `dynamic` (QRIS) | `ID_QRIS_USD` |
> | Japan | `AU_PAY` | `JP_AU_PAY_USD` |
> | Japan | `GMO_AOZORA` | `JP_GMO_AOZORA_USD` |

> **Step 3: Call the collection API**
>
> Use the USD endpoint `/usd/collect/apply` to create a collection order. Pass the `amount` in **USD**.

### Request example

**URL:** `POST /usd/collect/apply`

```json theme={null}
{
  "appId": 1088,
  "orderId": "M233323000099",
  "amount": "50.00",
  "phone": "02012345678",
  "email": "james.anderson@gmail.com",
  "name": "James Anderson",
  "inBankCode": "ID_DANA_USD",
  "payType": "EWALLET",
  "partnerUserId": "149597870",
  "sign": "base64-encoded-rsa-signature"
}
```

**Key fields:**

| Parameter | Description |
| - | - |
| `appId` | The business ID associated with USD |
| `amount` | Transaction amount in **USD** (accurate to two decimal places) |
| `inBankCode` | USD payment code (e.g., `ID_DANA_USD`) |
| `payType` | Payment type, paired with inBankCode (e.g., `EWALLET`) |

### Response example

```json theme={null}
{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {
    "orderId": "M233323000099",
    "orderNo": "6023071013539074",
    "payUrl": "https://pay.haipay.asia/cashier/1L9zQS2",
    "sign": "base64-encoded-haipay-signature"
  }
}
```

### Exchange rate fields in async notifications

When a collection involves USD-Denominated Payments currency conversion, the async notification (webhook) will include the following additional fields:

| Parameter | Type | Description |
| - | - | - |
| `originalCurrency` | String | The original currency of the order (e.g., `IDR`); populated when currency conversion is involved |
| `originalAmount` | String | The original amount in local currency (e.g., `2825000`); populated when currency conversion is involved |

> [!TIP]
>
> By comparing `amount` (USD amount) with `originalAmount` (local currency amount), merchants can calculate the effective exchange rate applied to the transaction.

## FAQ

> **How do merchants know which payment methods support USD-Denominated Payments?**
>
> Each region's payment method documentation lists the USD payment codes (typically with a `_USD` suffix). You can also call the [Get Merchant Payment Configuration](https://doc.haipay.net/docs/en/api/version2/MerchantPaymentConfig.md) API to query the payment methods currently enabled for your account.

> **Is the exchange rate determined at order creation or queried in real time?**
>
> The exchange rate is determined by HaiPay at the time of order creation. Merchants can preview the exchange rate before placing an order via the `/common/quote/v1/exchange-rate` API, but the actual rate is the one applied at order creation time.

> **Do both collection and payout support USD-Denominated Payments?**
>
> USD-Denominated Payments covers a broader range of payment methods for collections. Payout support for USD-Denominated Payments is more limited — refer to each region's documentation for specifics.

> **How is the local currency amount paid by the end user calculated?**
>
> Local currency amount paid by the end user = USD amount submitted by the merchant × exchange rate at order creation time. Merchants can retrieve the actual local currency amount paid via the `originalAmount` field in the async notification.

> **Does Global Cashier support USD-Denominated Payments?**
>
> Yes. After enabling USD-Denominated Payments, use the `/global/cashier/collect/apply` API and set the `currency` parameter to `USD`.

## Related Topics

* [HaiPay Payment Methods by Region](https://doc.haipay.net/docs/en/api/version2/cashin_code_list.md)
* [HaiPay Common API](https://doc.haipay.net/docs/en/guide/api_description_guide.md)
* [HaiPay Configuration and Signature Guide](https://doc.haipay.net/docs/en/guide/config_settings_and_signature_rules_guide.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.