Nhảy tới nội dung

Thanh Toán Bằng QR Cá Nhân

LUỒNG XỬ LÝ​

Sơ đồ hoạt động​

Quickpay_flow

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 notifyUrl nế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: 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 (commit hoặc rollback) phụ thuộc vào kết quả xử lý.
  • Bước 6: Server của MoMo xử lý yêu cầu confirm và trả kết quả về server POS.

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à 20s để đảm bảo nhận phản hồi từ server của MoMo.

POST /pay/pos

HTTP Request

AttributeTypeRequiredDescription
partnerCodeStringThông tin tích hợp
partnerRefIdStringMã đơn hàng của đối tác
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
hashStringRSA (jsonString, publicKey)
versionDoubleVersion, hiện tại là 2.0
payTypeIntegergiá trị 3
descriptionStringChi tiết giao dịch
extra_dataJsonJson bao gồm thông tin chi tiết nếu có. Định dạng là: {\"key\": \"value\"}
Giá trị mặc định là ""
Thông tin SKU thêm: {"sku": "sku1, sku2,..."}
Chi tiết nội dung của jsonString​
AttributeTypeRequiredDescription
partnerCodeStringMã đối tác
partnerRefIdStringMã đơn hàng của đối tác](/docs/payment/onboarding/integration-process#mã-đơn-hàng-của-đối-tác)
amountLongSố tiền cần thanh toán
paymentCodeStringPayment code được tạo từ app MoMo mà được scanned bởi thu ngân
storeIdStringMã cửa hàng (nên truyền tham số để chi tiết hơn nếu được tạo từ của hàng)
storeNameStringTên cửa hàng

paymentCode bao gồm 18-20 ký tự (bắt đầu với MM trong trường hợp có 20 ký tự) và hết hạn sau 1 phút kể từ lúc tạo.

Ví dụ của jsonString

{
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "amount": 30000,
  "paymentCode": "MM627755248085056826",
  "storeId": "001",
  "storeName": "Partner store 01"
}

Dữ liệu hash được mã hóa bởi thuật toán RSA

VwnYQbw5eg2XGVO6uGgyOETG9dBQXjdOw8OyBptZ5zvsUTPiNxMc4hi1sd7TTRkifG0kaOJVgplrLlyogFxcegyZzQ7LtjDr/4FtN8MfFKWozhxSWW2JYQyJ/klegGVpOTSkXkfUoueGdTSI2IJFS1pe5rxkmBdMWRilbyfOqbTdrWt50gjY2mQbhke7+9puGLgg8mh+NfYCbEZtHDKyDODA0MVNMNh3ATd31KwfNLm0zx6QQ6KXBq5M04cpTA6rIZ9uz3fxEwTvPycuxJtLvtFDpLapNAmUwqA2Rej3mTgOTN1+Jq9isqEueA0Ix3ip++d8GbJXJYkvYfr0XgT3zA==

Mẫu Request

{
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "description": "Payment by MoMo POS",
  "hash": "VwnYQbw5eg2XGVO6uGgyOETG9dBQXjdOw8OyBptZ5zvsUTPiNxMc4hi1sd7TTRkifG0kaOJVgplrLlyogFxcegyZzQ7LtjDr/4FtN8MfFKWozhxSWW2JYQyJ/klegGVpOTSkXkfUoueGdTSI2IJFS1pe5rxkmBdMWRilbyfOqbTdrWt50gjY2mQbhke7+9puGLgg8mh+NfYCbEZtHDKyDODA0MVNMNh3ATd31KwfNLm0zx6QQ6KXBq5M04cpTA6rIZ9uz3fxEwTvPycuxJtLvtFDpLapNAmUwqA2Rej3mTgOTN1+Jq9isqEueA0Ix3ip++d8GbJXJYkvYfr0XgT3zA==",
  "version": 2,
  "payType": 3
}

HTTP Response

AttributeTypeDescription
statusIntegerTrạng thái giao dịch
messageJsonJson bao gồm nội dung chi tiết
message.descriptionStringMô tả chi tiết
message.transidLongMã giao dịch của MoMo
message.amountLongSố tiền cần thanh toán
message.phoneNumberStringSố điện thoaị khách hàng dùng để đăng ký MoMo (ẩn 3 số)
message.walletIdStringID của ví MoMo

Mẫu Response

{
  "status": 0,
  "message": {
    "transid": 43121679,
    "description": "Thành công",
    "amount": 30000,
    "phoneNumber": "0963***714",
    "walletId": "3406ABB1FF64F676F54A397B6B5F31E7FDA9533B"
  }
}

Gửi IPN​

Sau khi cấp quyền thành công, server của MoMo sẽ tạo dữ liệu và gọi URL được cung cấp bởi đối tác (notifyURL) để thông báo việc trạng thái của hóa đơn thanh toán với nội dung được mô tả như sau.

Cấu hình notifyUrl: https://business.momo.vn/merchant/integrate/generalInfo

Notify URL Example

https://www.partner.com/confirm

HTTP Request​

  • Method: POST
  • Content-type: application/json
AttributeTypeDescription
partnerCodeStringMã đối tác
accessKeyStringAccess Key information
amountLongPaid amount
partnerRefIdStringTransaction ID của đối tác
partnerTransIdStringThông tin đơn hàng
transTypeStringGiá trị luôn là momo_wallet
momoTransIdStringMã giao dịch của MoMo
statusIntegerTrạng thái giao dịch
messageStringMô tả trạng thái giao dịch
responseTimeLongThời gian gọi notifyUrl (theo millisecond)
Time zone: GMT +7
storeIdStringMã cửa hàng
signatureStringChữ ký để kiểm tra thông tin. Sử dụng thuật toán Hmac_SHA256 với dữ liệu theo đinh dạng sau:
accessKey=$accessKey&amount=$amount&message=$message&momoTransId=$momoTransId
&partnerCode=$partnerCode&partnerRefId=$partnerRefId&partnerTransId=$partnerTransId
&responseTime=$responseTime&status=$status&storeId=$storeId&transType=momo_wallet

Json body Example

{
  "partnerCode": "MOMOIQA420180417",
  "accessKey": "TNWFx9JWayevKPiB8LyTgODiCSrjstXN",
  "amount": 10000,
  "partnerRefId": "B001221",
  "partnerTransId": "",
  "transType": "momo_wallet",
  "momoTransId": "43121679",
  "status": 0,
  "message": "Thành Công",
  "responseTime": 1555472829549,
  "signature": "cd0d82ad983098a2fb99b8e49266ed7bd4db85ebf77d13b2db2f755ff0600fa0",
  "storeId": "store001"
}

HTTP Response​

Server đối tác cần phản hồi lại server MoMo để thông báo trạng thái của đơn hàng đã được lưu trữ, với nội dung mô tả như sau:

  • HTTP status: 200
  • Body: application/json
AttributeTypeDescription
statusIntegerTrạng thái đơn hàng
messageStringMô tả trạng thái
partnerRefIdStringTransaction ID của đối tác
momoTransIdStringMã giao dịch của MoMo
amountLongSố tiền cần thanh toán
signatureStringChữ ký để kiểm tra tính toàn vẹn của thông tin request.
Sử dụng thuật toán Hmac_SHA256 với dữ liệu theo định dạng sau:
amount=$amount&message=$message&momoTransId=$momoTransId&partnerRefId=$partnerRefId
&status=$status

Mẫu Response

{
  "status": 0,
  "message": "Thành công",
  "amount": 10000,
  "partnerRefId": "B001221",
  "momoTransId": "43121679",
  "signature": "0671f38c555629c6b05ee4043c28d9fde59443ee56bc7216b5b953cc4e8bf848"
}

Xác nhận giao dịch​

Sau khi MoMo đã treo tiền User thành công (tiền từ ví User được chuyển về ví trung gian), lúc này User sẽ nhận được thông báo thành công (tiền đã được trừ) và giao dịch tương ứng phía MoMo sẽ có trạng thái Chờ xử lý. Đối tác sẽ xử lý các nghiệp vụ nội bộ và gọi API này để hoàn tất giao dịch, gọi là API confirm, bao gồm 2 trạng thái:

  • Xác nhận (commit): Đối tác xử lý giao dịch thành công, trạng thái này sẽ chuyển tiền từ ví trung gian về ví đối tác tương ứng. Giao dịch tương ứng phía MoMo sẽ hoàn tất với trạng thái Thành công.
  • Hủy bỏ (rollback): Đối tác xử lý giao dịch thất bại, trạng thái này sẽ trả lại tiền đã giữ trước đó từ ví trung gian về ví user. Giao dịch tương ứng phía MoMo sẽ hoàn tất với trạng thái Thất bại.

Thông tin kết nối đến MoMo

POST /pay/confirm

HTTP Request

Tên fieldKiểuBắt buộcMô tả
partnerCodeStringMã đối tác
partnerRefIdStringMã giao dịch đối tác
Định dạng: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestTypeStringLoại request, có 2 giá trị:
- Xác nhận giao dịch: capture
- Hủy bỏ giao dịch: revertAuthorize
requestIdStringId của mỗi request khi gọi qua MoMo
momoTransIdStringMã giao dịch MoMo đã treo tiền
signatureStringChữ ký để kiểm tra thông tin. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng: partnerCode=$partnerCode&partnerRefId=$partnerRefId&requestType=$requestType
&requestId=$requestId&momoTransId=$momoTransId
customerNumberStringSố điện thoại khách hàng
descriptionStringMô tả lý do (sử dụng trong trường hợp rollback)

Request mẫu

{
  "partnerCode": "MOMOIQA420180417",
  "partnerRefId": "Merchant123556666",
  "requestType": "capture",
  "requestId": "1512529262248",
  "momoTransId": "12436514111",
  "signature": "bf577f678efebee61705de899984a67c4eeb3439318b5f0bd6e37263cf6e9fb3",
  "customerNumber": "0963181714"
}

HTTP Response

Tên fieldKiểuMô tả
statusIntegerKết quả của request
messageStringMô tả chi tiết
dataJsonJson chứa nội dung chi tiết (trong trường hợp thành công)
data.partnerCodeStringMã đối tác
data.partnerRefIdStringpartnerRefId đã gửi
data.momoTransIdStringMã giao dịch MoMo
data.amountLongSố tiền đã treo
signatureStringChữ ký để kiểm tra thông tin. Sử dụng thuật toán Hmac_SHA256 với data theo định dạng: amount=$amount&momoTransId=$momoTransId&partnerCode=$partnerCode&partnerRefId=$partnerRefId

Response mẫu

{
  "status": 0,
  "message": "Thành công",
  "data": {
    "partnerCode": "MOMOIQA420180417",
    "momoTransId": "12436514111",
    "amount": 30000,
    "partnerRefId": "Merchant123556666"
  },
  "signature": "ca2ab5c354ff1bf8af1dd3448a3aa5681e4f329d71082dc1a90347255656f70d"
}
ON THIS PAGE