Quick Pay - POS Scanner

Vouchers are supported with these payment methods:

• Quick Pay - POS Scanner
• Scan Dynamic QR Code

The instructions below show how you can process transactions with vouchers by Quick Pay - POS Scanner and how API Configurations operate.

Process Flow

API Configurations

Initiate Transaction

To have complete control of the customer experience, non-hosted payment page will be applied to allow customers enter their payment information directly on your website. In this case, when customer chooses to use this payment method, this API should be called first to initiate a transaction and retrieve the token (used for simplifying other requests following this API).

API information to retrieve token:

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

HTTP Request

POST /v2/gateway/api/tokenization/create

Attribute	Type	Required	Description
partnerCode	String		Integration information
subPartnerCode	String		Merchant ID
storeId	String		Store ID
requestId	String		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
orderId	String		OrderId of partner, unique for each request
referenceCode	String		Payment code created from MoMo app that is scanned by cashier
requestTime	Long		Time partner send request to MoMo. Format: timestamp Example: 1692783998394
lang	String		Language of returned message (vi or en)
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&orderId=$orderId&partnerCode= $partnerCode&referenceCode=referenceCode&requestId=$requestId &subPartnerCode=$subPartnerCode

Example Request

{
  "partnerCode": "MOMO",
  "subPartnerCode": "MOMO",
  "orderId": "6d0a1b10-b382-11e9-8fda-91fa25841420",
  "lang":  "vi",
  "requestTime":1692783998394,
  "requestId": "1666756278085id",
  "referenceCode" : "1023984137834985578",
  "signature": "5344e1f4244173fe0ba2b4c865881aad79b86beff8154b4f74f3b92634ffa711"
}

HTTP Response

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Same as the original request
orderId	String		OrderId of partner, unique for each request
responseTime	Long		Time to respond payment results to partner Format: timestamp
message	String		Error description, error language is based on lang
resultCode	Integer		Result Code
token	String		This is the unique transaction token. It's valid for a specific time depending on merchant's account setting
promotionInfo	List		List of promotionInfo
userInfo	Object		Info of the customer
partnerUserId	String		ID of user per merchant/partner

Details of promotionInfo 

Attribute	Type	Required	Description
id	String		Voucher code - generated by Partner
campaignId	String		Campaign id at MoMo
name	String		Name of promotion

Example promotionInfo

{
  "id" : "782354878793",
  "campaignId": "36745763473645",
  "name" : "Black Friday"
}

Details of userInfo 

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

Attribute	Type	Required	Description
name	String		Name of the customer as registered on merchant site

Example UserInfo

{
    "name": "Nguyen Van A"
}

Example Response

{
  "resultCode": 0,
  "message": "Giao dịch thành công.",
  "partnerCode": "MOMOIOLD20190129",
  "orderId": "1666756278085:0123456778",
  "requestId": "1666756278085id",
  "responseTime": 1666756278549,
  "token": "bd9ba8e038cda3cd87887bf3e9d9e258757a0d1333cbb68babbfd0e3",
  "promotionInfo": [
    {
      "id" : "782354878793",
      "campaignId": "36745763473645",
      "name" : "Black Friday"
    }
  ],
  "userInfo": {
    "name": "*** HUY"
  },
  "partnerUserId": "834ASDF"
}

Pay using Token

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

HTTP Request

POST /v2/gateway/api/tokenization/pay

Parameter	Type	Required	Description
partnerCode	String		Integration information
subPartnerCode	String		Sub partner Id
partnerClientId	String		Identifier of user. Default value is empty ""
storeId	String		Store ID
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
originalAmount	Long		The amount before discount.
amount	Long		Payment amountMin: 1.000 VND Payment amountMax: 30.000.000 VND Currency: VND.
requestId	String(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
tokenType	String		oneTime
token	String		Encrypt a object json by RSA using public Key RSA Encryption
orderInfo	String		Short 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.
autoCapture	Boolean		If set to false, the payment will not be automatically captured.
items	List		List of Item
promotionList	List		List of promotionList
feeList	List		List of fee info
requestTime	Long		Time partner send request to MoMo. Format: timestamp Example: 1692783998394
extraData	String		Default value is empty "" Encode base64 follow Jsonformat: {"key": "value"} Example with data: {"username": "momo"}=> data of extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0=
lang	String		Language of returned message (vi or en)
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 &orderId=$orderId&orderInfo=$orderInfo&partnerClientId= $partnerClientId&partnerCode=$partnerCode&requestId= $requestId&token=$token

Details of an items

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: VND
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 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 fee info 

Attribute	Type	Required	Description
amount	Long		Amount be charge by fee
type	String		Type of fee

Example fee info

{
  "amount" : 1000,
  "type" : "tax"
}

Details of promotionList 

Attribute	Type	Required	Description
id	String		Voucher code - generated by Partner
campaignId	String		Campaign id at MoMo
amount	Long		The discount amount of voucher

Example promotionList

{
  "id" : "782354878793",
  "campaignId": "36745763473645",
  "amount" : 10000
}

Data of token before encrypted

Attribute	Type	Required	Description
value	String		Token Value

Example request

{
  "token": "sa5s4a54s5a4s5a4s5",
  "partnerCode": "MOMO_ATM_DEV",
  "subPartnerCode": "MOMO_ATM_DEV",
  "storeId": "MoMo test store",
  "partnerClientId": "",
  "orderId": "12545465654656",
  "originalAmount": "20000",
  "amount": "20000",
  "lang": "vi",
  "autoCapture": true,
  "orderInfo": "Thanh toan MoMo",
  "requestId": "365656d56sd",
  "tokenType": "oneTime",
  "items": [
    {
      "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"
    }
  ],
  "promotionList": [
    {
      "id" : "782354878793",
      "name" : "Black Friday",
      "amount" : 1000000,
      "type" : "voucher"
    },
    {
      "id" : "782354878793",
      "name" : "Black Friday",
      "amount" : 1000000,
      "type" : "membership",
      "rate" : "0.5"
    }
  ],
  "feeList" : [
    {
      "amount" : 1000,
      "type" : "fee"
    },
    {
      "amount" : 1123,
      "type" : "tax"
    }
  ],
  "requestTime":1692783998394,
  "extraData": "",
  "signature": "2512s1d2s1ds21d2s1d1ce5d1a251#@"
}

HTTP Response

Attribute	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
requestId	String		Each Request’s Identification
amount	Long		Amount to pay
transId	Long		MoMo's transaction ID
responseTime	Long		Time to respond payment results to partner Format: timestamp
partnerClientId	String		Vendor’s unique identifier for each user (e.g.: user ID or email). This ID will be linked with end-user’s MoMo account.
resultCode	Integer		Order status
message	String		Result description, language is based on lang
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		ID of the voucher/ campaign
voucherType	String		Percent
voucherName	String		Name of the voucher/ campaign
merchantRate	String		Merchant rate of the voucher/ campaign

Example response

{
  "partnerCode": "MOMORSDU20220527",
  "orderId": "235_1713267813811",
  "requestId": "1713267813811",
  "amount": 20000,
  "responseTime": 1713267823260,
  "message": "Thành công.",
  "resultCode": 0,
  "transId": 3212233480,
  "partnerClientId": "",
  "promotionInfo": [
    {
      "amount": 10000,
      "amountSponsor": 6000,
      "voucherId": "uat_100424_athena_circlek_mr60_10k",
      "voucherType": "percent",
      "voucherName": "CircleK - Giảm 10K cho đơn từ 0đ (100056,302383) MR60",
      "merchantRate": "60"
    }
  ]
}

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 of a 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

These result codes and messages are exclusively assigned for the Payments onetime-token. Additionally, kindly locate other result codes and messages in the comprehensive list of result codes provided here.

See also

• Check Transaction Status
• Reverse & Refund
• Confirm Payment