Webhook

Quy trình

Mô tả:

• Webhook là phương thức thông báo kết quả giao dịch cho Merchant qua yêu cầu HTTP POST.
• URL API webhook được cấu hình khi Merchant khai báo thông tin với Baokim.
• Nếu Merchant nhận được webhook và xử lý thành công, vui lòng response với code = 0.
• Nếu Merchant response với code khác 0, Baokim sẽ gửi lại webhook trong vòng 10 lần, mỗi lần cách nhau 5 phút.

Các bước kiểm tra và xử lý khi nhận webhook

1. Kiểm tra tính toàn vẹn dữ liệu qua Signature.
2. Kiểm tra trạng thái đơn hàng/giao dịch, số tiền thanh toán.
3. Chủ động kiểm tra và tránh ghi nhận duplicate giao dịch khi nhận webhook nhiều lần.

Thông tin API

Method: POST

URL: (URL do Merchant cấu hình với Baokim)

Header yêu cầu:

Header	Mô tả
Signature	Chữ ký số để xác thực tính toàn vẹn dữ liệu

Request

(Baokim gửi tới Merchant)

Bảng tham số chính

Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
request_id	String	✅	ID request
request_time	Datetime	✅	Thời gian request. Format: YYYY-MM-DD HH:mm:ss
merchant_code	String	✅	Mã định danh merchant
operation	String	✅	Loại thao tác. PAYMENT_TRANS = giao dịch thanh toán
payment_result	Object	✅	Kết quả thanh toán
token_result	Object	❌	Thông tin token (NULL nếu không phải thanh toán lưu token)

Thông tin đơn hàng (payment_result)

Trường	Kiểu	Bắt buộc	Mô tả
result_code	integer	✅	Mã kết quả xử lý giao dịch. 200 = thành công
result_message	string	✅	Mô tả kết quả giao dịch
order	object	✅	Thông tin đơn hàng
transaction	array<object>	✅	Danh sách giao dịch phát sinh từ đơn hàng

Thông tin đơn hàng (payment_result.order)

Trường	Kiểu	Bắt buộc	Mô tả
id	integer	✅	ID đơn hàng trong hệ thống
mrc_order_id	string	✅	Mã đơn hàng do merchant tạo
total_amount	integer	✅	Tổng giá trị đơn hàng (VNĐ)
payment_method	integer	✅	Phương thức thanh toán
status	integer	✅	Trạng thái đơn hàng. 1 = hoàn thành
completed_at	string	❌	Thời điểm hoàn thành (YYYY-MM-DD HH:mm:ss)
created_at	string	✅	Thời điểm tạo đơn hàng (YYYY-MM-DD HH:mm:ss)
updated_at	string	✅	Thời điểm cập nhật gần nhất (YYYY-MM-DD HH:mm:ss)

Thông tin giao dịch (payment_result.transaction)

Trường	Kiểu	Bắt buộc	Mô tả
id	integer	✅	ID giao dịch trong hệ thống
order_id	integer	✅	ID đơn hàng liên kết
mrc_order_id	string	✅	Mã đơn hàng do merchant tạo
type	integer	✅	Loại giao dịch. 1 = thanh toán
payment_method	integer	✅	Phương thức thanh toán
merchant_fee	integer	✅	Phí do merchant chịu (VNĐ)
user_fee	integer	✅	Phí do người dùng chịu (VNĐ)
amount	integer	✅	Số tiền gốc của đơn hàng (VNĐ)
total_amount	integer	✅	Tổng tiền thực tế người dùng thanh toán = amount + user_fee (VNĐ)
description	string / null	❌	Mô tả giao dịch
status	integer	✅	Trạng thái giao dịch. 1 = hoàn thành
bnpl	object / null	❌	Thông tin thanh toán mua trước trả sau (nếu có)
installment	object / null	❌	Thông tin thanh toán trả góp (nếu có)
completed_at	string	❌	Thời điểm hoàn thành giao dịch (YYYY-MM-DD HH:mm:ss)
created_at	string	✅	Thời điểm tạo giao dịch (YYYY-MM-DD HH:mm:ss)
updated_at	string	✅	Thời điểm cập nhật gần nhất (YYYY-MM-DD HH:mm:ss)

Thông tin token (token_result)

Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
token	String	❌	Chuỗi token thẻ lưu trên Baokim
card.bank_name	String	❌	Tên đầy đủ ngân hàng phát hành
card.holder_name	String	❌	Tên chủ thẻ
card.issue_date	String	❌	Ngày hết hạn thẻ
card.number	String	❌	Số thẻ dạng mask (VD: 970407xxxxxx1234)
card.bank_short_name	String	❌	Tên viết tắt ngân hàng phát hành

Ví dụ Request

{
  "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 trả lại cho Baokim)

ghi chú

HTTP 200 - Thành công

Bảng tham số chính

Tên trường	Kiểu dữ liệu	Bắt buộc	Mô tả
code	Integer	✅	0 = thành công, khác 0 = Baokim sẽ gửi lại webhook
message	String	✅	Nội dung phản hồi
data	Object	❌	Dữ liệu đính kèm (nếu có)

Ví dụ Response thành công

{
  "code": 0,
  "message": "Thành công"
  "data": { }
}

Error Codes

Mã lỗi	Mô tả
104	Lỗi xác thực
105	Chữ ký số không hợp lệ