Tạo giao dịch Chuyển đổi trả góp
Quy trình
Mô tả:
- Merchant gửi yêu cầu tạo giao dịch CĐTG tới Baokim sau khi đã xử lý thành công giao dịch thẻ của người dùng.
- Baokim ghi nhận yêu cầu và trả về thông tin đơn hàng ở trạng thái chờ chuyển đổi.
Thông tin API
Method: POST
Request
(Tham số đối tác gửi lên)
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 của request từ Merchant sang Baokim |
| 2 | request_time | String(20) | ✅ | Thời gian gửi request. Format: YYYY-MM-DD H:i:s |
| 3 | merchant_code | String(50) | ✅ | Mã định danh duy nhất của Merchant |
| 4 | bank_no | String(6) | ✅ | Mã định danh duy nhất của ngân hàng trên Baokim |
| 5 | customer_id_number | String(12) | ❌ | Số CMND / CCCD / hộ chiếu c ủa khách hàng |
| 6 | customer_name | String(200) | ✅ | Tên đầy đủ của khách hàng, không dấu, có khoảng trắng |
| 7 | customer_phone | String(10) | ✅ | Số điện thoại khách hàng |
| 8 | customer_email | String(255) | ✅ | Email khách hàng |
| 9 | customer_address | String(500) | ❌ | Địa chỉ khách hàng |
| 10 | product_name | String(255) | ❌ | Tên các sản phẩm trong đơn hàng |
| 11 | auth_code | String(50) | ✅ | Mã chuẩn chi |
| 12 | card_no | String(10) | ✅ | 6 số đầu + 4 số cuối của thẻ. Ví dụ: thẻ 53396xxxxxxx82111 → truyền 5339682111 |
| 13 | mrc_order_id | String(50) | ✅ | Mã đơn hàng merchant |
| 14 | loan_pack_id | Number(10) | ✅ | ID gói vay (lấy từ response API Lấy danh sách ngân hàng và gói vay trả góp) |
| 15 | auth_time | String(50) | ✅ | Thời gian khách hàng thanh toán thẻ |
| 16 | total_payment_amount | Number(50) | ✅ | Số tiền khách hàng thanh toán thẻ |
Ví dụ Request
{
"request_id": "MERCHANT050015588AXE012",
"request_time": "2020-08-11 14:41:00",
"merchant_code": "MERCHANT",
"bank_no": "970436",
"customer_id_number": "H0119600",
"customer_name": "Nguyễn Trung Quân",
"customer_phone": "0394827170",
"customer_email": "[email protected]",
"customer_address": "40, ngách 16/255 đường Láng, Đống Đa, Hà Nội",
"product_name": "Tủ lạnh LG",
"auth_code": "1312338",
"card_no": "5339682111",
"mrc_order_id": "VLAD_1753867524",
"loan_pack_id": 638,
"auth_time": "2020-08-11 14:41:00",
"total_payment_amount": 10700000
}
Response
(Tham số Baokim trả về)
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 |
| 3 | data | Object | ✅ | Dữ liệu trả về |
Thông tin data
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | bank_no | String(6) | ✅ | Mã định danh ngân hàng trên Baokim |
| 2 | customer_id_number | String(12) | ❌ | Số CMND / CCCD / hộ chiếu |
| 3 | customer_name | String(200) | ❌ | Tên đầy đủ khách hàng, không dấu, có khoảng trắng |
| 4 | customer_phone | String(10) | ✅ | Số điện thoại khách hàng |
| 5 | customer_email | String(255) | ✅ | Email khách hàng |
| 6 | customer_address | String(500) | ❌ | Địa chỉ khách hàng |
| 7 | product_name | String(255) | ❌ | Tên các sản phẩm trong đơn hàng |
| 8 | auth_code | String(50) | ✅ | Mã chuẩn chi |
| 9 | card_no | String(50) | ✅ | 6 số đầu + 4 số cuối của thẻ (Ví dụ: thẻ 53396xxxxxxx82111 thì truyền 5339682111) |
| 10 | mrc_order_id | String(50) | ✅ | Mã đơn hàng merchant |
| 11 | loan_package | Object | ✅ | Thông tin gói vay |
| 12 | auth_time | String(50) | ✅ | Thời gian thanh toán thẻ |
| 13 | total_payment_amount | Integer | ✅ | Số tiền thanh toán thẻ |
| 14 | status | Integer | ✅ | Trạng thái đơn hàng trên Baokim |
| 15 | installment_fee_amount | Integer | ✅ | Phí chuyển đổi trả góp |
| 16 | monthly_payment_amount | Integer | ✅ | Số tiền trả góp hàng tháng (tổng tiền vay / kỳ hạn) |
| 17 | installment_amount | Integer | ✅ | Số tiền đăng ký trả góp |
| 18 | order_id | Integer | ✅ | Mã đơn hàng duy nhất do Baokim tạo |
| 19 | created_at | String(20) | ✅ | Thời gian tạo đơn hàng |
| 20 | updated_at | String(20) | ✅ | Thời gian cập nhật đơn hàng |
Thông tin loan_package
| STT | Tên trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|---|---|---|---|---|
| 1 | loan_pack_id | Integer | ✅ | ID gói trả góp trên hệ thống Baokim |
| 2 | package_name | String(255) | ✅ | Tên gói vay |
| 3 | grace_period | Integer | ✅ | Thời hạn trả góp (tháng) |
| 4 | conversion_fee | Decimal | ✅ | Phí chuyển đổi trả góp (%) |
Ví dụ Response
{
"code": 0,
"message": "Success",
"data": {
"bank_no": "970436",
"customer_id_number": "H0119600",
"customer_name": "Nguyễn Trung Quân",
"customer_phone": "0394827170",
"customer_email": "[email protected]",
"customer_address": "40, ngách 16/255 đường Láng, Đống Đa, Hà Nội",
"product_name": "Tủ lạnh LG",
"auth_code": "1312338",
"card_no": "5339682111",
"mrc_order_id": "VLAD_1753867524",
"loan_package": {
"loan_pack_id": 638,
"package_name": "Gói vay kỳ hạn 6 tháng",
"grace_period": 6,
"conversion_fee": 2.0
},
"auth_time": "2020-08-11 14:41:00",
"total_payment_amount": 10700000,
"status": 1,
"installment_fee_amount": 700000,
"monthly_payment_amount": 1188889,
"installment_amount": 10700000,
"order_id": 45467,
"created_at": "2020-08-11 14:41:00",
"updated_at": "2020-08-11 15:41:00"
}
}
Bảng mã lỗi
| Mã lỗi | Mô tả |
|---|---|
| 200 | Thành công |
| 11 | Thất bại |
| 101 | Lỗi hệ thống Baokim |
| 102 | Lỗi xác thực basic auth |
| 103 | Lỗi xác thực chữ ký |
| 104 | Lỗi validate: RequestId không hợp lệ |
| 105 | Lỗi validate: RequestTime không hợp lệ |
| 106 | Lỗi validate: PartnerCode không hợp lệ |
| 107 | Lỗi validate: CustomerName không hợp lệ |
| 108 | Lỗi validate: CustomerPhone không hợp lệ |
| 109 | Lỗi validate: CustomerEmail không hợp lệ |
| 110 | Lỗi validate: BankCode không hợp lệ |
| 112 | Lỗi validate: ClientIdNo không hợp lệ |
| 113 | Lỗi validate: AuthCode không hợp lệ |
| 114 | Lỗi validate: CardNo không hợp lệ |
| 118 | Lỗi validate: ReferenceId không hợp lệ |
| 122 | Lỗi validate: ConversionMoney không hợp lệ |
| 123 | Lỗi validate: PayPerMonth không hợp lệ |
| 124 | Lỗi validate: InstallmentAmount không hợp lệ |
| 125 | Lỗi validate: TotalPaymentAmount không hợp lệ |
| 126 | Ngân hàng trả góp và ngân hàng phát hành thẻ không khớp |
| 127 | Lỗi validate: Operation không hợp lệ |
| 142 | Trạng thái không hợp lệ |
| 157 | Đầu số thẻ không hỗ trợ trả góp |
| 159 | Thời gian bắt đầu (fromTime) không hợp lệ |
| 160 | Thời gian kết thúc (toTime) không hợp lệ |
| 168 | Kỳ hạn trả góp không hợp lệ |
| 170 | Lỗi gói vay chưa được cấu hình tại Baokim |
| 171 | Giao dịch huỷ không được hỗ trợ |
| 174 | Thời gian huỷ không hợp lệ |
| 176 | Thời gian thanh toán không hợp lệ |
| 177 | Lý do huỷ không hợp lệ |