Create Installment Conversion Transaction

Process

Description:

• Merchant sends a request to create an installment conversion (IC) transaction to Baokim after successfully processing the customer's card transaction.
• Baokim records the request and returns order information in pending conversion status.

API Information

Method: POST

Request

(Parameters sent by the partner)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	request_id	String(100)	✅	Unique ID of the request from Merchant to Baokim
2	request_time	String(20)	✅	Request sent time. Format: YYYY-MM-DD H:i:s
3	merchant_code	String(50)	✅	Unique merchant identifier
4	bank_no	String(6)	✅	Unique bank code on Baokim
5	customer_id_number	String(12)	❌	Customer ID / CCCD / passport number
6	customer_name	String(200)	✅	Full customer name, no accents, with spaces
7	customer_phone	String(10)	✅	Customer phone number
8	customer_email	String(255)	✅	Customer email
9	customer_address	String(500)	❌	Customer address
10	product_name	String(255)	❌	Product name(s) in the order
11	auth_code	String(50)	✅	Authorization code
12	card_no	String(10)	✅	First 6 + last 4 digits of card. Example: card 53396xxxxxxx82111 → send 5339682111
13	mrc_order_id	String(50)	✅	Merchant order code
14	loan_pack_id	Number(10)	✅	Loan package ID (retrieved from "Retrieve banks and installment loan packages" API response)
15	auth_time	String(50)	✅	Time when customer charged the card
16	total_payment_amount	Number(50)	✅	Amount customer charged on card

Request Example

{
  "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

(Parameters returned by Baokim)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	code	Number(3)	✅	Baokim error code
2	message	String(200)	✅	Error code message
3	data	Object	✅	Data returned

Data Information

No.	Field Name	Data Type	Required	Description
1	bank_no	String(6)	✅	Bank code on Baokim
2	customer_id_number	String(12)	❌	Customer ID / CCCD / passport
3	customer_name	String(200)	❌	Full customer name, no accents, with spaces
4	customer_phone	String(10)	✅	Customer phone number
5	customer_email	String(255)	✅	Customer email
6	customer_address	String(500)	❌	Customer address
7	product_name	String(255)	❌	Product name(s) in the order
8	auth_code	String(50)	✅	Authorization code
9	card_no	String(50)	✅	First 6 + last 4 digits of card (Example: card 53396xxxxxxx82111 then send 5339682111)
10	mrc_order_id	String(50)	✅	Merchant order code
11	loan_package	Object	✅	Loan package information
12	auth_time	String(50)	✅	Card payment time
13	total_payment_amount	Integer	✅	Card payment amount
14	status	Integer	✅	Order status on Baokim
15	installment_fee_amount	Integer	✅	Installment conversion fee
16	monthly_payment_amount	Integer	✅	Monthly installment payment amount (total loan / term)
17	installment_amount	Integer	✅	Installment registered amount
18	order_id	Integer	✅	Unique order code created by Baokim
19	created_at	String(20)	✅	Order creation time
20	updated_at	String(20)	✅	Order update time

loan_package Information

No.	Field Name	Data Type	Required	Description
1	loan_pack_id	Integer	✅	Loan package ID on Baokim system
2	package_name	String(255)	✅	Loan package name
3	grace_period	Integer	✅	Installment term (months)
4	conversion_fee	Decimal	✅	Installment conversion fee (%)

Response Example

{
  "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": "6-month installment package",
      "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"
  }
}

Error Codes

Error Code	Description
200	Success
11	Failure
101	Baokim system error
102	Basic auth authentication error
103	Signature authentication error
104	Validation error: Invalid RequestId
105	Validation error: Invalid RequestTime
106	Validation error: Invalid PartnerCode
107	Validation error: Invalid CustomerName
108	Validation error: Invalid CustomerPhone
109	Validation error: Invalid CustomerEmail
110	Validation error: Invalid BankCode
112	Validation error: Invalid ClientIdNo
113	Validation error: Invalid AuthCode
114	Validation error: Invalid CardNo
118	Validation error: Invalid ReferenceId
122	Validation error: Invalid ConversionMoney
123	Validation error: Invalid PayPerMonth
124	Validation error: Invalid InstallmentAmount
125	Validation error: Invalid TotalPaymentAmount
126	Installment bank and card issuer bank do not match
127	Validation error: Invalid Operation
142	Invalid status
157	Card BIN does not support installment
159	Invalid start time (fromTime)
160	Invalid end time (toTime)
168	Invalid installment term
170	Loan package not configured on Baokim
171	Transaction cancellation not supported
174	Invalid cancellation time
176	Invalid payment time
177	Invalid cancellation reason