Webhook thanh toán

Quy trình

Mô tả:

• Sau khi nhận được kết quả thanh toán từ Ngân hàng hợp tác, Baokim sẽ gửi webhook cho merchant.
• Nếu Merchant xử lý thành công, vui lòng response với code = 0.
• Nếu response code khác 0, Baokim sẽ gửi lại webhook 10 lần, mỗi lần cách nhau 5 phút.

Thông tin API

Method: POST

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

Header yêu cầu:

Header	Kiểu dữ liệu	Mô tả
Signature	string	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

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	request_id	String	✅	ID request
2	request_time	Datetime	✅	Thời gian request. Format: YYYY-MM-DD H:m:s
3	master_merchant_code	String(50)	✅	Mã master merchant
4	sub_merchant_code	String(50)	✅	Mã sub merchant
5	operation	String	✅	Loại webhook: PAYMENT_TRANS hoặc REFUND_TRANS
6	payment_result	Object	✅	Kết quả thanh toán
7	token_result	Object	❌	Thông tin token (NULL nếu không phải thanh toán lưu token)

Thông tin payment_result

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	result_code	Integer	✅	Trạng thái thanh toán
2	result_message	String	✅	Message kết quả
3	order	Object	✅	Thông tin đơn hàng
4	transactions	Array of Object	✅	Danh sách giao dịch

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

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	id	Integer	✅	Mã đơn hàng Baokim
2	mrc_order_id	String	✅	Mã đơn hàng merchant (NULL nếu thanh toán từ VA tĩnh)
3	total_amount	Integer	✅	Số tiền đơn hàng
4	payment_method	Integer	✅	Phương thức thanh toán: 1 = VA, 2 = BNPL, 3 = Thẻ tín dụng, 4 = Trả góp thẻ, 5 = ATM, 6 = VNPayQR, 22 = Auto debit
5	status	Integer	✅	Trạng thái: 1 = Thành công, 6 = Chờ TT trả trước, 9 = Đã hoàn, 13 = Thất bại
6	customer_info	Object	❌	Thông tin khách hàng
7	completed_at	Datetime	✅	Thời gian thành công
8	created_at	Datetime	✅	Thời gian tạo
9	updated_at	Datetime	✅	Thời gian cập nhật cuối

Thông tin khách hàng (payment_result.order.customer_info)

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	code	String	❌	Mã khách hàng
2	name	String	❌	Tên khách hàng
3	email	String	❌	Email khách hàng
4	phone	String	❌	SĐT khách hàng
5	address	String	❌	Địa chỉ khách hàng
6	gender	Integer	❌	Giới tính: 1 = Male, 2 = Female
7	type	Integer	❌	Loại khách hàng: 1 = Cá nhân, 2 = Doanh nghiệp

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

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	id	Integer	✅	Mã giao dịch Baokim
2	type	Integer	✅	Loại giao dịch: 1 = Thanh toán, 2 = Hoàn tiền
3	payment_method	Integer	✅	Phương thức thanh toán: 1 = VA, 2 = BNPL, 3 = Thẻ tín dụng, 4 = Trả góp thẻ, 5 = ATM, 6 = VNPayQR, 22 = Auto debit
4	sub_merchant_fee	Integer	✅	Phí sub merchant chịu
5	master_merchant_fee	Integer	✅	Phí master merchant chịu
6	master_merchant_model	Integer	✅	Mô hình master merchant
7	user_fee	Integer	✅	Phí user chịu
8	total_amount	Integer	✅	Tổng tiền khách hàng thanh toán sau phí
9	amount	Integer	✅	Số tiền biến động số dư sub merchant
10	description	String	❌	Nội dung giao dịch
11	status	Integer	✅	Trạng thái: 0 = Khởi tạo, 1 = Thành công, 2 = Thất bại, 3 = Pending
12	bnpl	Object	❌	Thông tin BNPL (nếu là giao dịch BNPL)
13	installment	Object	❌	Thông tin trả góp (nếu là giao dịch trả góp)
14	completed_at	Datetime	✅	Thời gian thành công
15	created_at	Datetime	✅	Thời gian tạo đơn hàng
16	updated_at	Datetime	✅	Thời gian cập nhật cuối

Thông tin BNPL (payment_result.transactions.bnpl)

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	payment_per_month	Integer	❌	Số tiền cần thanh toán từng tháng (VNĐ)
2	paylater_amount	Integer	❌	Số tiền trả sau (VNĐ)
3	down_payment	Integer	❌	Số tiền trả trước (VNĐ)
4	provider	String	❌	Mã nhà cung cấp

Thông tin trả góp (payment_result.transactions.installment)

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	card_brand	String	❌	Thương hiệu thẻ sử dụng (Visa, MasterCard, JCB)
2	period	Integer	❌	Kỳ hạn trả góp (số tháng)
3	payment_per_period	Integer	❌	Số tiền phải thanh toán theo kỳ (VNĐ)
4	bank_code	String(6)	❌	Mã ngân hàng phát hành thẻ

Thông tin token (token_result)

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	result_code	Integer	❌	Trạng thái tạo token
2	result_message	String	❌	Message
3	source_type	String	❌	Loại nguồn: ACCOUNT hoặc CARD
4	token_info	Object	❌	Thông tin token

Thông tin token (token_info)

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	token	String	❌	Chuỗi token lưu trên Baokim
2	expired_at	Datetime	❌	Thời gian hết hạn token
3	status	Integer	❌	Trạng thái token: 1 = Active, 0 = Deactive
4	bank_name	String	❌	Tên đầy đủ ngân hàng phát hành
5	holder_name	String	❌	Tên chủ thẻ/tài khoản
6	issue_date	String	❌	Ngày hết hạn thẻ/tài khoản
7	number	String	❌	Số thẻ (mask) hoặc số tài khoản
8	bank_short_name	String	❌	Tên viết tắt ngân hàng

Ví dụ Request

{
  "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 Trường Chinh, Khương Mai, Thanh Xuân, Hà Nội",
        "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": "Thanh toán đơn hàng",
        "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 trả lại cho Baokim)

Bảng tham số chính

STT	Tham số	Kiểu dữ liệu	Bắt buộc	Mô tả
1	code	Integer	✅	0 = Thành công, khác 0 = Baokim sẽ gửi lại webhook
2	message	String	✅	Nội dung phản hồi
3	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": {}
}