Thanh Toán Bằng QR Cá Nhân
LUỒNG XỬ LÝ
Sơ đồ hoạt động
Diễn giải sơ đồ
- Bước 1: Người dùng đăng nhập app MoMo, chọn MÃ THANH TOÁN (Payment Code) để tạo mã thanh toán (
paymentCode). - Bước 2: Thu ngân quét Barcode (hoặc QR code) trên màn hình của người dùng để lấy
paymentCode. Thông tin sẽ được gửi đến server POS của nhà đối tác. - Bước 3: POS Server đóng gói và gửi thông tin giao dịch đã nhận được đến server MoMo để cấp quyền.
- Bước 4: Server nhà MoMo xử lý yêu cầu và trả kết quả cấp quyền về server POS. Nếu thất bại (không thể cấp quyền), giao dịch kết thúc ở đây. Nếu thành công, Server nhà MoMo sẽ gọi
ipnUrlnếu có cấu hình (API được gọi bởi đối tác theo định dạng của MoMo, xem chi tiết để thông báo trạng thái đơn hàng của đối tác. - Bước 5: (Không xảy ra nếu
autoCapture=trueđược truyền ở bước 3) Server POS nhận kết quả trả về từ server của MoMo, xử lý và gửi yêu cầu phản hồi đến Server của MoMo để xác nhận giao dịch (capturehoặccancel) phụ thuộc vào kết quả xử lý. - Bước 6: Server của MoMo xử lý yêu cầu
confirmvà trả kết quả về server POS.
Cấu hình API
Xử lý thanh toán
Mô tả dữ liệu mà hệ thống POS gửi thông qua server MoMo để xin cấp quyền.
Thời gian timeout nhỏ nhất khi gọi API này nên là 30s để đảm bảo nhận phản hồi từ server của MoMo.
POST /v2/gateway/api/pos
| Parameter | Type | Required | Description |
|---|---|---|---|
| partnerCode | String |  | Thông tin tích hợp |
| subPartnerCode | String | Định danh duy nhất của tài khoản M4B của bạn Chỉ áp dụng cho nhóm đối tác thuộc Master Merchant, 3PSP: third party services provider | |
| storeId | String | Mã cửa hàng | |
| storeName | String | Tên cửa hàng | |
| orderId | String | | Mã đơn hàng của đối tác Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$ |
| amount | Long | | Số tiền cần thanh toán Nhỏ nhất: 1.000 VND Lớn nhất: 5.000.000 VND Currency: VND. |
| 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 |
| paymentCode | String | | Payment code được tạo từ app MoMo mà được scanned bởi thu ngân sử dụng public Key và thuật toán RSA Encryption |
| orderInfo | String | | Thông tin hóa đơn |
| orderGroupId | Long | được cung cấp bởi MoMo để sắp xếp các nhóm của các hóa đơn cho các hoạt động vận hành sau đó. Liên hệ MoMo để có thể sử dụng field này. | |
| autoCapture | Boolean | Nếu giá trị false, giao dịch sẽ không tự động capture. Mặc định là true | |
| 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 (server-to-server) | |
| 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","skus":"value1,value2"} thì data extraData: eyJ1c2VybmFtZSI6Im1vbW8iLCJza3VzIjoidmFsdWUxLHZhbHVlMiJ9 |
| items | List | Danh sách các sản phẩm hiển thị trên trang thanh toán. Tối đa: 50 loại sản phẩm | |
| userInfo | Object | Thông tin người dùng | |
| requestTime | Long | Thời gian đối tác gửi yêu cầu đến MoMo. Định dạng: timestampVí dụ: 1692783998394 | |
| lang | String | | Ngôn ngữ của message được trả về (vi or en) |
| 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: 1 chuỗi String được sort theo thứ tự alphabet: accessKey=$accessKey&amount=$amount&extraData=$extraData&orderId=$orderId&orderInfo=$orderInfo&partnerCode=$partnerCode&paymentCode=$paymentCode&requestId=$requestId |
Chi tiết nội dung của items
| Attribute | Type | Required | Description |
|---|---|---|---|
| id | String | | SKU number |
| name | String | | Tên sản phẩm |
| description | String | Miêu tả sản phẩm | |
| category | String | Phân loại ngành hàng của sản phẩm | |
| imageUrl | String | Link hình ảnh của sản phẩm | |
| manufacturer | String | Tên nhà sản xuất | |
| price | Long | | Đơn giá |
| currency | String | | VND |
| quantity | Integer | | Số lượng của sản phẩm. Cần là một số lớn hơn 0 |
| unit | String | Đơn vị đo lường của sản phẩm này | |
| totalPrice | Long | | Tổng giá = Đơn giá x Số lượng |
| taxAmount | Long | Tổng thuế |
Chi tiết nội dung của userInfo
| Attribute | Type | Required | Description |
|---|---|---|---|
| name | String | Tên của người dùng | |
| phoneNumber | String | Số điện thoại của người dùng | |
| String | Email của người dùng |
HTTP Response
| Attribute | Type | Required | Description |
|---|---|---|---|
| partnerCode | String | | Thông tin tích hợp |
| orderId | String | | Mã đơn hàng của đối tác Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$ |
| requestId | String | | Định danh của mỗi yêu cầu |
| amount | Long | | Số tiền cần thanh toán Nhỏ nhất: 1.000 VND Lớn nhất: 5.000.000 VND Currency: VND. |
| transId | Long | | Mã giao dịch của MoMo |
| responseTime | Long | | Thời gian phản hồi kết quả giao dịch đến đối tác. Định dạng: timestamp |
| resultCode | Integer | | Trạng thái giao dịch |
| message | String | | Mô tả kết quả giao dịch, ngôn ngữ dựa trên lang |
| promotionInfo | List | Thông tin khuyến mãi Default value is null |
Details of promotionInfo
| Attribute | Type | Required | Description |
|---|---|---|---|
| amount | Long | | Số tiền giảm giá |
| amountSponsor | Long | | Số tiền giả giá merchant tham gia vào voucher/ campaign |
| voucherId | String | | ID của voucher/ campaign |
| voucherType | String | | Percent |
| voucherName | String | | Tên voucher/ campaign |
| merchantRate | String | | Tỉ lệ mà merchant tham gia vào voucher/ campaign |
Xử lý kết quả thanh toán
Xem thêm thông tin tại Payment Notification.
Mô tả tham chiếu
Mô tả tham số được xử dụng trong nội dung body của 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 |
| orderInfo | String | | Thông tin hóa đơn |
| partnerUserId | String | Định danh duy nhất của MoMo cho mỗi tài khoản ví MoMo. | |
| orderType | String | | momo_wallet |
| transId | Long | | MoMo's transaction ID |
| resultCode | Integer | | Trạng thái giao dịch của hóa đơn Result Code |
| message | String | | Mô tả kết quả, ngôn ngữ dựa trên lang |
| payType | String | | Mặc định: pos |
| responseTime | Long | | Thời gian phản hồi kết quả giao dịch đến đối tác Định dạng: timestamp |
| extraData | String | | Extra Data. Default: "" |
| signature | String | | Chữ ký để xác nhận thông tin. Sử dụng thuật toán Hmac_SHA256 với định dạng: Mỗi chuỗi bao gồm các key name được sắp xếp theo thứ tự alphabet: 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 |
| promotionInfo | List | Thông tin khuyến mãi Default value is null |
Details of promotionInfo
| Attribute | Type | Required | Description |
|---|---|---|---|
| amount | Long | | Số tiền giảm giá |
| amountSponsor | Long | | Số tiền giả giá merchant tham gia vào voucher/ campaign |
| voucherId | String | | ID của voucher/ campaign |
| voucherType | String | | Percent |
| voucherName | String | | Tên voucher/ campaign |
| merchantRate | String | | Tỉ lệ mà merchant tham gia vào voucher/ campaign |
Result Codes & Messages
Các result codes và mô tả tương ứng này được chỉ định riêng cho luồng Thanh toán bằng QR Cá Nhân. Ngoài ra, vui lòng tìm kiếm những mã khác trong danh sách result codes tổng hợp ở đây.
| Result code | Description | Final Status | Recommended actions | Type |
|---|---|---|---|---|
| 0 | Thành công. | Yes | ||
| 44 | Giao dịch bị từ chối vì mã thanh toán không hợp lệ. | No | Mã thanh toán không đúng định dạng. Vui lòng kiểm tra xem khách hàng có dùng đúng MoMo QR thanh toán, hay một số ký tự lạ đã bị thêm vào trong quá trình quét mã do lỗi từ máy POS. Mã thanh toán khả dụng là mã thanh toán đúng với một trong ba định dạng sau: "MM" + "18 digit" => ví dụ: MM561918531775222861 "mm" + "18 digit" => ví dụ: mm561918531775222861 "18 digit" => ví dụ: 561918531775222861 | User error |
| 4005 | Giao dịch bị từ chối do mã thanh toán cá nhân đã hết hạn. | Yes | Vui lòng yêu cầu khách hàng sử dụng mã thanh toán cá nhân mới. | User error |