Thanh Toán MOD
Luồng Xử Lý
Lựa chọn 1: QR Code dán trên bưu kiện
Trước khi vận chuyển
- Bước 1: Khách hàng (người dùng) xác nhận đơn hàng và chọn thanh toán khi nhận hàng.
- Bước 2: Hệ thống đối tác khởi tạo đơn hàng với thông tin đơn hàng cùng với mã đơn hàng (orderID) duy nhất, sau đó gửi đến MoMo để yêu cầu tạo QR Code bao gồm thông tin đơn hàng và số tiền.
- Bước 3: MoMo tạo QR Code, sau đó trả về cho đối tác.
- Bước 4: Hệ thống đối tác nhận QR Code, gửi thông tin đến người gửi hàng. Người gửi hàng in QR Code và dán lên bưu kiện.
Thanh toán bằng phương thức MOD khi nhận hàng
- Bước 5: Khi bưu kiện đến được tay khách hàng, tiến hành quét QR Code được dán trên bưu kiện bằng MoMo app hoặc ứng dụng quét QR Code khác trên thiết bị di động.
- Bước 6: Khách hàng xác nhận thanh toán qua 'màn hình thanh toán an toàn' trên ứng dụng MoMo.
- Bước 7: Momo xử lý giao dịch, sau đó trả kết quả giao dịch cho đối tác, đồng thời hiển thị kết quả cho khách hàng trên MoMo app.
Đối với lựa chọn này, shipper cần phải kiểm tra kỹ kết quả thanh toán trên ứng dụng MoMo của người dùng để đảm bảo rằng giao dịch đã được thực hiện thành công.
Lựa chọn 2: QR Code hiển thị trên ứng dụng của nhân viên giao hàng
Trước khi vận chuyển
- Bước 1: Khách hàng (người dùng) xác nhận đơn hàng và chọn thanh toán khi nhận hàng.
- Bước 2: Đối tác xác nhận đơn hàng, sau đó gửi thông tin đơn hàng đến Shipper app.
Thanh toán bằng phương thức MOD khi nhận hàng
- Bước 3: Shipper gặp khách hàng và gửi yêu cầu QR Code bằng cách chọn phương thức thanh toán MOD.
- Bước 4: Hệ thống đối tác khởi tạo đơn hàng với thông tin đơn hàng cùng với mã đơn hàng (orderID) duy nhất, sau đó gửi đến MoMo để yêu cầu tạo QR Code bao gồm thông tin đơn hàng và số tiền.
- Bước 5: Sau khi xác thực thông tin đối tác, MoMo trả về QR Code.
- Bước 6: Hệ thống đối tác nhận QR Code và xử lý, sau đó trả về cho shipper app.
- Bước 7: QR Code được hiển thị trên shipper app. Shipper đưa QR Code cho khách hàng để quét.
- Bước 8: Khách hàng tiến hành quét QR Code bằng MoMo app hoặc ứng dụng quét QR Code khác trên thiết bị di động.
- Bước 9: Khách hàng xác nhận thanh toán qua 'màn hình thanh toán an toàn' trên ứng dụng MoMo.
- Bước 10: Momo xử lý giao dịch, sau đó trả kết quả giao dịch cho đối tác, đồng thời hiển thị kết quả cho khách hàng trên MoMo app.
- Bước 11: Đối tác nhận kết quả giao dịch và xử lý trả về cho shipper app.
- Bước 12: Hiển thị kết quả giao dịch trên shipper app. Đơn hàng được hoàn tất.
Cấu hình API
Thiết lập phương thức thanh toán
Trên trang thanh toán của đối tác, sau khi người dùng chọn thanh toán với ví điện tử MoMo, hệ thống đối tác gọi API onDelivery để lấy phương thức thanh toán và sử dụng phương thức phù hợp với nền tảng của họ.
requestType: Định danh loại request
POST /v2/gateway/api/create
| Attribute | Type | Required | Description |
|---|---|---|---|
| partnerCode | String |  | Thông tin tích hợp |
| partnerName | String | Tên đối tác | |
| storeId | String | Mã cửa hàng | |
| requestId | String(50) | | Định danh duy nhất cho mỗi yêu cầu, Đối tác sử dụng requestId cho xử lý idempotency control |
| amount | Long | | Số tiền cần thanh toán Nhỏ Nhất: 1.000 VND Tối đa: 20.000.000 VND Tiền tệ: VND Kiểu dữ liệu: Long |
| orderId | String | | Mã đơn hàng của đối tác |
| orderInfo | String | | Thông tin đơn hàng |
| redirectUrl | String | | Một URL của đối tác. URL này được sử dụng để chuyển trang (redirect) từ MoMo về trang mua hàng của đối tác sau khi khách hàng thanh toán. Support: AppLink and WebLink |
| ipnUrl | String | | API của đối tác. Được MoMo sử dụng để gửi kết quả thanh toán theo phương thức IPN |
| requestType | String | | onDelivery |
| extraData | String | | Giá trị mặc định là rỗng"" Encode base64 theo định dạng Json: {"key": "value"} Ví dụ với dữ liệu: {"username": "momo"}thì data extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0= |
| autoCapture | Boolean | Nếu giá trị là false, đối tác cần gọi API confirm để thực hiện capture cho việc thanh toán | |
| lang | String | | Ngôn ngữ của message (vi or en) |
| signature | String | | Chữ ký dùng để đảm bảo độ tin cậy của thông tin giao dịch. Là 1 chuỗi được mã hóa bằng thuật toán Hmac_SHA256 theo format: một chuỗi gồm key name và giá trị của các field sắp xếp theo thứ tự của key name từ a-z: accessKey=$accessKey&amount=$amount&extraData=$extraData&ipnUrl=$ipnUrl&orderId=$orderId&orderInfo=$orderInfo&partnerCode=$partnerCode&redirectUrl=$redirectUrl&requestId=$requestId&requestType=$requestType |
Thông tin điều hướng (redirectUrl)
WebLink: Đường dẫn liên kết để mở website.
AppLink: Đường dẫn liên kết để mở mobile application.
Xem thêm về AppLink
Android: https://developer.android.com/training/app-links
IOS: https://developer.apple.com/documentation/uikit/core_app/..
Mẫu Request
{
"partnerCode": "MOMO",
"partnerName" : "Test",
"storeId" : "MoMoTestStore",
"requestType": "onDelivery",
"ipnUrl": "https://momo.vn",
"redirectUrl": "https://momo.vn",
"orderId": "MM1540456472575",
"amount": 150000,
"lang": "vi",
"orderInfo": "SDK team.",
"requestId": "MM1540456472575",
"extraData": "eyJ1c2VybmFtZSI6ICJtb21vIn0=",
"signature": "fd37abbee777e13eaa0d0690d184e4d7e2fb43977281ab0e20701721f07a0e07"
}
Danh sách những phương thức thanh toán mà MoMo cung cấp
| Attribute | Type | Required | Description |
|---|---|---|---|
| partnerCode | String | | Thông tin tích hợp |
| requestId | String | | Giống với yêu cầu ban đầu |
| orderId | String | | Mã đơn hàng của đối tác |
| amount | Long | | giống với số tiền thanh toán ban đầu |
| responseTime | Long | | Thời gian trả kết quả thanh toán về đối tác Định dạng: timestamp |
| message | String | | Mô tả lỗi, ngôn ngữ dựa trên lang |
| resultCode | int | | Result Code |
| payUrl | String | | URL để chuyển từ trang mua hàng của đối tác sang trang thanh toán của MoMo |
| deeplink | String | URL để mở ứng dụng trực tiếp MoMo (Khách hàng phải cài đặt ứng dụng MoMo trước) và trang xác nhận thanh toán. | |
| qrCodeUrl | String | Dữ liệu để tạo mã QR nếu bạn muốn khách hàng quét mã QR trực tiếp trên trang mua hàng hoặc in mã lên hoá đơn. Note: Đây không phải URL chứa hình ảnh của mã QR, bạn cần sử dụng thư viện ngoài để tạo mã QR. | |
| deeplinkMiniApp | String | URL mở màn hình xác nhận thanh toán của ứng dụng MoMo. Áp dụng khi đối tác sử dụng mini app nhúng vào trong ứng dụng MoMo. |
Trên môi trường production: Bạn cần phải yêu cầu cho phép sử dụng những trường qrCodeUrl, deeplink,deeplinkMiniApp.
Mẫu Response
{
"partnerCode": "MOMO",
"requestId": "MM1540456472575",
"orderId": "MM1540456472575",
"amount": 150000,
"responseTime": 145256987,
"message": "Thành công",
"resultCode": 0,
"payUrl": "https://test-payment.momo.vn/v2/gateway/pay?t=TU9NT1NKSTEyMDE5MDgyM3wxNjEzNTMyMDk3OTIyOjAxMjM0NTY3Nzg=",
"deeplink": "momo://?action=payWithAppToken&amount=150000&fee=0&requestType=payment&orderLabel=M%C3%A3+%C4%91%C6%A1n+h%C3%A0ng&orderId=MM1540456472575&requestId=MM1540456472575&merchantnamelabel=Nh%C3%A0+cung+c%E1%BA%A5p&description=SDK+team.&partnerCode=MOMO&merchantcode=MOMO&language=vi&merchantname=MoMo+Payment&packageId=&extras=&extraData=email=abc@gmail.com&deeplinkCallback=https%3A%2F%2Ftest-payment.momo.vn%2Fgw_payment%2Fm2%3Fid%3DM7EWVy&callbackUrl=https%3A%2F%2Ftest-payment.momo.vn%2Fgw_payment%2Fm2%3Fid%3DM7EWVy&urlSubmitToken=https%3A%2F%2Ftest-payment.momo.vn%2Fgw_payment%2Fpayment_with_app%3FpartnerCode%3DMOMO%26accessKey%3DF8BBA842ECF85%26requestId%3DMM1540456472575%26orderId%3DMM1540456472575%26orderInfo%3DSDK%2Bteam.%26amount%3D150000%26signature%3Ddf2a347519abb91e9c1bd1bee80e675f4108cb6dbcac531979e805857293d486%26requestType%3DcaptureWallet%26payType%3Dapp-in-app&appScheme=",
"qrCodeUrl": "https://test-payment.momo.vn/gw_payment/s/zoVKZd"
}
Thanh toán
Bạn cần cài đặt ứng dụng MoMo Test và sử dụng Tài khoản MoMo TEST để thực hiện giao dịch.
Hướng dẫn thanh toán: Đăng nhập > Màn hình Home > Quét mã QR.
Xử lý kết quả thanh toán
Xem thêm tại Payment Notification.
Khi giao dịch thành công, trang thanh toán của MoMo được điều hướng về trang của đối tác dựa trên field redirectUrl mà đối tác thêm vào ở lệnh onDelivery, và đính kèm thêm 1 số tham số vào URL theo định dạng sau. Lưu ý điều hướng này xảy ra trong app của Nhân viên giao hàng.
Mô tả tham số
Mô tả các tham số được dùng bởi MoMo trong URL redirectUrl và nội dung của body ipnUrl.
| Attribute | Type | Required | Description |
|---|---|---|---|
| partnerCode | String | | Thông tin tích hợp |
| orderId | String | | Mã đơn hàng của đối tác |
| requestId | String | | Partner's requestId |
| amount | Long | | Số tiền cần thanh toán |
| partnerUserId | String | Định danh duy nhất của MoMo cho mỗi tài khoản ví MoMo. | |
| orderInfo | String | | Thông tin đơn hàng |
| orderType | String | | momo_wallet |
| transId | Long | | Mã giao dịch của MoMo |
| resultCode | Integer | | Trạng thái giao dịch của đơn hàng Mã Kết Quả |
| message | String | | Mô tả lỗi ngôn ngữ dựa trên lang |
| payType | String | | Hình thức thanh toán: web hoặc qr |
| responseTime | Long | | Thời gian trả kết quả thanh toán về đối tác Định dạng: timestamp |
| extraData | String | | Thông tin thêm. Mặc định: "" |
| signature | String | | Chữ ký để xác nhận giao dịch. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng được sort từ a-z : accessKey=$accessKey&amount=$amount&extraData=$extraData&message=$message&orderId=$orderId&orderInfo=$orderInfo&orderType=$orderType&partnerCode=$partnerCode&payType=$payType&requestId=$requestId&responseTime=$responseTime&resultCode=$resultCode&transId=$transId |