Skip to main content
Gcashier Pay’s FX API lets you convert balances between supported currencies at real-time interbank rates. The process is a straightforward two-step flow: first request a quote to lock in a rate, then confirm the trade before the quote expires. Results are delivered both synchronously in the confirmation response and asynchronously via the sp3201 webhook. You can also query supported currency pairs and your full transaction history at any time.
All FX API calls require a valid accessToken in the request header, obtained after merchant onboarding is approved. Include it as: Authorization: Bearer <accessToken>.

​
Overview

1

Query supported currency pairs (sp2202)

Discover which sell/buy currency combinations are available for your account.
2

Request an FX quote (sp1201)

Lock in a rate for a specific amount and direction.
3

Execute the FX trade (sp1202)

Confirm the trade using the quoteId before it expires.
4

Receive the FX result webhook (sp3201)

Gcashier Pay posts the final settlement status to your callback URL.
5

Query FX history (sp2201)

Look up past transactions by quoteId or time range.

​
Step 1 — Query Supported Currency Pairs

Before requesting a quote, call POST /api/sp2202 to retrieve the currency pairs available on your account. This list can change as new corridors are activated, so query it dynamically rather than hard-coding pairs. 
{}
Each object in data represents a tradeable pair. sellCurrency is the currency you spend; buyCurrency is the currency you receive.

​
Step 2 — Request an FX Quote

Call POST /api/sp1201 to obtain a rate-locked quote. You specify either the sell amount or the buy amount — set lockDirection accordingly.
FieldRequiredDescription
merOrderNoMYour unique reference for this quote request
sellCurrencyOCurrency you are selling (optional if implied by buyCurrency)
buyCurrencyMCurrency you want to receive
lockDirectionMSELL = you specify how much to sell; BUY = you specify how much to buy
amountMThe amount to lock, in the currency implied by lockDirection

​
Request / Response Example — Selling USD, Buying CNY

{
  "merOrderNo": "FX20240601001",
  "sellCurrency": "USD",
  "buyCurrency": "CNY",
  "lockDirection": "SELL",
  "amount": "10000.00"
}
The expireTime is a Unix timestamp in milliseconds. FX quotes are typically valid for 30 seconds. If you do not call sp1202 before expireTime, the quote will be invalidated and you must request a new one.

​
Step 3 — Execute the FX Trade

Once you have a valid quoteId, confirm the trade by calling POST /api/sp1202. Pass the quoteId and your webhook URL for async result delivery. 
{
  "quoteId": "QT20240601000701",
  "callbackUrl": "https://api.acme-trade.com/webhooks/gcashier/fx-result"
}
The synchronous response confirms the trade has been accepted for settlement. The definitive success or failure result is delivered via the sp3201 webhook.
Build a retry-safe design: check whether a bizFlow already exists for a quoteId before re-submitting, since a quote can only be executed once.

​
Step 4 — Receive the FX Result Webhook (sp3201)

Gcashier Pay posts the settlement outcome to your callbackUrl after the exchange is processed. Respond with HTTP 200 to acknowledge receipt. 
{
  "bizFlow": "BF20240601000702",
  "quoteId": "QT20240601000701",
  "merOrderNo": "FX20240601001",
  "sellCurrency": "USD",
  "buyCurrency": "CNY",
  "rate": "7.2415",
  "sellAmount": "10000.00",
  "buyAmount": "72415.00",
  "status": "SUCC",
  "code": "S00000",
  "message": "FX trade settled successfully."
}
StatusMeaning
SUCCExchange completed — CNY balance credited
FAILExchange failed — USD balance not debited
PROCESSSettlement in progress — wait for final webhook

​
Step 5 — Query FX History

Use POST /api/sp2201 to look up past FX transactions. You can search by quoteId for a specific trade, or by a time range to retrieve all trades within a window. 
{
  "quoteId": "QT20240601000701"
}
Time range queries are limited to a maximum window of 24 hours. For historical reporting over longer periods, paginate by shifting the 24-hour window back in increments.

​
Sandbox Testing

In the Gcashier Pay sandbox environment, the settlement outcome of an FX trade is determined by the last digit of the amount in your sp1201 quote request:
Last digit of amountSimulated result
0 – 3SUCC — exchange completes successfully
4 – 6FAIL — exchange fails
7 – 9PROCESS — exchange remains in processing state
For example, requesting a sellAmount of 10000.00 (last digit 0) will trigger a successful settlement webhook in the sandbox.