Chuyển đổi

Chuyển đổi một số tiền từ một loại tiền tệ sang loại khác sử dụng tỷ giá hiện tại cho Merchant yêu cầu. Chuyển đổi sử dụng tỷ giá tương tự như API Lấy tỷ giá FX, trong giai đoạn hiệu lực của báo giá đó.

Hướng (và do đó tỷ giá nào được áp dụng) được suy ra từ thứ tự của from_currency và to_currency:

Chuyển đổi ngoại tệ → VND (khách hàng bán ngoại tệ) áp dụng tỷ giá bid.
Chuyển đổi VND → ngoại tệ (khách hàng mua ngoại tệ) áp dụng tỷ giá ask.

Phía được áp dụng được trả về trong rate_type, và response mang cùng quote_code để báo giá có thể được đối chiếu (và ở giai đoạn sau, khóa lại).

Đường dẫn

URL: /cb-core/api/v1/fx/convert
Method: POST
Mô tả: Chuyển đổi số tiền giữa hai loại tiền tệ sử dụng tỷ giá hiện tại.

Request

Bảng Request

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
request_id	string(50)	Có	Mã duy nhất định danh request. Định dạng gợi ý: MerchantCode + BK + YYYYMMDD + UniqueId
request_time	string(19)	Có	Thời gian Merchant gửi request. Định dạng: YYYY-MM-DD HH:MM:SS
merchant_code	string(20)	Có	Mã merchant được Baokim cung cấp trước khi tích hợp
from_currency	string(10)	Có	Loại tiền tệ được chuyển đổi từ (ví dụ `USD`). Chỉ cho phép một mã tiền tệ
to_currency	string(10)	Có	Loại tiền tệ được chuyển đổi thành (ví dụ `VND`). Chỉ cho phép một mã tiền tệ
amount	decimal(18,2)	Có	Số tiền, tính bằng `from_currency`, để chuyển đổi

Ví dụ Request

{
  "request_id": "MERCHANT1234BK202606053",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "from_currency": "USD",
  "to_currency": "VND",
  "amount": 1000.00
}

Response

Bảng Response

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
response_code	int(4)	Có	Mã kết quả từ Baokim, theo bảng Mã lỗi
response_message	string(200)	Có	Mô tả mã kết quả
merchant_code	string(20)	Có	Mã merchant được Baokim cung cấp trước khi tích hợp
data	Object	Có	Kết quả chuyển đổi

Cấu trúc Object Data (bên trong `data`)

Tham số	Loại dữ liệu	Mô tả
currency_pair	string(10)	Cặp tiền tệ được sử dụng cho chuyển đổi, ở định dạng `BASE/QUOTE` (ví dụ `USD/VND`)
from_currency	string(10)	Loại tiền tệ được chuyển đổi từ
to_currency	string(10)	Loại tiền tệ được chuyển đổi thành
amount	decimal(18,2)	Số tiền đầu vào, tính bằng `from_currency`
converted_amount	decimal(18,2)	Số tiền kết quả, tính bằng `to_currency`
rate	decimal(18,4)	Tỷ giá áp dụng (VND trên 1 đơn vị ngoại tệ)
rate_type	string(3)	Phía được áp dụng: `bid` hoặc `ask`
quote_code	string(50)	Mã báo giá cho tỷ giá này. Dùng để đối chiếu và dành cho khóa tỷ giá
last_updated	string(19)	Thời gian tỷ giá được làm mới lần cuối. Định dạng: YYYY-MM-DD HH:MM:SS
valid_until	string(19)	Thời gian cho đến khi báo giá còn hiệu lực. Có thể `null` ở giai đoạn hiện tại

Ví dụ Response

{
  "response_code": 200,
  "response_message": "Thành công",
  "merchant_code": "MERCHANT1234",
  "data": {
    "currency_pair": "USD/VND",
    "from_currency": "USD",
    "to_currency": "VND",
    "amount": 1000.00,
    "converted_amount": 26450000.00,
    "rate": 26450.0000,
    "rate_type": "bid",
    "quote_code": "FXQ20260605101530USDVND0001",
    "last_updated": "2026-06-05 10:15:00",
    "valid_until": "2026-06-05 10:16:00"
  }
}

Mã lỗi

Mã Response	Thông báo Response
200	Thành công
101	Lỗi hệ thống
110	Mã merchant không hợp lệ
120	Signature không hợp lệ
404	Cặp tiền tệ không được hỗ trợ
422	Lỗi xác thực
423	Tỷ giá FX không khả dụng
429	Quá nhiều yêu cầu

Đường dẫn​

Request​

Bảng Request​

Ví dụ Request​

Response​

Bảng Response​

Cấu trúc Object Data (bên trong data)​

Ví dụ Response​

Mã lỗi​