Quick Pay - POS Scanner

Process Flow

Flow diagram

Explanation

• Step 1: User logs in MoMo app, selects MÃ THANH TOÁN (Payment Code) to create a payment code (paymentCode).
• Step 2: Cashier scans Bar code (or QR code) on the user’s screen to get paymentCode, and the information will be sent to partner’s POS server.
• Step 3: POS Server packs and sends received transaction information to MoMo’s server for authorization.
• Step 4: MoMo’s Server processes the request and returns the authorization result to POS server. If failed (cannot make authorization), transaction ends here. If succeed, MoMo’s server will call notifyUrl if have config (API provided by partner in MoMo’s format, view detail to notify order payment status.
• Step 5: POS Server receives result returned from MoMo’s Server, processes and send corresponding request to MoMo’s server to confirm the transaction (commit or rollback) depending on the result of the processing.
• Step 6: MoMo’s Server processes the confirm request and returns result to POS server.

Payment Processing

Describe data the POS server sends through the MoMo server to authorization.

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

POST /pay/pos

HTTP Request

Attribute	Type	Required	Description
partnerCode	String		Integration information
partnerRefId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
hash	String		RSA (jsonString, publicKey)
version	Double		Version, currently is 2.0
payType	Integer		Value is3
description	String		Transaction description
extra_data	Json		Json contain detail information if available. Format is: {\"key\": \"value\"} Default value is "" Additional information SKU: {"sku": "sku1, sku2,..."}

Details of jsonString content

Attribute	Type	Required	Description
partnerCode	String		Partner Code
partnerRefId	String		Partner Transaction ID
amount	Long		Payment amount
paymentCode	String		Payment code created from MoMo app that is scanned by cashier
storeId	String		Store ID (should transmit to be more detailed, if there is a store)
storeName	String		Store name

paymentCode consists of 18-20 characters (starting with MM in case of 20 characters) and has expiration time of 1 minute since created.

jsonString Example

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

Data hash encrypted by RSA

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

Example request Example

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

HTTP Response

Attribute	Type	Description
status	Integer	Transaction status
message	Json	Json containing detail contents
message.description	String	Detailed description
message.transid	Long	MoMo's transaction ID
message.amount	Long	Payment amount
message.phoneNumber	String	MoMo's customer phone number (hidden 3 digits)
message.walletId	String	MoMo Wallet ID

Response Example

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

Processing payment result

After making authorization successfully, MoMo’s server will create data and call URL provided by partner (notifyUrl) to notify order payment status with content as described below.

Configure notifyUrl: https://business.momo.vn/merchant/integrate/generalInfo

Notify URL Example

https://www.partner.com/confirm

HTTP Request

• Method: POST
• Content-type: application/json

Attribute	Type	Description
partnerCode	String
accessKey	String	Integration information
amount	Long	Paid amount
partnerRefId	String	Partner's transaction ID
partnerTransId	String	Order Information
transType	String	Value always as momo_wallet
momoTransId	String	MoMo's transaction ID
status	Integer	Transaction status
message	String	Status description
responseTime	Long	Time calling notifyUrl (in millisecond) Time zone: GMT +7
storeId	String	Store ID
signature	String	Signature to check information. Use Hmac_SHA256 algorithm with data in format: accessKey=$accessKey&amount=$amount&message=$message&momoTransId= $momoTransId&partnerCode=$partnerCode&partnerRefId=$partnerRefI d&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

Partner’s Server needs to respond back to MoMo’s server informing that the order status has been recorded, with content description as below.

• HTTP status: 200
• Body: application/json

Attribute	Type	Description
status	Integer	Transaction status. 0 if successful
message	String	Status description
partnerRefId	String	Partner's transaction ID
momoTransId	String	MoMo's transaction ID
amount	Long	Payment amount
signature	String	Signature to check information. Use Hmac_SHA256 algorithm with data in format: amount=$amount&message=$message&momoTransId=$momoTransId &partnerRefId=$partnerRefId&status=$status

Response Example

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

Payment Confirmation

After MoMo has put user’s money on hold successfully (money from User’s e-wallet transferred to the middle e-wallet), User will receive success notification (money has been deducted) and the respective transaction from MoMo’s side will have the status of Waiting to be processed. Partner will process internal operations and call this API to complete the transaction, called confirm API, including 2 statuses:

• Confirm (commit): Partner processes the transaction successfully, and this status will transfer the money from the middle wallet to respective partner’s wallet. Respective transaction from MoMo’s side will complete with Successful status.
• Cancel (rollback): Partner fails to process the transaction, and this status will return the money on hold from the middle wallet to the user’s wallet. The respective transaction from MoMo’s side will complete with Failed status.

POST /pay/confirm

HTTP Request

Attribute	Type	Required	Description
partnerCode	String		Integration information
partnerRefId	String		Partner's transaction ID Format: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
requestType	String		Request type, with 2 values: - Confirm transaction: capture - Cancel transaction: revertAuthorize
requestId	String		ID of each request when calling MoMo
momoTransId	String		MoMo's transaction ID authorized
signature	String		Signature to check information. Use Hmac_SHA256 algorithm with data in format: partnerCode=$partnerCode&partnerRefId=$partnerRefId &requestType=$requestType&requestId=$requestId &momoTransId=$momoTransId
customerNumber	String		Customer's phone number
description	String		Reason description (used in the case of rollback)

Request Example

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

HTTP Response

Attribute	Type	Description
status	Integer	Request result
message	String	Status description
data	Json	Json containing detail contents (in successful cases)
data.partnerCode	String	Partner Code
data.partnerRefId	String	partnerRefId of request
data.momoTransId	String	MoMo's transaction ID
data.amount	Long	Amount on hold
signature	String	Signature to check information. Use Hmac_SHA256 algorithm with data in format: amount=$amount&momoTransId=$momoTransId&partnerCode=$partnerCode &partnerRefId=$partnerRefId

Response Example

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