Tạo mã QRPay/QRGlobal

Quy trình

• MERCHANT gọi API Tạo mã QRPay/QRGlobal tới hệ thống Baokim.
• Baokim xác thực yêu cầu (JWT, chữ ký số), tra cứu thông tin SUB MERCHANT để lấy các thông tin định danh điểm chấp nhận thanh toán (card_acceptor_id, mã MCC...).
• Hệ thống Baokim sinh chuỗi QR theo chuẩn VietQR/EMVCo và khởi tạo đơn hàng.
• Baokim trả kết quả (qr_string, qr_url) cho MERCHANT để hiển thị cho người thanh toán.
• Cùng một mã QR chấp nhận cả thanh toán nội địa (QRPay) và thanh toán xuyên biên giới (QRGlobal); loại giao dịch được phân biệt qua trường qr_type trong Webhook thông báo giao dịch.

Thông tin API

Method: POST

URL: /b2b/core/api/ext/mm/qr/create

Bảo mật: Bearer JWT (Authorization header)

Request

Bảng tham số chính

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	request_id	String(100)	✅	ID duy nhất ứng với mỗi Request từ MERCHANT sang Baokim
2	request_time	String(20)	✅	Thời gian gửi Request. Format: YYYY-MM-DD H:i:s
3	master_merchant_code	String(50)	✅	Mã định danh duy nhất cho MASTER MERCHANT
4	sub_merchant_code	String(50)	✅	Mã định danh duy nhất cho SUB MERCHANT
5	mrc_order_id	String(50)	✅	Mã đơn hàng của Merchant, duy nhất theo từng SUB MERCHANT. Với QR tĩnh (acc_type = 2): đóng vai trò mã định danh của mã QR
6	acc_type	Integer	✅	Loại mã QR: 1 = Động, 2 = Tĩnh
7	amount	Integer	⚠️	Số tiền thanh toán (VND, số nguyên). Bắt buộc khi acc_type = 1 (QR động), cố định theo đơn hàng. QR tĩnh: không truyền (NULL), người thanh toán tự nhập số tiền khi quét
8	memo	String(25)	✅	Nội dung thanh toán hiển thị khi quét QR (tối đa 25 ký tự, không dấu)
9	post_code	String(10)	✅	Mã bưu điện của điểm chấp nhận thanh toán
10	store_code	String	❌	Mã cửa hàng
11	branch_code	String	❌	Mã chi nhánh
12	staff_code	String	❌	Mã nhân viên

Ví dụ Request

{
  "request_id": "MERCHANT050015588QR001",
  "request_time": "2026-06-10 14:41:00",
  "master_merchant_code": "MASTERMERCHANT",
  "sub_merchant_code": "SUBMERCHANT",
  "mrc_order_id": "ORD_123456789",
  "acc_type": 1,
  "amount": 200000,
  "memo": "Thanh toan don hang",
  "post_code": "100000",
  "store_code": null,
  "branch_code": null,
  "staff_code": null
}

Response

Bảng tham số chính

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	code	Number(3)	✅	Mã lỗi của Baokim
2	message	String(200)	✅	Thông báo mã lỗi của Baokim
3	data	Object	✅	Dữ liệu Baokim trả về

Thông tin data

STT	Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
1	order_id	Integer	✅	Mã đơn hàng của Baokim
2	mrc_order_id	String	✅	Mã đơn hàng Merchant
3	acc_type	Integer	✅	Loại mã QR: 1 = Động, 2 = Tĩnh
4	amount	Integer	❌	Số tiền thanh toán. NULL với QR tĩnh
5	qr_string	Text	✅	Chuỗi QR theo chuẩn EMVCo, Merchant dùng để tự sinh ảnh QR hiển thị
6	qr_url	String	✅	Đường dẫn ảnh mã QR
7	created_at	Datetime	✅	Thời gian tạo đơn hàng
8	updated_at	Datetime	✅	Thời gian cập nhật đơn hàng

Ví dụ Response

{
  "code": 100,
  "message": "Thành công",
  "data": {
    "order_id": 1870436,
    "mrc_order_id": "ORD_123456789",
    "acc_type": 1,
    "amount": 200000,
    "qr_string": "00020101021238550010A0000007270123000697040300000000000020386304C3A4",
    "qr_url": "https://sandbox.baokim.vn/qr/BK1234567890.png",
    "created_at": "2026-06-10 14:41:05",
    "updated_at": "2026-06-10 14:41:05"
  }
}

Bảng mã lỗi

Mã lỗi	Mô tả
100	Thành công
11	Thất bại
101	Lỗi hệ thống Baokim
103	Lỗi xác thực chữ ký
104	Lỗi xác thực JWT
422	Dữ liệu không hợp lệ (sai định dạng, thiếu trường bắt buộc)
504	Timeout
707	Mã Order ID đã tồn tại
709	Master Merchant không thể tự tạo giao dịch
710	Sub Merchant không tồn tại
711	Master Merchant không tồn tại
712	Sub Merchant đang không hoạt động
713	Master Merchant đang không hoạt động
714	Sub Merchant không thuộc Master Merchant
717	Mã dịch vụ không tồn tại
718	Mã dịch vụ không hoạt động
720	Token không hợp lệ
724	Không tìm thấy cấu hình phí