Tổng quan
Phiên bản
| Phiên bản | Trạng thái | Ngày phát hành | Ngày ngừng hỗ trợ | Cảnh báo ngừng sử dụng |
|---|---|---|---|---|
| V1.0 | Latest | 07/2025 | — | — |
Bảng thuật ngữ
| Thuật ngữ | Giải nghĩa |
|---|---|
| Baokim | Công ty cổ phần Thương mại điện tử Bảo Kim |
| MERCHANT/MRC | Đơn vị kết nối với Bảo Kim để tích hợp dịch vụ thanh toán |
| MASTER MERCHANT | Merchant cấp cao quản lý một hoặc nhiều Sub Merchant |
| Merchant Category Code/MCC | Mã ngành nghề của đơn vị chấp nhận thanh toán theo chuẩn quốc tế |
| SUB MERCHANT | Merchant con, hoạt động dưới sự quản lý của Master Merchant |
| ĐVCNTT | Đơn vị chấp nhận thanh toán |
| USER | Khách hàng mua hàng của Merchant |
| VA | Virtual Account — tài khoản ảo dùng để thu hộ qua chuyển khoản |
| CĐTG | Chuyển đổi trả góp |
| BNPL | Buy Now Pay Later — mua trước trả sau |
| TCTC | Tổ chức tín dụng (Kredivo, HomeCredit, FundiIn, Muadee) |
| CIT | Cardholder-Initiated Transaction — giao dịch do chủ thẻ khởi tạo |
| MIT / UCOF | Merchant-Initiated Transaction — giao dịch do Merchant khởi tạo bằng token thẻ đã lưu |
| JWT | JSON Web Token — chuỗi xác thực OAuth2 |
| SHA256withRSA | Thuật toán ký số sử dụng RSA + SHA-256 |
| SHA1withRSA | Thuật toán ký số sử dụng RSA + SHA-1 (dùng cho Host-to-Host VA direct) |
| AES-256-CBC | Thuật toán m ã hoá dữ liệu thẻ |
| 3DS / OTP | Xác thực hai lớp khi thanh toán thẻ quốc tế |
| QRPay | Dịch vụ thanh toán bằng mã QR nội địa qua mạng lưới NAPAS |
| QRGlobal | Dịch vụ thanh toán mã QR xuyên biên giới (khách hàng nước ngoài quét mã QR của Merchant) |
| QR động | Mã QR gắn với một đơn hàng cụ thể, số tiền cố định, sử dụng một lần |
| QR tĩnh | Mã QR in/dán cố định tại điểm bán, người thanh toán tự nhập số tiền, sử dụng nhiều lần |
| NAPAS | Công ty Cổ phần Thanh toán Quốc gia Việt Nam |
| VietQR | Chuẩn mã QR thanh toán theo đặc tả EMVCo do NAPAS ban hành |
Giới thiệu chung về dịch vụ B2B tại Baokim
Baokim cung cấp bộ API cho phép Merchant tích hợp trực tiếp các dịch vụ thanh toán. Toàn bộ dữ liệu truyền nhận dưới dạng JSON qua kênh HTTPS, kết hợp xác thực OAuth2 và chữ ký số để đảm bảo bảo mật.
Bộ tài liệu này bao gồm các nhóm API sau:
Direct Merchant
Merchant tích hợp trực tiếp với Baokim, không có cấp trung gian.
Basic - Pro
| API | Mô tả |
|---|---|
| Xác thực Merchant | Lấy JWT Token OAuth2 |
| Tạo đơn hàng | Tạo đơn thanh toán, nhận checksum_url |
| Tra cứu đơn hàng | Kiểm tra trạng thái đơn |
| Webhook | Nhận thông báo kết quả thanh toán |
| Hoàn đơn hàng | Hoàn tiền toàn bộ hoặc một phần |
| Huỷ đơn hàng | Huỷ đơn chưa thanh toán |
Host-to-Host
| Nhóm | API | Mô tả |
|---|---|---|
| VA | Tạo VA, Cập nhật VA, Webhook, Tra cứu, Hoàn tiền | Thu hộ qua chuyển khoản ngân hàng bằng Virtual Account |
| BNPL | Lấy danh sách gói vay, Tạo giao dịch, Tra cứu, Webhook, Huỷ | Mua trước trả sau qua Kredivo, HomeCredit, FundiIn, Muadee |
| Installment | Lấy danh sách ngân hàng, Kiểm tra thẻ, Tạo giao dịch CĐTG, Tra cứu, Webhook, Huỷ | Chuyển đổi trả góp thẻ tín dụng qua ngân hàng phát hành |
| Thẻ quốc tế | Xác thực API, Authentication, Webhook, Authorization, Capture, Reversal, Hoàn tiền, Tra cứu | Thanh toán Visa / Mastercard / JCB với luồng CIT + MIT (UCOF) |
Master Merchant
Mô hình phân cấp: Master Merchant quản lý nhiều Sub Merchant. Mọi request đều truyền cả master_merchant_code và sub_merchant_code.
Basic - Pro
| API | Mô tả |
|---|---|
| Xác thực Merchant | Lấy JWT Token OAuth2 |
| Tạo đơn hàng | Tạo đơn thanh toán Auto Debit theo mô hình Master/Sub |
| Webhook thanh toán | Nhận thông báo kết quả thanh toán |
| Tra cứu đơn hàng | Kiểm tra trạng thái đơn |
| Huỷ thu hộ tự động | Huỷ lệnh Auto Debit |
| Webhook huỷ thu hộ tự động | Nhận thông báo kết quả huỷ |
| Hoàn đơn hàng | Hoàn tiền giao dịch |
Host-to-Host
| Nhóm | API | Mô tả |
|---|---|---|
| VA | Tạo VA, Webhook, Cập nhật VA, Tra cứu, Hoàn tiền | Virtual Account theo mô hình Master/Sub Merchant |
| Thẻ quốc tế | Xác thực API, Authentication, Webhook, Authorization, Capture, Reversal, Hoàn tiền, Tra cứu, Payment UCOF | Thanh toán Visa / Mastercard / JCB theo mô hình Master/Sub, có thêm luồng MIT (UCOF) |
| QRPay/QRGlobal | Xác thực Merchant, Tạo mã QR, Hoàn tiền, Webhook, Tra cứu | Thanh toán bằng mã QR nội địa (QRPay) và xuyên biên giới (QRGlobal) theo mô hình Master/Sub |
| Deeplink | Xác thực Merchant, Lấy danh sách ngân hàng, Tạo Deeplink | Điều hướng người dùng vào App ngân hàng để thực hiện chuyển tiền theo mô hình Master/Sub |
Phân loại merchant
Direct Merchant
Direct Merchant là mô hình trong đó Merchant tích hợp trực tiếp với hệ thống của BaoKim thông qua API.
Trong mô hình này, Merchant sẽ:
- Ký hợp đồng trực tiếp với BaoKim
- Nhận
merchant_code,client_id,client_secret - Tích hợp API để tạo đơn hàng và xử lý thanh toán
Luồng tổng quan
- User thực hiện mua hàng trên hệ thống của Merchant
- Merchant gọi API tạo đơn hàng tới BaoKim
- BaoKim trả về
payment_url - Merchant điều hướng user tới trang thanh toán
- Sau khi thanh toán hoàn tất, BaoKim gửi kết quả qua:
- Redirect URL
- Webhook
Đặc điểm
- Merchant quản lý trực tiếp việc tích hợp API
- Merchant chịu trách nhiệm quản lý đơn hàng và giao dịch
- BaoKim xử lý phần thanh toán và kết nối ngân hàng
Master Merchant
Master Merchant là mô hình trong đó một đối tác trung gian tích hợp với BaoKim và cung cấp dịch vụ thanh toán cho nhiều Merchant con (Sub-Merchant).
Master Merchant sẽ:
- Tích hợp API với BaoKim
- Quản lý nhiều Merchant con trong hệ thống của mình
- Gửi thông tin
store_codehoặcbranch_codeđể phân biệt các Merchant con
Luồng tổng quan
- User mua hàng tại hệ thống của Sub-Merchant
- Sub-Merchant gửi yêu cầu thanh toán tới hệ thống Master Merchant
- Master Merchant gọi API của BaoKim để tạo đơn hàng
- BaoKim xử lý thanh toán
- Kết quả thanh toán được trả về Master Merchant
- Master Merchant cập nhật trạng thái giao dịch cho Sub-Merchant
Đặc điểm
- Master Merchant quản lý nhiều Merchant con
- Chỉ Master Merchant tích hợp API với BaoKim
- Sub-Merchant không cần tích hợp trực tiếp với BaoKim