Scan Dynamic QR Code

Vouchers are supported with these payment methods:

• Quick Pay - POS Scanner
• Scanning Dynamic QR Code

The instructions below show how you can process transactions with vouchers when user scan your Dynamic QR Code and how API Configurations operate. With this payment method, you should provide MoMo an API to validate voucher before user make a transaction.

Process Flow

API Configurations

Initiate payment method

On the Merchant's POS, after customers choose to pay with MoMo e-wallet, POS server needs to call MoMo's API captureWallet to get payment methods and then apply suitable ones to their platforms.

requestType: Identify the type of the request

Minimum timeout when call this API must be 30s to ensure receive response from MoMo.

HTTP Request

POST /v2/gateway/api/create

Attribute	Type	Required	Description
partnerCode	String		Integration information
subPartnerCode	String		Sub partner Id
storeId	String		Store ID
requestId	String(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
amount	Long		Amount needs to be paid Min: 1.000 VND Max: 50.000.000 VND Currency: VND Data type: Long
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
orderInfo	String		Order's information
orderGroupId	Long		The orderGroupId will be provided by MoMo to classify groups of orders for further operational activities. Please contact MoMo to use this field.
redirectUrl	String		A partner's URL. This URL is used to redirect from MoMo page to partner's page after customer's payment. Support: AppLink and WebLink
ipnUrl	String		Partner API. Used by MoMo to submit payment results by IPN method (server-to-server) method
requestType	String		captureWallet
extraData	String		Default value is empty "" Encode base64 follow Jsonformat: {"key": "value"} Example with data: {"username": "momo"}=> data of extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0=
items	List		List of products displayed on the payment page. Maximum: 50 items
deliveryInfo	Object		Delivery info of this order
userInfo	Object		Info of the customer
autoCapture	Boolean		If set to false, the payment will not be automatically captured.
lang	String		Language of returned message (vi or en)
signature	String		Signature to confirm information. Secure transaction in Hmac_SHA256 with format: a String sort all key name of data field from a-z: accessKey=$accessKey&amount=$amount&extraData=$extraData &ipnUrl=$ipnUrl&orderId=$orderId&orderInfo=$orderInfo &partnerCode=$partnerCode&redirectUrl=$redirectUrl &requestId=$requestId&requestType=$requestType

Details of an item

It is not required to add items. Howvever, each item added must have these fixed keys:

Attribute	Type	Required	Description
id	String		SKU number
name	String		Name of the product
description	String		Description of the product
category	String		Product classification/Product category
imageUrl	String		Link image of product
manufacturer	String		Name of manufacturer
price	Long		Unit price
currency	String		VND
quantity	Integer		Quantity number of the product. It must be greater than 0
unit	String		The units of measurement used for products
totalPrice	Long		Total price = price x quantity
taxAmount	Long		Total amount of tax

Example of Item

{
  "id": "204727",  
  "name": "YOMOST Bac Ha&Viet Quat 170ml",  
  "description": "YOMOST Sua Chua Uong Bac Ha&Viet Quat 170ml/1 Hop",
  "category": "beverage",
  "imageUrl":"https://momo.vn/uploads/product1.jpg",
  "manufacturer":"Vinamilk",
  "price": 11000,               
  "quantity": 5,
  "unit":"hộp",
  "totalPrice": 55000,
  "taxAmount":"200"
}

Details of deliveryInfo

Attribute	Type	Required	Description
deliveryAddress	String		Delivery address
deliveryFee	String		Delivery fee
quantity	String		Quantity of product

Example of deliveryInfo

{
    "deliveryAddress": "Phu My Hung Tower",
    "deliveryFee": "30000",
    "quantity": "2"
}

Details of userInfo content

If this is provided, customer as MoMo user will be receive a notification or email (by choices).

Attribute	Type	Required	Description
name	String		Name of the customer as registered on merchant site
phoneNumber	String		Phone number of the customer as registered on merchant site
email	String		Email address of the customer as registered on merchant site

Example of userInfo

{
    "name": "Nguyen Van A",
    "phoneNumber": "0999888999",
    "email": "email_add@domain.com"
}

Example Request

{
  "partnerCode": "MOMO",
  "partnerName" : "Test",
  "storeId" : "MoMoTestStore",
  "requestType": "captureWallet",
  "ipnUrl": "https://momo.vn",
  "redirectUrl": "https://momo.vn",
  "orderId": "MM1540456472575",
  "amount": 150000,
  "lang":  "vi",
  "orderInfo": "SDK team.",
  "requestId": "MM1540456472575",
  "extraData": "eyJ1c2VybmFtZSI6ICJtb21vIn0=",
  "signature": "fd37abbee777e13eaa0d0690d184e4d7e2fb43977281ab0e20701721f07a0e07"
}

Try yourself

HTTP Response

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Same as the original request
orderId	String		Partner Transaction ID
amount	Long		Same as the original payment amount
responseTime	Long		Time to respond payment results to partner Format: timestamp
message	String		Error description, error language is based on lang
resultCode	int		Result Code
payUrl	String		URL for switching from the partner's page to the MoMo payment page
deeplink	String		URL to open MoMo application directly (Customers must install MoMo app first) and payment confirmation screen. If you have problem opening deeplink in android 11, please see the tutorial
qrCodeUrl	String		Data to generate QR code if you want customers to scan the QR code directly on your purchase page or to print it on the invoice. Note: This URL is NOT containing the image of the QR code, you need to use an external library to generate the QR code.
deeplinkMiniApp	String		URL to open the MoMo app's payment confirmation screen. Apply when partner's website is embedded into MoMo app.
signature	String		Signature to confirm information. Secure transaction in Hmac_SHA256 with format: accessKey=$accessKey&amount=$amount&message=$message&orderId=$orderId &partnerCode=$partnerCode&payUrl=&payUrl&requestId= $requestId&responseTime=$responseTime&resultCode=$resultCode

On the production environment: You need to request permission to use qrCodeUrl, deeplink,deeplinkMiniApp fields.

Example of a 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"
}

Validate voucher

Merchants can be categorized into two groups:

• Merchants that have VAT included in item prices. Voucher is applied after VAT.
• Merchants that have VAT not included in item prices. Voucher is applied before VAT. In addition to VAT, some restaurants have service fee, shipping fee, etc. which are added to the bill after the voucher discount. In Voucher Distribution, Partner will take charge of Validating voucher conditions and Calculating voucher discount based on your own specialties. The voucher discount calculation method is different between two groups. The solution in this document can cover for both groups of Merchants. HTTP Request

GET <your endpoint>

Property	Type	Description
partnerCode	string	ID of Merchant on MoMo
campaignId	string	ID of the promotion campaign on MoMo
saleTranId	string	The order number orderId that MoMo received from Partner on create payment.
voucherCode	string	Voucher code - generated by Partner

Authorization Type Use one of the following Auth Type:

• Basic Auth
• API Key
• Bearer Token Token expireTime = 604800000 ms And when MoMo requests a new token, the previously valid token will not expire immediately.

Example request param

<your endpoint>?partnerCode={partnerCode}&campaignId={campaignId}&saleTranId={saleTransId}&voucherCode={voucherCode}

HTTP Response

HTTP Status Code: 200

Property	Type	Required	Description
isValid	Boolean		To specify whether the voucher is applicable for this order
usedBillAmount	Integer		Total bill amount that initiated the transaction
originalBillAmount	Integer		The bill amount before VAT and other restaurant fees, which is used to deduct the voucher. Only required when VAT is not included in item prices. In other cases, default value is null.
usedDiscountAmount	Integer		The discount amount of voucher. In case the bill is not eligible to apply voucher, response usedDiscountAmount = 0.
partnerVatAndFeeAmount	Integer		Total amount of VAT and other restaurant fees at Partner. Only required when VAT is not included in item prices. In other cases, default value is null. Currency: VND For example: VAT: 10.000 VND Service fee: 25.000 VND Shipping fee: 15.000 VND partnerVatAndFeeAmount: 50.000 VND
finalBillAmount	Integer		Total bill amount after discount that needs to be paid.
message	String		Error message when applying the voucher
errorCode	Integer		Error code, as described below

Example of a Voucher applied successfully - case VAT is included in item prices

{
 "isValid": true,
 "usedBillAmount": 110000,
 "usedDiscountAmount": 40000,
 "finalBillAmount": 70000,
 "message": "Success.",
 "errorCode": 0
}

Example of a Voucher applied successfully - case VAT is not included in item prices

{
 "isValid": true,
 "usedBillAmount": 110000,
 "originalBillAmount": 100000,
 "usedDiscountAmount": 40000,
 "partnerVatAndFeeAmount": 6000,
 "finalBillAmount": 66000,
 "message": "Success.",
 "errorCode": 0
}

Example of a Voucher applied failed

{
 "isValid": false,
 "usedBillAmount": 10000,
 "usedDiscountAmount": 0,
 "finalBillAmount": 10000,
 "message": "Đã áp dụng chương trình giảm giá khác, không thể áp dụng thẻ quà.",
 "errorCode": -1111124
}

Error Codes and Messages of API validate voucher

Error Codes	Description	Type	Error Message for users
0	Success.
-2	Request timeout.	System error	Đã xảy ra lỗi trong quá trình xử lý. Quý khách vui lòng thử lại.
-25	Unknown error	System error	Đã có lỗi trong quá trình xử lý. Chúng tôi ghi nhận và sẽ khắc phục sớm.
-501	The voucher is already expired.	User error	Thẻ quà tặng đã hết hạn vào lúc ${endAt}. Vui lòng kiểm tra thông tin thẻ quà.
-502	The voucher is already used.	User error	Thẻ quà tặng đã được sử dụng.
-504	The bill amount is not sufficient enough to apply voucher.	User error	Thẻ quà chỉ áp dụng cho giá trị thanh toán từ ${minBillValue} trở lên.
-508	Request has more than 1 voucher.	System error	Bạn không thể sử dụng nhiều thẻ quà trong cùng một thời điểm.
-509	The voucher has not started to be used.	User error	Thẻ quà chưa đến thời gian áp dụng. Vui lòng kiểm tra thông tin thẻ quà.
-100008	The voucher is not applicable to the selected store.	User error	Thẻ quà không áp dụng cho cửa hàng đã chọn. Kiểm tra thông tin thẻ quà.
-100012	The voucher has an configuration error.	System error	Thẻ quà bị lỗi cấu hình. Vui lòng liên hệ CSKH để được hỗ trợ!
-100014	No suitable vouchers for the transaction.	System error	Rất tiếc, chưa có thẻ quà nào phù hợp cho giao dịch của bạn!
-1111111	The voucher can not be applied due to a technical error.	System error	Thẻ quà chưa thể áp dụng do lỗi kĩ thuật. Quý khách vui lòng thử lại.
-1111118	The voucher is locked on Partner's system.	System error	Thẻ quà hiện đang tạm khoá.
-1111119	Exceed the limit of voucher redemption per user.	User error	Thẻ quà chỉ áp dụng 1 lần đối với mỗi người dùng.
-1111120	Exceed the total limit of voucher redemption.	User error	Rất tiếc! Số lượt sử dụng thẻ quà đã hết.
-1111121	The voucher is inapplicable to this channel.	User error	Thẻ quà không áp dụng trên kênh này. Vui lòng kiểm tra thông tin thẻ quà.
-1111124	Another voucher is being applied on Partner's system, user can not apply the selected voucher.	User error	Đã áp dụng chương trình giảm giá khác, không thể áp dụng thẻ quà.
-1111125	Invalid transaction data.	User error	Không tìm thấy thông tin hóa đơn. Quý khách vui lòng thử lại.
-100015	Default error code	System error	Giao dịch chưa thỏa điều kiện thẻ quà. Kiểm tra thông tin thẻ quà.

Payment

You need to install MoMo Test app and use MoMo TEST Account to process payment.

Payment guideline: Login > Home screen > Scan QR.

Processing payment result

For more information, see Payment Notification.

Parameter description

Description for parameters which are used by MoMo in the URL redirectUrl and the body content of ipnUrl.

Attribute	Type	Required	Description
partnerCode	String		Integration Information
orderId	String		Partner Transaction ID
requestId	String		Partner's requestId
amount	Long		Payment amount
partnerUserId	String		MoMo's unique identifier for each MoMo eWallet account.
orderInfo	String		Order's information
orderType	String		momo_wallet
transId	Long		MoMo's transaction ID
resultCode	Integer		Transaction status of the order Result Code
message	String		Error description, languague is based on lang
payType	String		Payment type: webApp, app,qror miniapp
responseTime	Long		Time to respond payment results to partner Format: timestamp
extraData	String		Extra Data. Default: ""
signature	String		Signature to confirm information. Secure transaction in Hmac_SHA256  algorithm with format: a String sort all key name of data field from 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
promotionInfo	List		The data to identify the promotion campaign in which the voucher(s) was applied in the payment transaction, with fixed keys for each voucher Default value is null

Details of promotionInfo

Attribute	Type	Required	Description
amount	Long		Discount amount of payment
amountSponsor	Long		Discount amount sponsor of merchant
voucherId	String		Voucher code - generated by Partner hoặc ID of the voucher/ campaign (voucher MoMo)
voucherType	String		voucher_partner hoặc Percent (voucher MoMo)
voucherName	String		Name of the voucher/ campaign
merchantRate	String		Merchant rate of the voucher/ campaign

Example IPN

{
  "orderType": "momo_wallet",
  "amount": 111000,
  "partnerCode": "MOMOHIUI20181015",
  "orderId": "VEQQL9KN2IW5XMUC3FYI",
  "extraData": "eyJtY19uYW1lIjoiaVBPUyBNQlMgeCBNb01vIFBsYXRpbnVtIiwic2t1cyI6IkFWMDAxLEFWMDAyIiwiZGV2aWNlX2lkIjoiTUdRVkVRUUw5S04yIiwib3JpZ2luX3RyYW5faWQiOiJNR1FWRVFRTDlLTjJJVzVYTVVDM0ZZSSIsInBvc19pZCI6MTE2NjcsInBvc19wYXJlbnQiOiJCUkFORC1PTVk3IiwibWNfaWQiOiIxMTY2NyIsIm9yZGVyX2lkIjoiTUdRVkVRUUw5S04ySVc1WE1VQzNGWUkiLCJwYXltZW50X21ldGhvZCI6Ik1PTU9RUjQifQ==",
  "signature": "e1b7aff328e97d3ad36cc49d1dc3b55771610fc917ede8a85e2111c863106e7a",
  "transId": 4028289695,
  "responseTime": 1713860057901,
  "resultCode": 0,
  "promotionInfo": [
    {
      "amount": 16650,
      "voucherId": "64MW64FI",
      "voucherType": "voucher_ipos",
      "voucherName": "Laville - Giảm 15% tối đa 20K cho đơn từ 100K"
    },
    {
      "amount": 10000,
      "amountSponsor": 6000,
      "voucherId": "uat_100424_athena_circlek_mr60_10k",
      "voucherType": "percent",
      "voucherName": "Giảm 10K Cho đơn từ 0đ",
      "merchantRate": "60"
    }
  ],
  "message": "Thành công.",
  "payType": "qr",
  "requestId": "1713859677588MGQVEQQL9KN2IW5XMUC3FYI",
  "orderInfo": "VEQQL9KN2IW5XMUC3FYI",
  "partnerUserId": "MT6ZiJDTnuWojnCfQAedcNaCxLPVPGk1s7g"
}

Notify the status of voucher redemption

Partner makes a request to this API to notify MoMo about the status of voucher redemption.

HTTP Request

POST /v1/merchants/{partnerId}/campaigns/{momoCampaignId}/vouchers/redeem-status

Variable	Type	Description
partnerId	String	ID of Merchant on MoMo
momoCampaignId	String	ID of the promotion campaign on MoMo

Parameter description

Property	Type	Required	Description
voucherCode	String		Voucher code - generated by Partner
userPhoneNumber	String		User's phone number who redeemed voucher Default value is empty ""
momoTransactionId	String		MoMo's Transaction ID
partnerTransactionId	String		Your Transaction ID/ orderId
redeemStatus	Enum		Voucher redemption result: - SUCCESS - FAIL
saleInfo	Object		Detail of order that applied voucher

Details of saleInfo

Property	Type	Required	Description
posId	String		Your POS identity
posName	String		Your POS name
tranDate	Long		Transaction date
originalAmount	Double		The bill amount before discount
serviceCharge	Double		Service charge percent, value mus be less than or equal to 1, default 0.
serviceChargeAmount	Double		Service charge amount
shipFeeAmount	Double		Shipping fee
vatAmount	Double		VAT fee amount
billAmount	Double		Total order amount. billAmount = originalAmount + serviceChargeAmount + shipFeeAmount + vatAmount
discountAmount	Double		Voucher discount amount
totalAmount	Double		Total amount user must pay (after applying voucher). totalAmount = billAmount - discountAmount
paymentMethod	String		Payment method of order: - MOMOSCANNER: Quick Pay - POS Scanner - MOMOQR: User scan dynamic QR code - CASH - CREDIT_CARD - VIETQR

HTTP Response

Property	Type	Description
status	string	See convention for common status code
message	string	The description of the above status code
formErrors	object	Described below. This property is set on status = FAIL and http status code is 400

Example request

{
  "voucherCode": "E61HE61J",
  "userPhoneNumber": "0915013325",
  "momoTransactionId": "48479590245",
  "partnerTransactionId": "KBJ6G2N4J1R2ENY7IVG7BOT0",
  "redeemStatus": "SUCCESS",
  "saleInfo": {
    "posId": "17130",
    "posName": "iPOS.vn - Văn Phòng",
    "tranId": "KBJ6G2N4J1R2ENY7IVG7BOT0",
    "tranDate": 1702961170,
    "originalAmount": 123000,
    "serviceCharge": 0.08,
    "serviceChargeAmount": 9840,
    "shipFeeAmount": 3000,
    "vatAmount": 5000,
    "billAmount": 140840,
    "discountAmount": 20000,
    "totalAmount": 103000,
    "paymentMethod": "MOMOQR"
  }
}

Result Codes & Messages of API payment

Kindly locate result codes and messages of One-time Payments AIO in the comprehensive list of result codes provided here.

See also

• Check Transaction Status
• Reverse & Refund
• Confirm Payment