USD Wrapping

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

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.

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

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.

Collection

Flow overview

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.

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

{
  "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

{
  "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

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

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

Yes. After enabling USD Wrapping, use the /global/cashier/collect/apply API and set the currency parameter to USD.

Quick start

Merchant Guide

Common Payment

Global Payment

Unified API

End To End Testing

Appendix

Merchant FAQ

What is USD Wrapping?

Business value

How it works

Supported regions and payment methods

Collection

Flow overview

Integration steps

Step 1: Obtain the appId for USD

Step 2: Select the USD payment method for the target region

Step 3: Call the collection API

Request example

Response example

Exchange rate fields in async notifications

FAQ

​What is USD Wrapping?

​Business value

​How it works

​Supported regions and payment methods

​Collection

​Flow overview

​Integration steps

Step 1: Obtain the appId for USD

Step 2: Select the USD payment method for the target region

Step 3: Call the collection API

​Request example

​Response example

​Exchange rate fields in async notifications

​FAQ

​Related Topics

What is USD Wrapping?

Business value

How it works

Supported regions and payment methods

Collection

Flow overview

Integration steps

Request example

Response example

Exchange rate fields in async notifications

FAQ

Related Topics