Xử lý kết quả Settlement

Khi việc xử lý thanh toán hoàn tất, Zengi sẽ thông báo cho đối tác các thông tin giao dịch liên quan. Các giao dịch mà Zengi sẽ thông báo đến đối tác gồm có:

• Các lệnh giao dịch như Sale, Void, PreAuth, PreAuth-Complete và Settlement.
• Ngoại trừ các lệnh hệ thống như: Logon, Reversal và Batch Upload.

Đối tác cần xây dựng một callBackUrl để nhận các thông tin giao dịch này. Sau đây là một số hướng dẫn để thực hiện xây dựng callbackUrl này.

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ư sau:

curl -X 'POST' \
  'https://<domain của đối tác>/ipn' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": "IPN đã được mã hóa",
}'

• Zengi có thể hỗ trợ thực hiện gọi callBackUrl theo thứ tự sau;
  • Ưu tiên 1: dùng callBackUrl được đối tác cung cấp trong mỗi lệnh giao dịch.
  • Ưu tiên 2: dùng callBackUrl được đối tác cung cấp khi đăng kí tài khoản.

Lưu ý

Zengi khuyến khích đối tác chỉ dùng 1 callBackurl duy nhất được đăng kí trước với Zengi để bảo đảm về tính ổn định và bảo mật.

2. Yêu cầu bảo mật

• CallBackUrl này cần bảo đảm một số tiêu chí bảo mật như sau:
  • Sử dụng HTTPS protocol
  • Đối tác cần cung cấp địa chỉ IP của CallbackUrl này cho Zengi, đồng thời Zengi cũng sẽ cung cấp IP của dịch vụ sẽ thực hiện gọi callbackUrl này cho đối tác để 2 bên thực hiện whitelist IP.
  • Nội dung payload của callBackUrl sẽ được zengi mã hóa toàn phần bằng thuận toán AES-256 với key do Zengi cung cấp. Do đó, khi nhận được thông tin do Zengi gửi sang callBackUrl này, đối tác cần thực hiện giải mã dữ liệu trước khi sử dụng.
  • Để bảo đảm tính toàn vẹn dữ liệu, Zengi có sử dụng thuật toán HMAC-256 để kí trên các trường dữ liệu quan trọng theo thỏa thuận bởi Zengi với từng đối tác hoặc toàn bộ dữ liệu IPN được đề cập sau đây.
  • Quy trình xử lý mã hóa như sau:

• Chi tiết hơn về phần mã hóa AES
• Chi tiết hơn về phần kí HMAC-SHA256

3. IPN - Instant Payment Notification

Chi tiết về cấu trúc của IPN do Zengi gửi cho đối tác như sau:

Cấu trúc IPN

No	Tên field	Loại dữ liệu	Ý nghĩa
1	batchNo	string	số lô
2	callbackUrl	string	callBackUrl để nhận các thông tin giao dịch
3	deviceId	string	Số serial_number của máy
4	extraData	string	Nội dung mở rộng nhận từ đối tác
5	id	string	ID của giao dịch. Ghi chú: ID này sẽ được dùng để đưa vào field transactionId khi gọi lệnh VOID
6	merchantTransId	string	Mã giao dịch của Merchant
7	mid	string	merchantId
8	quantity	string	Đếm (số giao dịch SALE – số giao dịch VOID)
9	reqId	string	Mã UUID 4 được sinh ra từ phía đối tác khi khởi tạo giao dịch và gửi sang Zengi
10	saleQuantity	string	Số lượng giao dịch SALE
11	saleTotalAmount	string	Tổng tiền giao dịch SALE
12	status	string	Trạng thái giao dịch
13	tid	string	terminalId
14	totalAmount	string	Tổng tiền giao dịch SALE và VOID
15	transaction_time	string	Thời gian giao dịch, có dạng yyyymmddhhmmss
16	transaction_type	string	Loại giao dịch. Nhận các giá trị: SALE, VOID, SETTLE
17	voidQuantity	string	Số lượng giao dịch VOID
18	voidTotalAmount	string	Tổng tiền giao dịch VOID
19	settlementList	array object	Danh sách giao dịch đã Settlement thành công. Chỉ áp dụng cho Settlement Callback.
19.1	settlementList - reqId	string	là mã UUID 4 do đối tác sinh và gửi cho Zengi qua các api giao dịch
19.2	settlementList - refNo	string	là mã giao dịch do các Acquirer gửi Zengi sau khi thực hiện giao dịch thành công.

Ví dụ:

{
    "batchNo":"000018",
    "callbackUrl":"",
    "deviceID":"",
    "extraData":"",
    "id":"",
    "merchantTransId":"",
    "mid":"",
    "quantity":"2",
    "reqId":"86b9b3ed-6a8d-4c8b-8c0a-a793e168dc66",
    "request_body":"",
    "response":"",
    "saleQuantity":"3",
    "saleTotalAmount":"36000",
    "settlementList":[
        {
            "refNo":"091729116223",
            "reqId":"c9f46985-c1d4-4034-abca-c0a4173dd518"
        },
        {
            "refNo":"751064092623",
            "reqId":"816ee092-cd98-4f01-9f9a-ba1a9690036a"
        },
        {
            "refNo":"347447699209",
            "reqId":"6b5f4c5f-2213-496e-8471-d57da4167990"
        },
        {
            "refNo":"751064092623",
            "reqId":"3f97c3f5-c080-48d4-a43d-810cee3ff788"
        }
    ],
    "status":"",
    "tid":"",
    "totalAmount":"24000",
    "transaction_time":"2025-06-17T14:10:21Z",
    "transaction_type":"SETTLE",
    "voidQuantity":"12000",
    "voidTotalAmount":"12000"
}

Các biến thường dùng trong xử lý thông tin giao dịch thẻ

AID thông dụng:

AID (Application Identifier)	Vendor	Tên	Diễn giải	Loại
A0000000031010	Visa International	VISA Debit/Credit (Classic)	Standard/Gold VISA credit card	EMV
A00000000401	Mastercard International	MasterCard Credit/Debit (Global)	Standard MasterCard	EMV
A0000000651010	JCB CO., LTD.	JCB J Smart Credit	Japan Credit Bureau	EMV
A000000333010101	China Unionpay Co. Ltd	UnionPay Debit	UnionPay Debit	EMV
A000000333010102	China Unionpay Co. Ltd	UnionPay Credit	UnionPay Credit	EMV
A0000000250000	American Express	American Express	American Express (Credit/Debit)	EMV

SwipeType: Các mã dành miêu tả thao tác thanh toán thẻ

Mã	Diễn giải
F	Fallback: Giao dịch được thực hiện khi chip thẻ bị hỏng
C	Chip: Giao dịch được thực hiện bằng cách đọc thẻ chip
CTL	Contactless: Giao dịch được thực hiện bằng NFC
M	Manual: Giao dịch được thực hiện bằng cách nhập thông tin thẻ trực tiếp trên máy
S	Swipe: Giao dịch được thực hiện bằng thẻ từ