Payment Webhook

Process

Description:

• After receiving the payment result from the Partner Bank, Baokim will send a webhook to the merchant.
• If the merchant processes successfully, respond with code = 0.
• If the response code is non-zero, Baokim will resend the webhook 10 times, each time 5 minutes apart.

API Information

Method: POST

URL: (URL configured by merchant with Baokim)

Request Header:

Header	Description
Signature	Digital signature to verify data integrity

Request

(Baokim sends to merchant)

Main Parameters

No	Parameter	Data Type	Required	Description
1	request_id	String	✅	Request ID
2	request_time	Datetime	✅	Request time. Format: YYYY-MM-DD H:m:s
3	master_merchant_code	String(50)	✅	Master merchant code
4	sub_merchant_code	String(50)	✅	Sub merchant code
5	operation	String	✅	Webhook type: PAYMENT_TRANS or REFUND_TRANS
6	payment_result	Object	✅	Payment result
7	token_result	Object	❌	Token information (NULL if not token payment)

Payment Result Information (payment_result)

No	Parameter	Data Type	Required	Description
1	result_code	Integer	✅	Payment status
2	result_message	String	✅	Result message
3	order	Object	✅	Order information
4	transactions	Array of Object	✅	Transaction list

Order Information (payment_result.order)

No	Parameter	Data Type	Required	Description
1	id	Integer	✅	Baokim order ID
2	mrc_order_id	String	✅	Merchant order ID (NULL if payment from static VA)
3	total_amount	Integer	✅	Order amount
4	payment_method	Integer	✅	Payment method: 1 = VA, 2 = BNPL, 3 = Credit Card, 4 = Card Installment, 5 = ATM, 6 = VNPayQR, 22 = Auto debit
5	status	Integer	✅	Status: 1 = Success, 6 = Pending prepayment, 9 = Refunded, 13 = Failed
6	customer_info	Object	❌	Customer information
7	completed_at	Datetime	✅	Success time
8	created_at	Datetime	✅	Creation time
9	updated_at	Datetime	✅	Last update time

Customer Information (payment_result.order.customer_info)

No	Parameter	Data Type	Required	Description
1	code	String	❌	Customer code
2	name	String	❌	Customer name
3	email	String	❌	Customer email
4	phone	String	❌	Customer phone number
5	address	String	❌	Customer address
6	gender	Integer	❌	Gender: 1 = Male, 2 = Female
7	type	Integer	❌	Customer type: 1 = Individual, 2 = Business

Transaction Information (payment_result.transactions)

No	Parameter	Data Type	Required	Description
1	id	Integer	✅	Baokim transaction ID
2	type	Integer	✅	Transaction type: 1 = Payment, 2 = Refund
3	payment_method	Integer	✅	Payment method: 1 = VA, 2 = BNPL, 3 = Credit Card, 4 = Card Installment, 5 = ATM, 6 = VNPayQR, 22 = Auto debit
4	sub_merchant_fee	Integer	✅	Sub merchant fee
5	master_merchant_fee	Integer	✅	Master merchant fee
6	master_merchant_model	Integer	✅	Master merchant model
7	user_fee	Integer	✅	User fee
8	total_amount	Integer	✅	Total customer payment after fees
9	amount	Integer	✅	Amount changing sub merchant balance
10	description	String	❌	Transaction content
11	status	Integer	✅	Status: 0 = Created, 1 = Success, 2 = Failed, 3 = Pending
12	bnpl	Object	❌	BNPL information (if transaction is BNPL)
13	installment	Object	❌	Installment information (if transaction is installment)
14	completed_at	Datetime	✅	Success time
15	created_at	Datetime	✅	Order creation time
16	updated_at	Datetime	✅	Last update time

BNPL Information (payment_result.transactions.bnpl)

No	Parameter	Data Type	Required	Description
1	payment_per_month	Integer	❌	Amount to be paid each month (VND)
2	paylater_amount	Integer	❌	Amount paid later (VND)
3	down_payment	Integer	❌	Down payment amount (VND)
4	provider	String	❌	Provider code

Installment Information (payment_result.transactions.installment)

No	Parameter	Data Type	Required	Description
1	card_brand	String	❌	Card brand used (Visa, MasterCard, JCB)
2	period	Integer	❌	Installment term (number of months)
3	payment_per_period	Integer	❌	Amount to be paid per period (VND)
4	bank_code	String(6)	❌	Card-issuing bank code

Token Information (token_result)

No.	Parameter	Data Type	Required	Description
1	result_code	Integer	❌	Token creation status
2	result_message	String	❌	Message
3	source_type	String	❌	Source type: ACCOUNT or CARD
4	token_info	Object	❌	Token information

Token Information (token_info)

No.	Parameter	Data Type	Required	Description
1	token	String	❌	Token string saved on Baokim
2	expired_at	Datetime	❌	Token expiration time
3	status	Integer	❌	Token status: 1 = Active, 0 = Deactive
4	bank_name	String	❌	Full bank name
5	holder_name	String	❌	Card/account holder name
6	issue_date	String	❌	Card/account expiration date
7	number	String	❌	Masked card number or account number
8	bank_short_name	String	❌	Bank short name

Request Example

{
  "request_id": "1e3fe73d3054904a9a4bb",
  "request_time": "2025-10-02 08:13:30",
  "master_merchant_code": "BAOKIMMASTERMERCHANT",
  "operation": "PAYMENT_TRANS",
  "sub_merchant_code": "BAOKIMSUBMERCHANT",
  "payment_result": {
    "result_code": 200,
    "result_message": "Payment successful",
    "order": {
      "id": 4412312,
      "mrc_order_id": "BK_021_ANC",
      "total_amount": 0,
      "payment_method": 22,
      "status": 1,
      "customer_info": {
        "code": "KH001",
        "name": "Nguyen Van A",
        "email": "[email protected]",
        "phone": "0812345678",
        "address": "313 Truong Chinh, Khuong Mai, Thanh Xuan, Ha Noi",
        "gender": 1,
        "type": 1
      },
      "completed_at": "2025-10-02 08:13:30",
      "created_at": "2025-10-02 08:13:30",
      "updated_at": "2025-10-02 08:13:30"
    },
    "transactions": [
      {
        "id": 1163423,
        "type": 1,
        "payment_method": 22,
        "sub_merchant_fee": 3300,
        "master_merchant_fee": 1100,
        "master_merchant_model": 1,
        "user_fee": 0,
        "total_amount": 0,
        "amount": -3300,
        "description": "Payment for order",
        "status": 1,
        "bnpl": {
          "payment_per_month": null,
          "paylater_amount": null,
          "down_payment": null,
          "provider": null
        },
        "installment": {
          "card_brand": null,
          "period": null,
          "payment_per_period": null,
          "bank_code": null
        },
        "completed_at": "2025-10-02 08:13:30",
        "created_at": "2025-10-02 08:13:30",
        "updated_at": "2025-10-02 08:13:30"
      }
    ]
  },
  "token_result": {
    "result_code": 200,
    "result_message": "Token create successful",
    "source_type": "ACCOUNT",
    "token_info": {
      "token": "Mq7AwLoHkafPdXYxvYedH8sb6MZ18k",
      "expired_at": "2050-10-13 21:16:30",
      "status": 1,
      "bank_name": "Ngân hàng TMCP Ngoại thương Việt Nam",
      "holder_name": "NGUYEN VAN A",
      "issue_date": "03/07",
      "number": "970407xxxxxx1234",
      "bank_short_name": "VCB"
    }
  }
}

Response

(Merchant responds to Baokim)

Main Parameters

No	Parameter	Data Type	Required	Description
1	code	Integer	✅	Result code. 0 = Merchant processed webhook successfully
2	message	String	✅	Processing result message
3	data	Object	❌	Returned data (if any)

Response Example

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