Promotion Info

One-Time Payments

API Configuration

HTTP Information

Initiate payment method

On the merchant's payment page, after customers choose to pay with MoMo e-wallet, merchant 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

HTTP Request

POST /v2/gateway/api/create

Attribute	Type	Required	Description
partnerCode	String		Integration information
subPartnerCode	String		Sub partner Id
storeName	String		Store name
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		Default value is empty "" 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","skus":"value1,value2"} => data of extraData: eyJ1c2VybmFtZSI6Im1vbW8iLCJza3VzIjoidmFsdWUxLHZhbHVlMiJ9
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

Details of deliveryInfo

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

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

Redirecting information (redirectUrl)

WebLink: Links to open website.

AppLink: Link to open mobile application.

Learn more about AppLink

• Android: https://developer.android.com/training/app-links
• IOS: https://developer.apple.com/documentation/uikit/core_app/..

Example Request

{
  "partnerCode": "MOMOSJNT20200819",
  "storeName": "MoMo 8 Hoàng Văn Thái",
  "storeId": "12345",
  "requestType": "captureWallet",
  "ipnUrl": "https://momo.vn/",
  "redirectUrl": "https://momo.vn/",
  "orderId": "OD1684902769001",
  "amount": "120000",
  "orderInfo": "MoMo_test",
  "requestId": "RQ1684902769001",
  "extraData": "eyJ1c2VybmFtZSI6Im1vbW8iLCJza3VzIjoidmFsdWUxLHZhbHVlMiJ9",
  "signature": "9ec3b6afdb6101cf707982d765705a379be7230a460a9e7fac49df8e4b065441",
  "lang": "vi",
  "autoCapture": "true",
  "orderGroupId": "",
  "deliveryInfo": {
    "deliveryAddress": "8 Hoàng Văn Thái, Tân Phú, Quận 7",
    "deliveryFee": "20000",
    "quantity": "5"
  },
  "userInfo": {
    "name": "MoMo",
    "phoneNumber": "0987123456",
    "email": "email@gmail.com"
  },
  "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": 20000,
      "currency": "VND",
      "quantity": 2,
      "unit": "hộp",
      "totalPrice": 40000,
      "taxAmount": "200"
    },
    {
      "id": "204782",
      "name": "YOMOST Dau Tay 170ml",
      "description": "YOMOST Sua Chua Uong Dau Tay 170ml/1 Hop",
      "category": "beverage",
      "imageUrl": "https://momo.vn/uploads/product2.jpg",
      "manufacturer": "Vinamilk",
      "price": 20000,
      "quantity": 3,
      "unit": "hộp",
      "totalPrice": 60000,
      "taxAmount": "200"
    }
  ]
}

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 response

{
    "partnerCode": "MOMOSJNT20200819",
    "orderId": "OD1684902769001",
    "requestId": "RQ1684902769001",
    "amount": 120000,
    "responseTime": 1684902770151,
    "message": "Thành công.",
    "resultCode": 0,
    "payUrl": "https://test-payment.momo.vn/v2/gateway/pay?t=TU9NT1NKTlQyMDIwMDgxOXxPRDE2ODQ5MDI3NjkwMDE",
    "deeplink": "momo://app?action=payWithApp&isScanQR=false&serviceType=app&sid=TU9NT1NKTlQyMDIwMDgxOXxPRDE2ODQ5MDI3NjkwMDE&v=3.0",
    "qrCodeUrl": "momo://app?action=payWithApp&isScanQR=true&serviceType=qr&sid=TU9NT1NKTlQyMDIwMDgxOXxPRDE2ODQ5MDI3NjkwMDE&v=3.0",
    "deeplinkMiniApp": "momo://app?action=payWithApp&isScanQR=false&serviceType=miniapp&sid=TU9NT1NKTlQyMDIwMDgxOXxPRDE2ODQ5MDI3NjkwMDE&v=3.0"
}

Quick Pay - POS Scanner

API Configuration

HTTP Information

Payment Processing

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

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

HTTP Request

POST /v2/gateway/api/pos

Parameter	Type	Required	Description
partnerCode	String		Integration information
storeId	String		Store ID
storeName	String		Store name
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
amount	Long		Payment amount Min: 1.000 VND Max: 5.000.000 VND Currency: VND.
requestId	String(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
paymentCode	String		Encrypt a String Payment code created from MoMo app that is scanned by cashier 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.
ipnUrl	String		Merchant’s API Endpoint. Used by MoMo to send payment results via IPN method (server-to-server)
extraData	String		Default value is empty "" Encode base64 follow Jsonformat: {"key":"value"} Example with data: {"username":"momo","skus":"value1,value2"} => data of extraData: eyJ1c2VybmFtZSI6Im1vbW8iLCJza3VzIjoidmFsdWUxLHZhbHVlMiJ9
items	List		List of products displayed on the payment page. Maximum: 50 items
userInfo	Object		Info of the customer`
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&partnerCode=$partnerCode &paymentCode=$paymentCode&requestId=$requestId

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

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

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		Payment amount Min: 1.000 VND Max: 5.000.000 VND Currency: VND.
transId	Long		MoMo's transaction ID
responseTime	Long		Time to respond payment results to partner Format: timestamp
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 empty ""

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	Long		Merchant rate of the voucher/ campaign

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	JsonArray		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 empty ""

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	Long		Merchant rate of the voucher/ campaign

Check Transaction Status

This API gets the transaction status corresponding to requested OrderId for specific merchant.

HTTP Request

POST /v2/gateway/api/query

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Unique ID of each request
orderId	String		ID of order that needs to be checked.
lang	String		Language of returned message (vi or en)
signature	String		Signature to check information. Use Hmac_SHA256 algorithm with data in format: accessKey=$accessKey&orderId=$orderId&partnerCode=$partnerCode &requestId=$requestId

Example request

{
    "partnerCode": "MOMOSJNT20200819",
    "requestId": "1684900982569",
    "orderId": "235_1684743462594",
    "lang":  "vi",
    "signature": "fe330c5bb1a05042d9633ca317166997bb48cf7e0cc1a950703f353026c0bb08"
}

Try yourself

HTTP Response

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Unique ID of each request
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
extraData	String		Extra Data. Default: value transmitted by merchant in captureWallet API
amount	Long		Payment amount
transId	Long		MoMo's transaction ID
payType	String		Payment method. web or qr. Default: "" if it is not a payment
resultCode	int		Result Code
refundTrans	List		List of refund transactions
message	String		Error description based on lang
responseTime	Long		Time to respond payment results to partner Format: timestamp
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 empty ""

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	Long		Merchant rate of the voucher/ campaign

Example response

{
    "partnerCode": "MOMOSJNT20200819",
    "orderId": "235_1684743462594",
    "requestId": "1684900982569",
    "extraData": "eyJza3VzIjoiUUFaMDAxIn0=",
    "amount": 60000,
    "transId": 3005899645,
    "payType": "pos",
    "resultCode": 0,
    "refundTrans": [],
    "message": "Thành công.",
    "responseTime": 1684900983668,
    "lastUpdated": 1684743466951,
    "promotionInfo": [
        {
            "amount": 10000,
            "amountSponsor": 5000,
            "voucherId": "kingfood_sku-be9c7aca-a623-4a53-9d5b-c017f5c0b842",
            "voucherType": "kingfood_sku",
            "voucherName": "Thẻ quà SKU Kingfoodmart -30% max 100k cho bill từ 50k",
            "merchantRate": "50"
        }
    ]
}