Webhook Transaction Result Notification

Process

Description:

• Baokim sends a webhook to Merchant when each transaction is approved or cancelled for deferred payment.
• Merchant needs to build a webhook API to receive this notification.
• Baokim signs the request data sent to Merchant using SHA256withRSA.

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 corresponding to each 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 identifier for partner: MERCHANT
4	operation	String	✅	Operation type: PAYMENT or REFUND
5	data	Object	✅	Detailed transaction information

Data Information

No.	Field Name	Data Type	Required	Description
1	order_id	Number	✅	Baokim order code
2	mrc_order_id	String(50)	✅	Merchant order code
3	merchant_code	String(50)	✅	Merchant identifier
4	customer_name	String(200)	✅	Full customer name, no accents, with spaces
5	customer_phone	String(10)	✅	Customer phone number
6	customer_email	String(255)	✅	Customer email
7	customer_address	String(500)	✅	Customer address
8	package_code	String(255)	✅	Loan package code
9	name	String(20)	✅	Loan package name
10	period	Number	✅	Term (1, 3, 6, 9, 12 months)
11	min_amount	Number	✅	Minimum amount to apply for this loan package
12	max_amount	Number	✅	Maximum amount to apply for this loan package
13	down_payment_percent	Number	✅	% of down payment amount
14	down_payment_amount	Number	✅	Down payment amount
15	original_amount	Number	✅	Order amount
16	user_fee	Number	✅	Fee buyer bears
17	merchant_fee	Number	✅	Merchant fee
18	total_paylater_amount	Number	✅	Total deferred payment amount (fees included)
19	payment_per_period	Number	✅	Payment amount per period
20	total_amount	Number	✅	Total amount user needs to pay (down payment + deferred payment)
21	difference_amount	Number	✅	Amount difference compared to straight payment
22	document_required	String(4)	✅	Required documents (CCCD/CMND)
23	provider_code	String(20)	✅	Finance organization name
24	description	String(255)	✅	Order description
25	url_success	String(255)	✅	URL redirect when loan approval is successful
26	url_fail	String(255)	✅	URL redirect when loan approval fails
27	status	Number	✅	Transaction status
28	extension	Object	✅	Extended information (product list)
29	created_at	Datetime	✅	Order creation time
30	updated_at	Datetime	✅	Order update time

Extension Information

No.	Field Name	Data Type	Required	Description
1	items	Array	✅	List of bank and loan package information objects

Items Information

No.	Field Name	Data Type	Required	Description
1	item_id	String(50)	✅	Product ID
2	item_code	String(50)	✅	Product code
3	item_name	String(255)	✅	Product name
4	item_amount	Number	✅	Product price
5	quantity	Number	✅	Product quantity
6	url	String(500)	✅	Product link

Request Example

{
  "request_id": "MERCHANT050015588AXE012",
  "request_time": "2020-08-11 14:41:00",
  "merchant_code": "MERCHANT",
  "operation": "PAYMENT/REFUND",
  "data": {
    "order_id": 1870436,
    "mrc_order_id": "VLAD_1753867524",
    "merchant_code": "MERCHANT",
    "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",
    "package_code": "homecredit_1month",
    "name": "Home Credit 1 month",
    "period": 1,
    "min_amount": 1000000,
    "max_amount": 500000,
    "down_payment_percent": 20,
    "down_payment_amount": 2000000,
    "original_amount": 10000000,
    "user_fee": 0,
    "merchant_fee": 100000,
    "total_paylater_amount": 8000000,
    "payment_per_period": 8000000,
    "total_amount": 10100000,
    "difference_amount": 100000,
    "document_required": "CCCD",
    "provider_code": "HOMECREDIT",
    "description": "Deferred payment order",
    "url_success": "https://example.com/success",
    "url_fail": "https://example.com/fail",
    "status": 1,
    "extension": {
      "items": [
        {
          "item_id": 123456,
          "item_code": "AEIQ_4562",
          "item_name": "Máy tính xách tay ABC",
          "item_amount": 10000000,
          "quantity": 1,
          "url": "https://example.com/product-detail"
        }
      ]
    },
    "created_at": "2020-08-11 14:41:00",
    "updated_at": "2020-08-11 15:41:00"
  }
}

Response

(Merchant's reply to Baokim)

Main Parameters Table

No.	Field Name	Data Type	Required	Description
1	code	Integer	✅	Result code. 0, 100 or 200 = Success
2	message	String	✅	Processing result message
3	data	Object	❌	Returned data (if any)

Response Example

{
  "code": 200,
  "message": "Successfully",
  "data": null
}