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

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

## What is USD Wrapping?

USD Wrapping 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 Wrapping, the presentment currency is USD.
  * **Settlement Currency**: The currency the merchant actually receives in their account. With USD Wrapping, 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.
</Tip>

### 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 Wrapping 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](/docs/en/api/version2/cashin_code_list).

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

<Card title="Step 1: Obtain the appId for USD" icon="key">
  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`.
  </Warning>
</Card>

<Card title="Step 2: Select the USD payment method for the target region" icon="list">
  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` |
</Card>

<Card title="Step 3: Call the collection API" icon="code">
  Use the USD endpoint `/usd/collect/apply` to create a collection order. Pass the `amount` in **USD**.
</Card>

### Request example

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

```json theme={null}
{
  "appId": 1088,
  "orderId": "M233323000099",
  "amount": "50.00",
  "phone": "08230219312",
  "email": "user@example.com",
  "name": "John Doe",
  "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.example.com/checkout",
    "sign": "base64-encoded-haipay-signature"
  }
}
```

### Exchange rate fields in async notifications

When a collection involves USD Wrapping 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.
</Tip>

## FAQ

<Accordion title="How do merchants know which payment methods support USD Wrapping?">
  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](/docs/en/api/version2/MerchantPaymentConfig) API to query the payment methods currently enabled for your account.
</Accordion>

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

<Accordion title="Do both collection and payout support USD Wrapping?">
  USD Wrapping covers a broader range of payment methods for collections. Payout support for USD Wrapping is more limited — refer to each region's documentation for specifics.
</Accordion>

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

<Accordion title="Does Global Cashier support USD Wrapping?">
  Yes. After enabling USD Wrapping, use the `/global/cashier/collect/apply` API and set the `currency` parameter to `USD`.
</Accordion>

## Related Topics

* [HaiPay Payment Methods by Region](/docs/en/api/version2/cashin_code_list)
* [HaiPay Common API](/docs/en/guide/api_description_guide)
* [HaiPay Configuration and Signature Guide](/docs/en/guide/config_settings_and_signature_rules_guide)