Payment Notification
Xử lý kết quả thanh toán
Khi việc xử lý thanh toán hoàn tất, MoMo 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.
Giao diện (Redirect)
Sau khi luồng thanh toán hoàn tất, khách hàng được điều hướng đến redirectUrl mà bên đối tác đã cung cấp trong create request. Một vài thông số sẽ được thêm vào URL theo dạng sau:
Method: GET
redirectUrl ?{parameters}
IPN - Instant Payment Notification
Hệ thống của MoMo sử dụng API được khai báo trong ipnUrl để gửi HTTP request với cấu hình bên dưới đến hệ thống đối tác.
Method: POST
| Attribute | Value | Description |
|---|---|---|
| URL | ipnUrl | URL |
| Method | POST | Phương thức của HTTP request |
| Headers | Content-type: application/json | HTTP Headers |
| Payload | Result Transaction | Nội dung của HTTP body |
Mẫu Request IPN
curl -X 'POST' 'https://example.com/momo_ipn' -H 'content-type: application/json' -d $'{"partnerCode":"MOMOIOLD20190129","orderId":"01234567890123451633504872421","requestId":"01234567890123451633504872421","amount":1000,"orderInfo":"Test Thue 1234556","orderType":"momo_wallet","transId":2588659987,"resultCode":0,"message":"Giao dịch thành công.","payType":"qr","responseTime":1633504902954,"extraData":"eyJyZXN1bHRfbmFtZXNwYWNlIjoidW1hcmtldCIsImVycm9yIjoiIiwic3RhdGUiOjZ9","signature":"90482b3881bdf863d5f61ace078921bbc6dbb58b2fded35261c71c9af3b1ce4f"}'
Reponse của đối tác sẽ đến MoMo sau khi MoMo gửi HTTP request đến địa chỉ ipnUrl.
Bên đối tác cần phản hồi với HTTP code 204 (không cần gửi thêm nội dung)!
Lưu ý: Đối tác cần phản hồi lại trong vòng 30 giây.
Đối tác cần kiểm tra tính hợp lệ của chữ ký trong IPN để đảm bảo kết quả của giao dịch. Amount và Currency trong notification phải khớp với Amount và Currency đối tác lưu trong database bên đó!
Field resultCode và message do đối tác xử lý. Tham chiếu đến result code mà MoMo trả về.
MoMo sẽ dùng những thông tin này để phản hồi lại khách hàng nếu có bất cứ lỗi nào xảy ra trong quá trình xử lý thanh toán bên nhà đối tác.
Trạng Thái Giao Dịch
Sử dụng field resultCode để xác định trạng thái của giao dịch:
resultCode = 0: giao dịch thành công.resultCode = 9000: giao dịch được cấp quyền (authorization) thành công .resultCode <> 0: giao dịch thất bại.
Tham khảo Result code để xác định chi tiết lỗi của giao dịch.
Trong một số trường hợp khi kiểm tra chéo số dư và dòng tiền, MoMo sẽ không sử dụng kết quả IPN từ đối tác để hoàn tiền giao dịch!
Instant Payment Notification
Instant Payment Notification (IPN) là thông điệp được gửi từ Nhà Cung Cấp Dịch Vụ Thanh Toán - Payment Service Provider (PSP) đến Bên Sử Dụng Dịch Vụ Thanh Toán - Payment Service Consumer (PSC). Việc này sử dụng giao thức HTTP và quy trình này là bất đồng bộ.
Tại sao sử dụng IPN
Instant Payment Notification (IPN) được sử dụng để thông báo (notify) kết quả giao dịch ngay lâp tức dến PSC:
- Thanh Toán: Web, SmartTv.
- Thanh Toán Trực Tuyến
- Thanh Toán Định Kỳ
Đối tác có thể sử dụng hệ thống của mình để xử lý thông tin nhận được từ PSP:
- Cập nhật trạng thái giao dịch (khuyên dùng)
- Cập nhật số dư tài khoản (nạo tiền), xuất sản phẩm, thông báo kết quả giao dịch đến ứng dụng di động,...
- Gửi hóa đơn điện tử
Sử dụng IPN để khắc phục trường hợp thanh toán thành công nhưng người dùng không nhận được sản phẩm.
Lý do:
- Người dùng đóng trình duyệt
- Không thể điều hướng đến trang ban đầu của đối tác: do đường truyền, hệ thông quá tải,...
Cách thực thi IPN
Đối tác cần tạo API phía backend để 'lắng nghe' kết quả từ MoMo và cung cấp URL của API đó trong field ipnUrl.
Sau khi người dùng sử dụng thanh toán trên MoMo (web hoặc app), MoMo sẽ thông báo kết quả giao dịch ngay lập tức đến URL này. API của đối tác nhận kết quả thanh toán và tiếp tực xử lý trong hệ thông bên họ.
Xây dựng API
HTTP Produces Header: Sử dụng để MoMo gửi HTTP Request Content-Type: application/json
HTTP Consumers Header: Đối tác phản hồi lại MoMo: HTTP code 204 (không cần gửi thêm nội dung)
Endpoint: URL chỉ nên bao gồm đường dẫn, tham số và không chứa ký tự đặc biệt, unicode hoặc khoảng cách.