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 ipnUrl 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: (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 (capture hoặc cancel) 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.

Cấu hình API

HTTP Information

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.

HTTP Request

POST /v2/gateway/api/pos

ParameterTypeRequiredDescription
partnerCodeStringThông tin tích hợp
subPartnerCodeStringĐị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
storeIdStringMã cửa hàng
storeNameStringTên cửa hàng
orderIdStringMã đơn hàng của đối tác
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
amountLongSố tiền cần thanh toán
Nhỏ nhất: 1.000 VND
Lớn nhất: 5.000.000 VND
Currency: VND.
requestIdString(50)Định danh duy nhất cho mỗi yêu cầu,
Đối tác sử dụng requestId cho xử lý idempotency
paymentCodeStringPayment 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
orderInfoStringThông tin hóa đơn
orderGroupIdLongđượ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.
autoCaptureBooleanNếu giá trị false, giao dịch sẽ không tự động capture. Mặc định là true
ipnUrlStringAPI 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)
extraDataStringGiá 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
itemsListDanh 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
userInfoObjectThông tin người dùng
requestTimeLongThời gian đối tác gửi yêu cầu đến MoMo. Định dạng: timestamp
Ví dụ: 1692783998394
langStringNgôn ngữ của message được trả về (vi or en)
signatureStringChữ 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
AttributeTypeRequiredDescription
idStringSKU number
nameStringTên sản phẩm
descriptionStringMiêu tả sản phẩm
categoryStringPhân loại ngành hàng của sản phẩm
imageUrlStringLink hình ảnh của sản phẩm
manufacturerStringTên nhà sản xuất
priceLongĐơn giá
currencyStringVND
quantityIntegerSố lượng của sản phẩm. Cần là một số lớn hơn 0
unitStringĐơn vị đo lường của sản phẩm này
totalPriceLongTổng giá = Đơn giá x Số lượng
taxAmountLongTổng thuế
Chi tiết nội dung của userInfo
AttributeTypeRequiredDescription
nameStringTên của người dùng
phoneNumberStringSố điện thoại của người dùng
emailStringEmail của người dùng

HTTP Response

AttributeTypeRequiredDescription
partnerCodeStringThông tin tích hợp
orderIdStringMã đơn hàng của đối tác
Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestIdStringĐịnh danh của mỗi yêu cầu
amountLongSố tiền cần thanh toán
Nhỏ nhất: 1.000 VND
Lớn nhất: 5.000.000 VND
Currency: VND.
transIdLongMã giao dịch của MoMo
responseTimeLongThời gian phản hồi kết quả giao dịch đến đối tác. Định dạng: timestamp
resultCodeIntegerTrạng thái giao dịch
messageStringMô tả kết quả giao dịch, ngôn ngữ dựa trên lang
promotionInfoListThông tin khuyến mãi
Default value is null
Details of promotionInfo
AttributeTypeRequiredDescription
amountLongSố tiền giảm giá
amountSponsorLongSố tiền giả giá merchant tham gia vào voucher/ campaign
voucherIdStringID của voucher/ campaign
voucherTypeStringPercent
voucherNameStringTên voucher/ campaign
merchantRateStringTỉ 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.

AttributeTypeRequiredDescription
partnerCodeStringThông tin tích hợp
orderIdStringMã đơn hàng của đối tác
requestIdStringPartner's requestId
amountLongSố tiền cần thanh toán
orderInfoStringThông tin hóa đơn
partnerUserIdStringĐịnh danh duy nhất của MoMo cho mỗi tài khoản ví MoMo.
orderTypeStringmomo_wallet
transIdLongMoMo's transaction ID
resultCodeIntegerTrạng thái giao dịch của hóa đơn Result Code
messageStringMô tả kết quả, ngôn ngữ dựa trên lang
payTypeStringMặc định: pos
responseTimeLongThời gian phản hồi kết quả giao dịch đến đối tác
Định dạng: timestamp
extraDataStringExtra Data. Default: ""
signatureStringChữ 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
promotionInfoListThông tin khuyến mãi
Default value is null
Details of promotionInfo
AttributeTypeRequiredDescription
amountLongSố tiền giảm giá
amountSponsorLongSố tiền giả giá merchant tham gia vào voucher/ campaign
voucherIdStringID của voucher/ campaign
voucherTypeStringPercent
voucherNameStringTên voucher/ campaign
merchantRateStringTỉ 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 codeDescriptionFinal StatusRecommended actionsType
0Thành công.Yes
44Giao dịch bị từ chối vì mã thanh toán không hợp lệ.NoMã 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
4005Giao dịch bị từ chối do mã thanh toán cá nhân đã hết hạn.YesVui lòng yêu cầu khách hàng sử dụng mã thanh toán cá nhân mới.User error

Xem thêm