Get FX Rate

Get the foreign exchange rate (two-way bid/ask) for the requesting Merchant.

The API supports three lookup modes:

• One pair — get the rate of a single currency pair.
• Several pairs — get the rates of a specific list of pairs.
• All pairs — get the rates of every pair supported for the Merchant.

Each returned rate carries a quote_code, the last_updated time (freshness) and a valid_until time (validity).

Path

• URL: /cb-core/api/v1/fx/get-rate
• Method: POST
• Description: Get the bid/ask rate for one, several or all currency pairs.

Request

Request table

Params	Data Type	Required	Description
request_id	string(50)	Yes	Unique code that identifies the request. Suggested format: MerchantCode + BK + YYYYMMDD + UniqueId
request_time	string(19)	Yes	Time the Merchant sends the request. Format: YYYY-MM-DD HH:MM:SS
merchant_code	string(20)	Yes	Merchant code provided by Baokim before integration
type	int(1)	Yes	Lookup mode. 1: one pair, 2: several pairs, 3: all supported pairs
currency_pair	string(255)	Conditional	The currency pair(s) to look up. When type = 1: a single pair, e.g. USD/VND. When type = 2: a comma-separated list, e.g. USD/VND,CNY/VND. When type = 3: not required.

Request Example

{
  "request_id": "MERCHANT1234BK202606052",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "type": 2,
  "currency_pair": "USD/VND,CNY/VND"
}

Response

Response Table

Params	Data Type	Required	Description
response_code	int(4)	Yes	Result code from Baokim, as per the Error Codes table
response_message	string(200)	Yes	Description of the result code
merchant_code	string(20)	Yes	Merchant code provided by Baokim before integration
data	Array of Objects	Yes	List of rate quotes, one per requested pair

Data Array Structure (inside data)

Params	Data Type	Description
currency_pair	string(10)	Currency pair in BASE/QUOTE format (e.g. USD/VND)
bid	decimal(18,4)	Buying rate — the rate at which the customer sells the foreign currency
ask	decimal(18,4)	Selling rate — the rate at which the customer buys the foreign currency
quote_code	string(50)	Quote code for this rate. Used for reconciliation and reserved for rate-lock
last_updated	string(19)	Time the rate was last refreshed. Format: YYYY-MM-DD HH:MM:SS
valid_until	string(19)	Time until which the quote is valid. May be null in the current phase

Response Example

{
  "response_code": 200,
  "response_message": "Success",
  "merchant_code": "MERCHANT1234",
  "data": [
    {
      "currency_pair": "USD/VND",
      "bid": 26450.0000,
      "ask": 26510.0000,
      "quote_code": "FXQ20260605101530USDVND0001",
      "last_updated": "2026-06-05 10:15:00",
      "valid_until": "2026-06-05 10:16:00"
    },
    {
      "currency_pair": "CNY/VND",
      "bid": 3600.5000,
      "ask": 3625.7000,
      "quote_code": "FXQ20260605101530CNYVND0002",
      "last_updated": "2026-06-05 10:15:00",
      "valid_until": "2026-06-05 10:16:00"
    }
  ]
}

Error Code

Response Code	Response Message
200	Success
101	System Error
110	Merchant Code Invalid
120	Invalid Signature
404	Currency Pair Not Supported
422	Validation Error
423	FX Rate Not Available
429	Too Many Requests