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 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
100	Success
101	System error
102	Provider error
104	JWT authentication error
105	Invalid digital signature
106	Order amount is insufficient for refund
107	Order cannot be refunded
108	Order cannot be cancelled
109	Order does not exist
110	Merchant order code already exists
422	Validation error