Xử lý kết quả thanh toán thẻ

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	aid	string	ID của app thực hiện giao dịch thẻ
2	amount	string	Số tiền giao dịch
3	appName	string	Tên app thực hiện giao dịch thẻ
4	approveCode	string	Mã chuẩn chi
5	batchNo	string	số lô
6	billId	string	Mã Bill được sinh ra từ phía Merchant của đối tác
7	cardHolder	string	Tên chủ thẻ
8	cardNumber	string	Số thẻ được cắt cụt
9	cardScheme	string	VISA, JCB, MASTER, AMEX, UPI
10	currency	string	Loại tiền giao dịch
11	deviceId	string	Số serial_number của máy
12	expDate	string	Ngày hết hạn thẻ
13	extraData	string	Nội dung mở rộng nhận từ đối tác
14	id	string	ID của giao dịch
15	invoiceNo	string	Số hóa đơn
16	isoResponseCode	string	Kết quả giao dịch, 00 - Thành công, kết quả khác 00 là lỗi.
17	merchantAddress	string	Địa chỉ của Merchant
18	merchantId	string	Merchant ID
19	merchantName	string	Merchant Name
20	merchantTransId	string	Mã giao dịch của Merchant
21	mid	string	merchantId
22	paymentType	string	Loại giao dịch. Mặc định nhận giá trị là "card"
23	refId	string	Mã tham chiếu được Acquirer bank trả về khi thực hiện giao dịch thành công đối với giao dịch Sale, PreAuth, PreAuth-Complete và Settlement
24	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
25	status	string	Trạng thái giao dịch
26	swipeType	string	Hình thức giao dịch, CL - contact, CLS - Contactless
27	tc	string	Mã TC của giao dịch thẻ
28	tid	string	terminalId
29	traceNo	string	số trace
30	transDateTime	string	Thời gian giao dịch, có dạng yyyymmddhhmmss
31	transactionType	string	Loại giao dịch. Nhận các giá trị: SALE, VOID, SETTLEMENT
32	settlementList	array object	Danh sách giao dịch đã Settlement thành công. Chỉ áp dụng cho Settlement Callback.
32.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
32.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ụ:

{
    "aid": "A0000000041010",
    "amount": "123456",
    "appName": "Debit Mastercard",
    "approveCode": "000000",
    "batchNo": "000001",
    "billId": "",
    "cardHolder": "CARDHOLDER/OCB",
    "cardNumber": "529183******1825",
    "cardScheme": "5",
    "currency": "VND",
    "deviceId": "1495222030",
    "expDate": "",
    "extraData": "{}",
    "id": "20250528160901",
    "invoiceNo": "000014",
    "isoResponseCode": "00",
    "merchantAddress": "17 TONG DAN HOAN KIEM, HN",
    "merchantId": "000000000000001",
    "merchantName": "Tam Test QR PC2POS",
    "merchantTransId": "20250528160901",
    "mid": "",
    "parent_id": "",
    "paymentType": "card",
    "refId": "438498133462",
    "reqId": "",
    "status": "SUCCESS",
    "swipeType": "C",
    "tc": "40CCCC727D454654",
    "tid": "",
    "traceNo": "000021",
    "transDateTime": "20250528160917",
    "transaction_type": "SALE",
    "settlementList":[{
        "reqID":"...",
        "refNo":"..."
    }]
}

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ừ