Overview
Version
| Version | Status | Release Date | End of Support | Deprecation Warning |
|---|---|---|---|---|
| V1.0 | Latest | 07/2025 | — | — |
Terminology Table
| Term | Definition |
|---|---|
| Baokim | Baokim E-commerce Trading Joint Stock Company |
| MERCHANT | An entity that connects with Baokim to integrate payment services |
| MASTER MERCHANT | A high-level merchant managing one or more Sub Merchants |
| SUB MERCHANT | A sub-level merchant operating under the management of a Master Merchant |
| ĐVCNTT | Payment Service Provider |
| USER | Customer purchasing goods from the Merchant |
| VA | Virtual Account — a virtual account used for collection via bank transfer |
| CĐTG | Installment conversion |
| BNPL | Buy Now Pay Later |
| TCTC | Credit institutions (Kredivo, HomeCredit, FundiIn, Muadee) |
| CIT | Cardholder-Initiated Transaction |
| MIT / UCOF | Merchant-Initiated Transaction using saved card token |
| JWT | JSON Web Token — OAuth2 authentication string |
| SHA256withRSA | Digital signature algorithm using RSA + SHA-256 |
| SHA1withRSA | Digital signature algorithm using RSA + SHA-1 (used for Host-to-Host VA direct) |
| AES-256-CBC | Card data encryption algorithm |
| 3DS / OTP | Two-factor authentication for international card payments |
General Introduction to Baokim B2B Services
Baokim provides a set of APIs that allow merchants to directly integrate various payment services. All data transmission is in JSON format over HTTPS channels, combined with OAuth2 authentication and digital signatures to ensure security.
This documentation includes the following API groups:
Direct Merchant
Merchants integrate directly with Baokim with no intermediate tier.
Basic - Pro
| API | Description |
|---|---|
| Merchant Authentication | Obtain JWT OAuth2 Token |
| Create Order | Create payment order, receive payment_url |
| Query Order | Check order status |
| Webhook | Receive payment result notifications |
| Refund Order | Full or partial refund |
| Cancel Order | Cancel unpaid order |
Host-to-Host
| Group | API | Description |
|---|---|---|
| VA | Create VA, Update VA, Webhook, Query, Refund | Collection via bank transfer using Virtual Account |
| BNPL | Get loan packages, Create transaction, Query, Webhook, Cancel | Buy Now Pay Later via Kredivo, HomeCredit, FundiIn, Muadee |
| Installment | Get bank list, Check card, Create installment transaction, Query, Webhook, Cancel | Credit card installment conversion via issuing bank |
| International Card | API Authentication, Authentication, Webhook, Authorization, Capture, Reversal, Refund, Query | Visa / Mastercard / JCB payment with CIT + MIT (UCOF) flow |
Master Merchant
Hierarchical model: Master Merchant manages multiple Sub Merchants. All requests include both master_merchant_code and sub_merchant_code.
Basic - Pro
| API | Description |
|---|---|
| Merchant Authentication | Obtain JWT OAuth2 Token |
| Create Order | Create payment order with Auto Debit model under Master/Sub hierarchy |
| Payment Webhook | Receive payment result notifications |
| Query Order | Check order status |
| Cancel Auto Debit | Cancel Auto Debit instruction |
| Cancel Webhook | Receive auto debit cancellation notifications |
| Refund Order | Refund transaction |
Host-to-Host
| Group | API | Description |
|---|---|---|
| VA | Create VA, Webhook, Update VA, Query, Refund | Virtual Account under Master/Sub Merchant model |
| International Card | API Authentication, Authentication, Webhook, Authorization, Capture, Reversal, Refund, Query, Payment UCOF | Visa / Mastercard / JCB payment under Master/Sub model with MIT (UCOF) flow |
| QRPay/QRGlobal | Merchant Authentication, Create QR Code, Refund, Webhook, Query | Payment via domestic (QRPay) and cross-border (QRGlobal) QR codes under Master/Sub model |
| Deeplink | Merchant Authentication, Get bank list, Create Deeplink | Redirects the user into the bank's app to perform a money transfer under Master/Sub model |
Merchant Classification
Direct Merchant
Direct Merchant is a model where the merchant integrates directly with Baokim's system via API.
In this model, the merchant will:
- Sign a contract directly with Baokim
- Receive
merchant_code,client_id,client_secret - Integrate API to create orders and process payments
Flow Overview
- User makes a purchase on the merchant's system
- Merchant calls Baokim's order creation API
- Baokim returns
payment_url - Merchant redirects user to the payment page
- After payment completion, Baokim sends the result via:
- Redirect URL
- Webhook
Characteristics
- Merchant directly manages API integration
- Merchant is responsible for managing orders and transactions
- Baokim handles payment processing and bank connections
Master Merchant
Master Merchant is a model where an intermediary partner integrates with Baokim and provides payment services to multiple sub-merchants.
Master Merchant will:
- Integrate API with Baokim
- Manage multiple sub-merchants in their system
- Send
store_codeorbranch_codeinformation to distinguish sub-merchants
Flow Overview
- User purchases at a sub-merchant's system
- Sub-merchant sends payment request to the master merchant's system
- Master Merchant calls Baokim's order creation API
- Baokim processes the payment
- Payment result is returned to Master Merchant
- Master Merchant updates transaction status for the sub-merchant
Characteristics
- Master Merchant manages multiple sub-merchants
- Only Master Merchant integrates API with Baokim
- Sub-merchants do not need to integrate directly with Baokim