Webhook Transaction Result Notification

Process

Description:

• For each transaction that is successfully converted / failed / or cancelled, Baokim sends a notification request to Merchant.
• Merchant needs to build a webhook API to receive this notification.
• Baokim will sign the data in the request sent to MERCHANT side.

API Information

Method: POST

URL: Merchant provided

Header:

Content-Type: application/json
Signature: $signature

Request

(Parameters sent by Baokim to Merchant)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	request_id	String(100)	✅	Unique ID of the request
2	request_time	String(20)	✅	Request sent time. Format: YYYY-MM-DD H:i:s
3	merchant_code	String(50)	✅	Merchant identifier
4	operation	String	✅	Operation type: PAYMENT or REFUND
5	data	Object	✅	Detailed transaction information

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
8	auth_code	String(50)	✅	Authorization code
9	bin	String(50)	✅	Card BIN prefix
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	✅	Status: Conversion successful / Conversion failed / Cancellation successful / Cancellation failed
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 (%)

Request Example

{
  "request_id": "MERCHANT050015588AXE012",
  "request_time": "2020-08-11 14:41:00",
  "merchant_code": "MERCHANT",
  "operation": "PAYMENT/REFUND",
  "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",
    "bin": "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"
  }
}

Response

(Merchant returns to Baokim)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	code	String(3)	✅	Confirmation received (0 = success)
2	message	String(20)	✅	Response message
3	data	String(20)	✅	Data returned if any

Response Example

{
  "code": 0,
  "message": "Success",
  "data": null
}

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