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 ngay cả khi giao dịch này có thành công hay không. 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.

IPN - Instant Payment Notification

Hệ thống của Zengi sử dụng callbackUrl được đối tác cung cấp theo thứ tự ưu tiên như sau để gửi HTTP POST request với cấu trúc bên dưới đến hệ thống đối tác.

Thứ tự ưu tiên của callbackUrl

• Ư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.

Cấu trúc IPN

No	Tên field	Loại dữ liệu	Ý nghĩa
1	id	string	ID của giao dịch
2	billId	string	Mã Bill được sinh ra từ phía Merchant của đối tác
3	reqID	string	Mã request được sinh ra từ phía đối tác khi khởi tạo giao dịch và gửi sang Zengi
4	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
5	approveCode	string	Mã chuẩn chị, chỉ có giá trị đối với giao dịch Sale, preAuth, preAuth-Complete
6	deviceId	string	Số serial_number của máy
7	amount	string	Số tiền giao dịch
8	status	string	Trạng thái giao dịch
9	transactionType	string	Loại giao dịch. Nhận các giá trị: SALE, VOID, SETTLEMENT
10	paymentType	string	Loại giao dịch. Mặc định nhận giá trị là "card"
11	cardScheme	string	VISA, JCB, MASTER, AMEX, UPI
12	tid	string	terminalId
13	mid	string	merchantId
14	emvData	json object	Dữ liệu EMV kết quả thanh toán thẻ
15	bathcNo	string	Số lô của giao dịch
16	settlementList	array object	Danh sách giao dịch đã Settlement thành công. Chỉ áp dụng cho Settlement Callback.
17	reqID	string	là mã UUID 4 do đối tác sinh và gửi cho Zengi qua các api giao dịch
18	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ụ:

{
    "id": " ..",
    "billID":"...",
    "reqID":" ...",
    "refID":"...",
    "approveCode":"...",
    "deviceId":"...",
    "amount":"...",
    "status":"...",
    "transactionType":"...",
    "paymentType":"card",
    "cardScheme":"VISA",
    "tid":"...",
    "mid":"...",
    "serialNumber":"...",
    "emvData":{...},
    "settlementList":[{
        "reqID":"...",
        "refNo":"..."
    }]
}

EMV Data:

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	appName	string	Tên app thực hiện giao dịch thẻ
3	approveCode	string	Mã chuẩn chi
4	batchNo	string	số lô
5	cardHolder	string	Tên chủ thẻ
6	cardNumber	string	Số thẻ được cắt cụt
7	cardType	string	CardType: 1 - International (Visa, AMEX, JCB), 2 - Domestic (Napas), 3 - Mastercard
8	currency	string	Loại tiền giao dịch
9	expDate	string	Ngày hết hạn thẻ
10	invoiceNo	string	Số hóa đơn
11	isoResponseCode	string	Kết quả giao dịch, 00 - Thành công, kết quả khác 00 là lỗi.
12	merchantAddress	string	Địa chỉ của Merchant
13	merchantId	string	Merchant ID
14	merchantTransId	string	Mã giao dịch của Merchant
15	refNo	string	Mã tham chiếu
16	swipeType	string	Hình thức giao dịch, CL - contact, CLS - Contactless
17	tc	string	Mã TC của giao dịch thẻ
18	terminalId	string	terminalId
19	totalAmount	string	Giá trị giao dịch
20	traceNo	string	số trace
21	transDateTime	string	Thời gian giao dịch, có dạng yyyymmddhhmmss

Ví dụ:

{   "id": " ..",
    "billID":"...",
    ...................
    "emvData":{
        "aid":"A0000000031010",
        "appName":"STB VISA CARD",
        "approveCode":"759497",
        "batchNo":"000019",
        "cardHolder":"/",
        "cardNumber":"423238******4712",
        "cardType":"1",
        "currency":"VND",
        "expDate":"",
        "invoiceNo":"000059",
        "isoResponseCode":"00",
        "merchantAddress":"117-119 LY CHINH THANG 117-119 LY CHINH THANG",
        "merchantId":"111111111111111",
        "merchantName":"Zengi",
        "merchantTransId":"20241210095518",
        "refNo":"419029268510",
        "swipeType":"CLS",
        "tc":"16212A24C734483D",
        "terminalId":"11111111",
        "totalAmount":"1000",
        "traceNo":"000191",
        "transDateTime":"20241210095532"
    }

}

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ừ