FX Rate API Introduction

The FX Rate APIs allow a Merchant to look up Baokim's foreign exchange rates in real time, convert an amount between two currencies and query the rate history.

The rate returned by these APIs is a reference quote for the requesting Merchant. In the current phase the quote is for reference only and does not commit a transaction — locking a quote to a real FX deal is handled in a later phase. Every quote already carries a quote code (quote_code) so that it can be reconciled and, in the future, re-used to lock the rate.

1. API List

API	Endpoint	Method	Purpose
Get Currencies	/cb-core/api/v1/fx/get-currencies	POST	Return the list of currency pairs Baokim can quote for the Merchant.
Get FX Rate	/cb-core/api/v1/fx/get-rate	POST	Get the bid/ask rate for one pair, several pairs or all supported pairs.
Convert	/cb-core/api/v1/fx/convert	POST	Convert an amount between two currencies using the current rate.
Get Historical Rate	/cb-core/api/v1/fx/get-historical-rate	POST	Query past rates of a currency pair for reconciliation and analysis.

2. Authentication

The FX Rate APIs are part of the Cross Border service and use the same request signing mechanism as the other Cross Border APIs, as defined in Introduction to Baokim API. In short:

• Every request is sent as a signed JSON body. The signature is placed in the Signature header and authenticates the request and guarantees data integrity.
• Signing uses the RSA256 (SHA256withRSA) algorithm. The RSA public/private key pair is generated by the Merchant; the private key is kept on the Merchant side and the public key is shared with Baokim during integration.
• Baokim verifies the signature with the Merchant's public key. An invalid signature is rejected with result code 120 Invalid Signature.

Header

Name	Value	Description
Content-Type	application/json	Data format is JSON
Signature	Digital signature	Digital signature for request authentication

The Signature header value follows the format defined in Introduction to Baokim API:

keyVersion=1.0,algorithm=RSA256,signature=base64-encoded-signature

3. Common Request Fields

Every FX Rate request contains the following fields in addition to the API-specific fields:

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	The Merchant code defined in the Baokim system, provided to the Merchant during integration

4. Common Response Fields

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, as per the Error Codes table
merchant_code	string(20)	Yes	Merchant code provided by Baokim before integration
data	Object/Array	No	API-specific payload. Absent or null on error

See Error Codes for the full list of result codes.

5. Terminology

Term	Explanation
Currency pair	A pair quoted as BASE/QUOTE, e.g. USD/VND. The first currency is the foreign currency, the second is VND.
bid	Buying rate — the rate at which the customer sells the foreign currency (inbound).
ask	Selling rate — the rate at which the customer buys the foreign currency (outbound).
spread	The difference ask - bid. Always bid < ask.
quote_code	The quote code returned with every rate. Used for reconciliation and reserved for rate-lock in a later phase.
last_updated	The time the underlying rate was last refreshed (freshness of the quote). Format: YYYY-MM-DD HH:MM:SS
valid_until	The time until which the quote is valid. May be null in the current phase.

6. Bid / Ask and Direction

Rates are always returned two-way (bid and ask) for a pair quoted as BASE/QUOTE (foreign currency / VND).

Customer action	Rate applied	Example (USD/VND)
Customer sells foreign ccy	bid	USD → VND uses bid
Customer buys foreign ccy	ask	VND → USD uses ask

In the Convert API the direction is derived from the order of from_currency / to_currency: converting a foreign currency into VND applies bid, while converting VND into a foreign currency applies ask. The applied side is echoed back in the response (rate_type).

7. Supported Currency Pairs

• USD/VND is always available.
• Other pairs (for example CNY/VND) are optional and depend on the upstream source bank and on the Merchant's configuration.
• Use Get Currencies to retrieve the pairs that are actually quotable for your Merchant. Only pairs that can be reliably quoted are returned.

8. Important Notes

• Per-Merchant pricing: for the same currency pair, different Merchants may receive different rates according to their configuration/contract.
• No source disclosure: the APIs return only the final figures. The data source, pricing formula and margin are never exposed.
• Rate limiting: each Merchant is limited to a maximum number of calls per minute. Exceeding the limit returns a "too many requests, try again later" error (see Error Codes).
• Traceability: every request carries its own request_id, and every quote carries its own quote_code.
• Reference only: in the current phase the quote is a reference quote and is not a commitment. If no reliable rate is available at request time, the API returns an "FX rate not available" error.

9. Rate Lookup Flow

Stage 1 — Periodic rate collection (background, on Baokim side)

Step	Actor	Description
1	Baokim	Collect rates from the configured source(s).
2	Baokim	Store the rates together with last_updated.

Stage 2 — Merchant looks up a rate

Step	Actor	Description
1	Merchant	Send a rate request for one pair, several pairs or all pairs (optionally with an amount).
2	Baokim	Authenticate the request and check the rate limit. If exceeded, return "try again later".
3	Baokim	Read the stored rate. If still fresh, use it directly; otherwise refresh it from the source.
4	Baokim	If the rate cannot be refreshed, return "FX rate not available" and stop.
5	Baokim	Apply the Merchant's pricing configuration, compute bid/ask, generate a quote_code.
6	Baokim	Return bid/ask + quote_code + last_updated + valid_until.