Tạo đơn hàng

Quy trình

Mô tả:

• Merchant gọi API này để tạo một đơn hàng của Baokim và nhận đường link thanh toán.
• Nếu response.code = 100: Baokim xử lý giao dịch và trả kết quả qua Webhook thanh toán.
• Nếu response.code = 101: Merchant cần redirect trình duyệt khách hàng đến redirect_url, sau khi thanh toán thành công Baokim trả kết quả qua Webhook thanh toán.

Lưu ý với phương thức Thu hộ tự động (payment_method = 22):

• Đăng ký không bao gồm thanh toán: truyền total_amount = 0.
• Đăng ký bao gồm thanh toán: truyền total_amount > 0.
• Yêu cầu thanh toán thu hộ: bắt buộc truyền payment_info.token và total_amount > 0.
• Nội dung description dùng làm nội dung chuyển tiền, tối đa 120 ký tự.

Thông tin API

Method: POST

URL: /b2b/core/api/ext/mm/order/send

Request

Bảng tham số chính

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	request_id	String(50)	✅	ID request
2	request_time	Datetime	✅	Thời gian request. Format: YYYY-MM-DD H:m:s
3	master_merchant_code	String(50)	✅	Mã master merchant Baokim cung cấp
4	sub_merchant_code	String(50)	✅	Mã sub merchant Baokim cung cấp
5	store_code	String(50)	❌	Mã cửa hàng
6	branch_code	String(50)	❌	Mã chi nhánh
7	staff_code	String(50)	❌	Mã nhân viên bán hàng
8	service_code	String(50)	❌	Mã dịch vụ (bắt buộc nếu là Thu hộ tự động)
9	mrc_order_id	String(50)	✅	Mã đơn hàng của merchant
10	description	String(255)	✅	Mô tả đơn hàng
11	total_amount	Integer	✅	Tổng tiền đơn hàng (= 0 nếu chỉ đăng ký thu hộ)
12	url_success	String	✅	URL redirect khi thanh toán thành công
13	url_fail	String	✅	URL redirect khi thanh toán thất bại
14	save_token	Integer	❌	Lưu thông tin thẻ: 0 = Không (default), 1 = Có
15	items	Array of objects	❌	List sản phẩm (xem bảng bên dưới)
16	customer_info	Object	❌	Thông tin khách hàng (xem bảng bên dưới)
17	payment_info	Object	❌	Thông tin thanh toán (xem bảng bên dưới)
18	payment_method	Integer	❌	Phương thức thanh toán — bắt buộc với tích hợp Pro (xem bảng bên dưới)

Thông tin phương thức thanh toán (payment_method)

Giá trị	Phương thức
1	VA
2	BNPL
3	Thẻ tín dụng
4	Trả góp thẻ
5	ATM
6	VNPayQR
22	Auto debit (Thu hộ tự động)

Thông tin thanh toán (payment_info)

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	token	String	❌	Token thanh toán (bắt buộc nếu card_hash null)
2	card_hash	String	❌	Thông tin thẻ mã hoá (bắt buộc nếu token null)

Thông tin sản phẩm (items)

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	code	String	❌	Mã sản phẩm
2	name	String	❌	Tên sản phẩm
3	amount	Integer	❌	Giá sản phẩm
4	quantity	Integer	❌	Số lượng
5	link	String	❌	Link sản phẩm

Thông tin khách hàng (customer_info)

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	code	String	❌	Mã khách hàng
2	name	String	❌	Tên khách hàng
3	email	String	❌	Email
4	phone	String	❌	Số điện thoại
5	address	String	❌	Địa chỉ
6	gender	Integer	❌	Giới tính: 1 = Male, 2 = Female

Ví dụ Request

{
  "request_id": "RQID0001",
  "request_time": "2023-08-18 10:00:00",
  "master_merchant_code": "BAOKIMMASTERMERCHANT",
  "sub_merchant_code": "BAOKIMSUBMERCHANT",
  "store_code": null,
  "branch_code": null,
  "staff_code": null,
  "service_code": "BILLINTERNET",
  "mrc_order_id": "BK_3894757",
  "description": "Đơn hàng Test",
  "total_amount": 20000,
  "url_success": "https://baokim.vn/success",
  "url_fail": "https://baokim.vn/fail",
  "save_token": 0,
  "items": [
    {
      "code": "SP001",
      "name": "Sản phẩm 01",
      "amount": 10000,
      "quantity": 1,
      "link": "https://baokim.vn/items/1"
    },
    {
      "code": "SP002",
      "name": "Sản phẩm 02",
      "amount": 10000,
      "quantity": 1,
      "link": "https://baokim.vn/items/2"
    }
  ],
  "customer_info": {
    "code": "KH001",
    "name": "Nguyen Van A",
    "email": "[email protected]",
    "phone": "0812345678",
    "address": "313 Trường Chinh, Khương Mai, Thanh Xuân, Hà Nội",
    "gender": 1
  },
  "payment_info": {
    "token": "Mq7AwLoHkafPdXYxvYedH8sb6MZ18k",
    "card_hash": null
  },
  "payment_method": 22
}

Response

Bảng tham số chính

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	code	Integer	✅	Mã kết quả: 100 = Đang xử lý, 101 = Cần redirect
2	message	String	✅	Thông báo
3	data	Object	✅	Dữ liệu trả về

Thông tin data

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	order_id	Integer	✅	Mã đơn hàng Baokim
2	mrc_order_id	String	✅	Mã đơn hàng merchant
3	master_merchant_code	String	✅	Mã master merchant
4	sub_merchant_code	String	✅	Mã sub merchant
5	total_amount	Integer	✅	Tổng tiền đơn hàng
6	payment_method	Integer	✅	Phương thức thanh toán
7	created_at	Datetime	✅	Thời gian tạo
8	updated_at	Datetime	✅	Thời gian cập nhật
9	redirect_url	String	❌	Link thanh toán Baokim (có giá trị khi code = 101)

Ví dụ Response — Cần redirect (code = 101)

{
  "code": 101,
  "message": "Thành công",
  "data": {
    "order_id": 50911,
    "mrc_order_id": "BK_3894757",
    "master_merchant_code": "BAOKIMMASTERMERCHANT",
    "sub_merchant_code": "BAOKIMSUBMERCHANT",
    "total_amount": 20000,
    "payment_method": 22,
    "created_at": "2025-04-14 15:23:10",
    "updated_at": "2025-04-14 15:23:10",
    "redirect_url": "https://b2b-payment-page.devtest.baokim.vn/payment/?oid=50911&checksum=50f1c60363c29c19b1c18359f1b4cfc655165117"
  }
}

Ví dụ Response — Đang xử lý (code = 100)

{
  "code": 100,
  "message": "Giao dịch đang chờ xử lý",
  "data": {
    "order_id": 50911,
    "mrc_order_id": "BK_3894757",
    "master_merchant_code": "BAOKIMMASTERMERCHANT",
    "sub_merchant_code": "BAOKIMSUBMERCHANT",
    "total_amount": 20000,
    "payment_method": 22,
    "created_at": "2025-04-14 15:23:10",
    "updated_at": "2025-04-14 15:23:10",
    "redirect_url": null
  }
}

Error Codes

Mã lỗi	Mô tả
100	Đang xử lý
101	Thành công - yêu cầu điều hướng khách hàng
102	Lỗi nhà cung cấp
104	Lỗi xác thực
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í