Thanh Toán Trên Thiết Bị All-In-One
Thanh toán trên thiết bị All-in-one là giải pháp tích hợp toàn diện, cho phép khách hàng linh hoạt lựa chọn giữa việc sử dụng thẻ vật lý (chạm, cắm hoặc quẹt) và quét mã QR đa năng (AIO QR) qua ứng dụng MoMo hoặc Ngân hàng để hoàn thành giao dịch chỉ trong tích tắc.
Luồng Xử Lý
Sơ đồ hoạt động
Diễn giải sơ đồ
- Bước 1: Xác nhận thanh toán: Khách hàng chọn sản phẩm và chọn phương thức thanh toán là thẻ (vật lý/NFC) hoặc QR đa năng.
- Bước 2: Khởi tạo yêu cầu: Hệ thống bán hàng của Đối tác tạo yêu cầu thanh toán (kèm số tiền và ID máy EDC) rồi gửi qua hệ thống MoMo.
- Bước 3: Xác thực và Kích hoạt: Cổng thanh toán MoMo xác thực yêu cầu, trả trạng thái "Chờ thanh toán" về máy POS của đối tác và đồng thời kích hoạt máy EDC.
- Bước 4.1 & 4.2: Kích hoạt thiết bị: Thiết bị MoMo AIO nhận lệnh khởi tạo để chuẩn bị chờ thanh toán, trong khi cổng MoMo trả kết quả trạng thái về cho hệ thống bán hàng.
- Phân luồng hiển thị trên EDC: 4.1.1 (Nếu là QR đa năng): Máy EDC hiển thị mã QR đa năng trên màn hình. 4.1.2 (Nếu là thanh toán thẻ): Máy EDC hiển thị màn hình chờ đọc thẻ (Chèn/Quẹt/Chạm).
- Bước 5: Khách hàng thanh toán: Khách hàng thực hiện thao tác tương ứng với phương thức đã chọn: 5.1: Dùng App Ngân hàng hoặc Ví điện tử quét mã QR. 5.2: Dùng thẻ vật lý hoặc ví NFC trên điện thoại để chạm/chèn vào máy EDC.
- Bước 6: Tiếp nhận và xử lý thông tin: 6.1: Hệ thống tiếp nhận kết quả từ các ứng dụng thanh toán QR. 6.2: Thiết bị AIO xử lý thông tin thẻ, xác thực và báo kết quả về MoMo.
- Bước 7: Xử lý kết quả cuối: MoMo xử lý tín hiệu từ thiết bị và cập nhật dữ liệu thanh toán cuối cùng cho đối tác.
- Bước 8: Hiển thị kết quả: Hệ thống của đối tác nhận thông báo thành công, in biên lai (nếu có) và hoàn tất giao dịch với khách hàng.
Cấu Hình API
Phương thức thiết lập thanh toán
- Hệ thống bán hàng của Đối tác tạo yêu cầu thanh toán theo hình thức thanh toán tương ứng rồi gửi qua hệ thống MoMo.
Thông tin API để đẩy lệnh thanh toán xuống thiết bị AIl-in-one HTTP Request
POST /v2/gateway/api/create
| Parameter | Type | Required | Description |
|---|---|---|---|
| userInfo | Object | Thông tin của khách hàng. | |
| subPartnerCode | String(50) | Mã định danh đối tác phụ. Chỉ áp dụng cho Đối tác chính (Master Merchant) hoặc các nhóm nhà cung cấp dịch vụ bên thứ ba (3PSP). | |
| storeName | String | Tên cửa hàng của đối tác. | |
| storeId | String(50) |  | Mã định danh cửa hàng. Đây là trường bắt buộc. MoMo sẽ kiểm tra xem storeId có được liên kết với thiết bị EDC hay không. Nếu MoMo nhận thấy mã này chưa được liên kết với bất kỳ thiết bị nào, MoMo sẽ từ chối yêu cầu này. |
| signature | String | | Chữ ký để xác nhận thông tin. Giao dịch được bảo mật bằng thuật toán Hmac_SHA256, với định dạng: Một chuỗi (String) sắp xếp tất cả các tên trường (key name) của dữ liệu theo thứ tự từ a-z: accessKey=$accessKey&amount=$amount&extraData=$extraData &ipnUrl=$ipnUrl&orderId=$orderId&orderInfo=$orderInfo &partnerCode=$partnerCode&redirectUrl=$redirectUrl &requestId=$requestId&requestType=$requestType |
| serialNumber | String | TSố này sẽ do MoMo cung cấp và được in trên thiết bị. Số này sẽ được liên kết với từng cửa hàng. - Nếu đối tác yêu cầu thanh toán kèm theo cả storeId và serialNumber, MoMo sẽ xác thực xem storeId có khớp chính xác với serialNumber hay không. - Nếu đối tác yêu cầu thanh toán chỉ với storeId mà không có serialNumber, MoMo sẽ tự tìm số seri mới nhất được liên kết với storeId đó. | |
| requestType | String | | payWithEdc (Phương thức thanh toán qua thiết bị EDC). |
| requestId | String(50) | | Mã định danh yêu cầu, là duy nhất cho mỗi yêu cầu. Đối tác của MoMo sử dụng trường này để kiểm soát tính lặp lại (idempotency). |
| referenceId | String(200) | Mã tham chiếu phụ của đối tác. Ví dụ: dùng trong các trường hợp như mã khách hàng, mã hộ gia đình, mã hóa đơn, mã thuê bao, v.v. | |
| redirectUrl | String | | Giá trị mặc định là chuỗi rỗng "". URL của đối tác, dùng để chuyển hướng người dùng từ trang MoMo quay lại trang của đối tác sau khi khách hàng thanh toán xong. Hỗ trợ: AppLink và WebLink. |
| partnerCode | String(50) | | Thông tin tích hợp |
| orderInfo | String(255) | | Thông tin của đơn hàng |
| orderId | String(200) | | Mã định danh giao dịch của đối tác Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$ |
| orderGroupId | Long | orderGroupId sẽ do MoMo cung cấp để phân loại các nhóm đơn hàng cho các hoạt động vận hành tiếp theo. Vui lòng liên hệ MoMo để sử dụng trường này. | |
| lang | String | | Ngôn ngữ của thông báo trả về (vi: tiếng Việt hoặc en: tiếng Anh). |
| items | List | Danh sách các sản phẩm hiển thị trên trang thanh toán. Tối đa: 50 sản phẩm. | |
| ipnUrl | String | | API của đối tác. Được MoMo sử dụng để gửi kết quả thanh toán qua phương thức IPN (server-to-server). |
| instrumentType | String | Các giá trị có thể có: QR: Khi người bán (merchant) cần tạo mã QR trên thiết bị EDC. Mặc định là AIO QR. CARD: Khi người bán cần kích hoạt thanh toán bằng thẻ trên thiết bị EDC. - Nếu để trống "", mặc định sẽ là CARD. | |
| extraData | String(1000) | | Giá trị mặc định là chuỗi rỗng "". Dữ liệu được mã hóa Base64 theo định dạng JSON: {"key":"value"} Ví dụ với dữ liệu: {"username":"momo","skus":"value1,value2"} => chuỗi Base64 tương ứng là eyJ1c2VybmFtZSI6Im1vbW8iLCJza3VzIjoidmFsdWUxLHZhbHVlMiJ9. |
| deliveryInfo | Object | Thông tin giao hàng của đơn hàng này. | |
| autoCapture | Boolean | Nếu đặt là false, khoản thanh toán sẽ không được hệ thống tự động ghi nhận (capture) ngay lập tức. | |
| amount | Long | | Số tiền cần thanh toán. Tối thiểu: 1,000 VND Tối đa: 50,000,000 VND Đơn vị: VND Kiểu dữ liệu: Long |
Example request
{
"partnerCode": "MOMOHIUI20181015",
"partnerName": "Test",
"storeId": "kozen029",
"subPartnerCode": "MOMOLFZB20230228",
"storeName": "Nước rửa tay",
"requestType": "payWithEdc",
"ipnUrl": "https://sangle.free.beeceptor.com",
"redirectUrl": "https://sangle.free.beeceptor.com",
"orderId": "OD1773203367580",
"amount": "1000",
"lang": "vi",
"autoCapture": true,
"subscriptionInfo": null,
"deliveryInfo": {
"deliveryAddress": "Ho Chi Minh",
"inStorePickup": false
},
"orderInfo": "Thanh toán cho đơn hàng",
"requestId": "1773203367580id",
"extraData": "ew0KImVtYWlsIjogImh1b25neGRAZ21haWwuY29tIg0KfQ==",
"signature": "20c959b2d00884c3f67ead4fd7bb97a9a48cc3de07434f6a0fca164b7aff84ed",
"instrumentType": "CARD"
}
HTTP Response
| 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 |
| responseTime | Long | | Thời gian trả kết quả thanh toán về đối tác. Format: timestamp |
| resultCode | Integer | | Mã lỗi |
| message | String | | Mô tả lỗi, ngôn ngữ dựa trên lang |
| orderId | Object | | Mã đơn hàng của đối tác Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$ |
| amount | String | | Giống với yêu cầu ban đầu |
Example response
{
"partnerCode": "MOMOHIUI20181015",
"orderId": "OD1773203367580",
"requestId": "1773203367580id",
"amount": 1000,
"responseTime": 1773203367760,
"message": "Thành công.",
"resultCode": 0
}
Thanh toán
Khách hàng có thể dùng thẻ vật lý, phi vật lý để thanh toán hoặc dùng ứng dụng MoMo, Ngân Hàng để quét QR thanh toán.
Xử lý kết quả thanh toán
Tìm hiểu thêm về Payment Notification. Payment Notification.
Thông tin 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ã định danh giao dịch của đối tác. |
| requestId | String | | Mã định danh yêu cầu của đối tác. |
| amount | Long | | Số tiền thanh toán. |
| partnerUserId | String | Mã định danh duy nhất của MoMo cho mỗi tài khoản ví điện tử MoMo. | |
| storeId | String | Mã định danh cửa hàng (Store ID). | |
| orderInfo | String | | Thông tin của đơn hàng. |
| orderType | String | | momo_wallet(loại đơn hàng qua ví MoMo). |
| transId | Long | | Mã định danh giao dịch của hệ thống MoMo. |
| resultCode | Integer | | Mã kết quả trả về, đại diện cho trạng thái giao dịch của đơn hàng. Result Code |
| message | String | | Mô tả lỗi hoặc thông báo, ngôn ngữ được hiển thị dựa trên tham số lang đã gửi |
| payType | String | | Payment type: edcDevice(thiết bị EDC), aio_qr(mã QR đa năng),banktransfer_qr(chuyển khoản ngân hàng qua QR). |
| responseTime | Long | | Thời điểm phản hồi kết quả thanh toán cho đối tác. Định dạng: timestamp |
| extraData | String | | Dữ liệu bổ sung. Mặc định là chuỗi rỗng "". |
| signature | String | | Chữ ký để xác nhận thông tin. Giao dịch được bảo mật bằng thuật toán Hmac_SHA256 với định dạng: Một chuỗi (String) sắp xếp tất cả các tên trường dữ liệu theo thứ tự 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 |
| cardPaymentInfo | Object | | Thông tin thẻ sử dụng thanh toán dùng cho đối soát. |
| paymentOption | String | Tài khoản/thẻ trong MoMo sử dụng để thanh toán cho giao dịch | |
| userFee | Long | Phí người dùng. | |
| promotionInfo | List | | Dữ liệu để xác định chương trình khuyến mãi mà (các) mã giảm giá (voucher) đã được áp dụng trong giao dịch thanh toán, với các mã (key) cố định cho từng voucher. Giá trị mặc định là null. |
Details of CardPaymentInfo
|
| Attribute | Type | Required | Description |
|---------------|---------|---------------------|------------------------------------------------------------------------------------------------------------------------------|
| cardType | String | | Loại thẻ:
Ví dụ: Visa, Mastercard, JCB, Amex. Thông tin này đến từ lệnh thanh toán thành công từ thiết bị. |
| cardNumber | String | | Thông tin thẻ thanh toán.
Ví dụ: Số thẻ 454078**3062. Thông tin này đến từ lệnh thanh toán thành công từ thiết bị. |
IPN Sample Request
{
"partnerCode": "MOMOHIUI20181015",
"orderId": "17501345596640123456778",
"requestId": "1750134559664",
"amount": 100000,
"orderInfo": "Thanh toán qua ví MoMo ne hihi",
"orderType": "momo_wallet",
"transId": 4401354269,
"resultCode": 0,
"message": "Thành công.",
"payType": "edcDevice",
"responseTime": 1750134605770,
"extraData": "eyJza3VzIjoiODkzNDgwNDAyNTc4MCw5ODkyODQ1MDAwMjMzLDg5MzQ4MDQwMjM2NDksODkzNDgwNDAyNTQ2OSxORVNUTEVNTTQ2LE5FU1RMRU1NMSw4OTM0ODA0MDIwNDAyLE5FU1RMRU1NNzUsOTg5Mjg0NTAwMDIzMiIsInVzZXJuYW1lIjoibW9tbyJ9",
"signature": "da66a9008cc774d2ea45fe3175c1197a77bf6e18ceb14c74df454191372b27cd",
"cardPaymentInfo": {
"cardType": "NAPAS",
"cardNumber": "970418******9550"
}
}
Quyết toán giao dịch
- Hệ thống bán hàng của Đối tác tạo yêu cầu quyết toán đối với các giao dịch thanh toán thẻ. Đối tác có thể thực hiện quyết toán giao dịch trên thiết bị All-in-one hoặc tạo yêu cầu quyết toán thông qua API. Thông tin API để đẩy lệnh quyết toán xuống thiết bị AIl-in-one
HTTP Request
POST /v2/gateway/card/settle
| Attribute | Type | Required | Description |
|---|---|---|---|
| partnerCode | String | | Thông tin tích hợp |
| storeId | String | | Mã định danh cửa hàng. |
| serialNumber | String | | Mã thiết bị sẽ được cung cấp bởi MoMo và in trên thiết bị. Mã thiết bị này sẽ được liên kết với từng cửa hàng. |
| partnerCode | String | | Mã định danh yêu cầu của đối tác. |
| signature | String | | Signature: accessKey=$accessKey&partnerCode=$partnerCode&requestId=$requestId&serialNumber=$serialNumber&storeId=$storeId |
Example request
{
"partnerCode": "MOMOD0MX20250828",
"storeId": "Triq3pJjqg5F2afm",
"serialNumber": "1495221012",
"requestId": "1759202655463id",
"signature": "1ac4edd31ab3ffe426711e8daa541d2f47252b4943b95c72922eb27b03bf9897"
}
HTTP Response
| Attribute | Type | Required | Description |
|---|---|---|---|
| responseTime | Long | | Thời điểm phản hồi kết quả thanh toán cho đối tác. Định dạng: timestamp (dấu thời gian). |
| resultCode | Integer | | Mã kết quả trả về, đại diện cho trạng thái giao dịch của yêu cầu. |
| message | String | | Mô tả lỗi hoặc thông báo, ngôn ngữ được hiển thị dựa trên tham số lang đã gửi. |
Example response
{
"resultCode": 0,
"message": "Successful.",
"responseTime": 1759202657279
}