Skip to main content

Xử lý kết quả kiểm tra chương trình khuyến mãi

Khi việc kiểm tra chương trình khuyến mãi (Promotion) hoàn tất, Zengi sẽ thông báo cho đối tác các thông tin khuyến mãi và số tiền áp dụng cho giao dịch.

Đối tác cần xây dựng một callBackUrl để nhận các thông tin này từ hệ thống Zengi. Sau đây là hướng dẫn chi tiết để thực hiện xây dựng webhook/callbackUrl.

1. Các thông số kỹ thuật của callBackUrl:​

  • CallBackUrl là một POST API được xây dựng ở phía đối tác và được đối tác cung cấp cho Zengi.
  • Định dạng dữ liệu truyền tải sử dụng kiểu application/json.

Yêu cầu kết nối (Request)​

curl -X 'POST' \
  'https://<domain_cua_doi_tac>/promotion' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Signature: d7a15a0756743...' \
  -d '{
    "provider_code": "PROV_001",
    "campaign_code": "SUMMER_SALE_2026",
    "original_amount": 1500000,
    "discount_amount": 200000,
    "amount": 1300000
  }'

Danh sách các tham số body request:​

Thuộc tínhKiểu dữ liệuBắt buộcMô tảVí dụ
provider_codeStringCóMã nhà cung cấp hoặc đối tác vận hành chương trình khuyến mãi."PROV_001"
campaign_codeStringCóMã chiến dịch khuyến mãi được áp dụng cho giao dịch."SUMMER_SALE_2026"
original_amountLong / BignumCóSố tiền gốc của hóa đơn trước khi áp dụng giảm giá.1500000
discount_amountLong / BignumCóSố tiền được giảm giá từ chương trình khuyến mãi.200000
amountLong / BignumCóSố tiền cuối cùng khách hàng phải thanh toán sau giảm giá (original_amount - discount_amount).1300000

2. Cơ chế xác thực và Bảo mật (X-Signature)​

Để đảm bảo toàn vẹn dữ liệu và chống giả mạo, Zengi sử dụng thuật toán HMAC-SHA256 để ký số vào mỗi request gửi sang đối tác.

Quy trình tạo chữ ký phía Zengi:​

  1. Sắp xếp tất cả các thuộc tính trong JSON body theo thứ tự Alphabet của Key (mức root).
  2. Nối các cặp key=value lại với nhau bằng ký tự & để tạo thành một chuỗi thô (Raw String).
  3. Sử dụng Secret_Key (do Zengi cấp riêng cho từng đối tác) để băm chuỗi thô bằng thuật toán HMAC-SHA256, đầu ra là một chuỗi dạng Hex.
  4. Đính kèm chuỗi chữ ký này vào HTTP Header với tên X-Signature.

Chuỗi thô (Raw String) mẫu từ ví dụ trên:

amount=1300000&campaign_code=SUMMER_SALE_2026&discount_amount=200000&original_amount=1500000&provider_code=PROV_001

Yêu cầu xác thực phía Đối tác:​

Khi nhận được request, đối tác phải lấy chuỗi X-Signature từ Header, tự tính toán lại chữ ký từ JSON body nhận được với Secret_Key đang lưu trữ, sau đó so sánh hai chuỗi chữ ký này với nhau. Nếu không trùng khớp, đối tác lập tức từ chối request bằng mã lỗi 401 Unauthorized.

3. Kết quả phản hồi từ phía Đối tác (Response)​

Phía đối tác sau khi xác thực chữ ký số thành công và xử lý nhận dữ liệu xong cần phản hồi lại cho Zengi theo định dạng JSON để xác nhận trạng thái:

{
  "status": "SUCCESS",
  "code": "00",
  "message": "Promotion result received successfully."
}
{
  "status": "ERROR",
  "code": "99",
  "message": "Internal server error occurred."
}