Webhook

Flow

Description:

• Webhook is a method to notify transaction results to Merchant via HTTP POST request.
• Webhook URL is configured when Merchant provides information to Baokim.
• If Merchant receives webhook and processes it successfully, please respond with code = 0.
• If Merchant responds with code other than 0, Baokim will resend webhook within 10 times, each time 5 minutes apart.

Steps to verify and process webhook receipt

1. Verify data integrity via Signature.
2. Verify order/transaction status, payment amount.
3. Actively verify and avoid recording duplicate transactions when receiving webhook multiple times.

API Information

Method: POST

URL: (URL configured by Merchant with Baokim)

Request Headers:

Header	Description
Signature	Digital signature to verify data integrity

Request

(Baokim sends to Merchant)

Main Parameters Table

Field Name	Data Type	Required	Description
request_id	String	✅	Request ID
request_time	Datetime	✅	Request time. Format: YYYY-MM-DD HH:mm:ss
merchant_code	String	✅	Merchant identifier code
operation	String	✅	Operation type. PAYMENT_TRANS = payment transaction
payment_result	Object	✅	Payment result
token_result	Object	❌	Token information (NULL if not token payment)

Order Information (payment_result)

Field	Type	Required	Description
result_code	integer	✅	Transaction processing result code. 200 = success
result_message	string	✅	Transaction result description
order	object	✅	Order information
transaction	array<object>	✅	List of transactions from order

Order Information (payment_result.order)

Field	Type	Required	Description
id	integer	✅	Order ID in system
mrc_order_id	string	✅	Merchant's order ID
total_amount	integer	✅	Total order value (VND)
payment_method	integer	✅	Payment method
status	integer	✅	Order status. 1 = completed
completed_at	string	❌	Completion time (YYYY-MM-DD HH:mm:ss)
created_at	string	✅	Order creation time (YYYY-MM-DD HH:mm:ss)
updated_at	string	✅	Last update time (YYYY-MM-DD HH:mm:ss)

Transaction Information (payment_result.transaction)

Field	Type	Required	Description
id	integer	✅	Transaction ID in system
order_id	integer	✅	Associated order ID
mrc_order_id	string	✅	Merchant's order ID
type	integer	✅	Transaction type. 1 = payment
payment_method	integer	✅	Payment method
merchant_fee	integer	✅	Merchant fee (VND)
user_fee	integer	✅	User fee (VND)
amount	integer	✅	Original order amount (VND)
total_amount	integer	✅	Total amount user actually paid = amount + user_fee (VND)
description	string / null	❌	Transaction description
status	integer	✅	Transaction status. 1 = completed
bnpl	object / null	❌	BNPL payment information (if applicable)
installment	object / null	❌	Installment payment information (if applicable)
completed_at	string	❌	Transaction completion time (YYYY-MM-DD HH:mm:ss)
created_at	string	✅	Transaction creation time (YYYY-MM-DD HH:mm:ss)
updated_at	string	✅	Last update time (YYYY-MM-DD HH:mm:ss)

Token Information (token_result)

Field Name	Data Type	Required	Description
token	String	❌	Card token saved on Baokim
card.bank_name	String	❌	Full issuing bank name
card.holder_name	String	❌	Card holder name
card.issue_date	String	❌	Card expiration date
card.number	String	❌	Masked card number (e.g.: 970407xxxxxx1234)
card.bank_short_name	String	❌	Issuing bank short name

Request Example

{
  "request_id": "B2B6A278C9815BD7EQ4AVPVZCI",
  "request_time": "2026-06-09 10:46:32",
  "merchant_code": "123workvn",
  "operation": "PAYMENT_TRANS",
  "payment_result": {
    "result_code": 200,
    "result_message": "Payment successful",
    "order": {
      "id": 991186,
      "mrc_order_id": "MERCHANT_DEPOSIT_48_1780976739_UXWUUAIE",
      "total_amount": 10000,
      "payment_method": 1,
      "status": 1,
      "completed_at": "2026-06-09 10:46:32",
      "created_at": "2026-06-09 10:45:41",
      "updated_at": "2026-06-09 10:46:32"
    },
    "transaction": [
      {
        "id": 940826,
        "order_id": 991186,
        "mrc_order_id": "MERCHANT_DEPOSIT_48_1780976739_UXWUUAIE",
        "type": 1,
        "payment_method": 1,
        "merchant_fee": 0,
        "user_fee": 330,
        "total_amount": 10330,
        "amount": 10000,
        "description": null,
        "status": 1,
        "bnpl": null,
        "installment": null,
        "completed_at": "2026-06-09 10:46:32",
        "created_at": "2026-06-09 10:45:45",
        "updated_at": "2026-06-09 10:46:32"
      }
    ]
  },
  "token_result": null
}

Response

(Merchant returns to Baokim)

note

HTTP 200 - Success

Main Parameters Table

Field Name	Data Type	Required	Description
code	Integer	✅	0 = success, other = Baokim will resend webhook
message	String	✅	Response content
data	Object	❌	Additional data (if any)

Success Response Example

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

Error Codes

Error Code	Description
104	Authentication error
105	Invalid digital signature