MOMO PAYMENT APIs

Version 2.1.5

Changes history
Version Date Section Name Changes
2.1.5 10.10.2018 Update error Code
2.1.5 04.08.2018 Update public key
2.1.5 12.07.2018 Update document
2.1.5 09.04.2018 Update new document
POS payment, Online all-in-
All MoMo payment
2.1.4 14.12.2017 one payment, app-to-app
methods
payment
Update refund, query Update refund, query
2.1.3 23.11.2017
status API status API

1| MoMo Payment APIs – M_Service

I. ABOUT THIS DOCUMENT
This document is the official MoMo payment APIs.
- Who can read this document such as technical engineers, BA engineers, R&D
engineers and testing engineers for the integration with MoMo payment.
- Which vendor systems can use this APIs such as any online shopping platforms,
cashier systems or POS systems and business mobile app platform that can check
out a payment.

II. PAYMENT METHODS IN THIS DOCUMENT

1) All-In-One Online Payment (M2 payment) [section 7]
- The end-user goes to a Vendor online shopping on PC web, mobile web or mobile
app and check out an order. After user checkout and choice MoMo as the
payment method, M2 payment will redirect end-user to M2 payment payUrl to
confirm a payment.
- The end-user using “QUÉT MÔ called scanner feature on MoMo app and scan the
payment QR code displayed within M2 payment payUrl when vendor shopping PC
web redirect to this.[figure 2.1]
- The end-user entering Vendor shopping mobile web or Vendor mobile app was
redirected to M2 payment payUrl. M2 payment will open MoMo app that the
end-user can confirm payment and return result to vendor.[figure 3.1]

Optional:

o QR code URL will return to vendor using this to generate QR code outside MoMo
page, you can place this QR code on Smart TV, tablet, print to bill for user scan
this QR code.
o Deeplink URL can be returned, vendor can handle open MoMo app, with callback
send to MoMo by returnURL

2) POS Payment [section 6]

The end-user show their “MÃ THANH TOÁN” called QR Code or barcode in MoMo
app and display for the Vendor cashier to scan in order to pay.
3) App-to-app Online Payment [section 8]
App-to-app payment know as Mobile App-in-app payment which mobile vendor app
call to open MoMo app via MoMo open SDK and confirm pay a transaction.

2| MoMo Payment APIs – M_Service

III. MOMO BUSINESS ACCOUNT
The MoMo Business Platform serves as the functional hub for vendor features
related to MoMo payment, including parameter settings, payment data query and
statistics, online refunds, and other features.

URL: [Link]

IV. DEFINATIONS
Vendor shopping
Any online shopping platforms, cashier systems or POS systems and business
mobile app platform.
Partner Code
Unique identify for each Vendor. Can find in MoMo Business Platform
URL: [Link]
Access key
Unique identify for each Vendor. Can find in MoMo Business Platform
Signature
The Vendor’s backend and the MoMo payment system create the same
signature based on the same secret key and algorithm and use it to verify each
other's identity. The signature algorithm is created and provided by MoMo.
Commonly used signature modes are MD5, SHA1, SHA256, and HMAC.
RSA encryption
RSA Encryption is one of the first public-key cryptosystems and is widely used
for secure data transmission. In such a cryptosystem, the encryption key is
public and it is different from the decryption key which is kept secret (private).
Vendor using public key that MoMo provided to encrypt for secure data
transfer.
Hash
Body data Vendor system using RSA encrypt data.
Example:
Before hash:
{
"partnerCode": " MOMOIQA420180417",
"partnerRefId": "Merchant123556666",
"requestId": "8374736463"
}
After using RSA encrypt this data:
jClksw/4LI+lMdBHpfX++fYDKpUg4a8W/heOY3PQbxI7NJI3GFlRQGsi70CSTZuW0KKgBXSuvpIF
d5zpzzxOi7MJg4qqNWRIEn2/PAiHjB2J6R4w+wdnz9yIAGkN8E9P4l4VAKFfR01quOWjIczjFxT7
V8ibOa92dYWtAEtms86Z7QYu4ZIw8m8b1IBgeifxm9T8k5Np3cati0QLUCEFkW+oKEWeV3f3EGpx
c7qFed4kPvxZAcBUzzQZHWUBxUVcH7d3tw7n6eGLI6lk+KvFjQRIMr94wvaPpVFXF049wexoUgPr
i8hUYJyPhEcchZDmeNJUZTWrB/1O1sJLKbSJgQ==

3| MoMo Payment APIs – M_Service

MoMo Business testing account

Username: mm_bu_test
Password: MOMO2018
Login: [Link]

4| MoMo Payment APIs – M_Service

V. INTEGRATION SPECIFICATIONS

Sandbox: [Link]
Production: [Link]

1) POS payment:
Partner code : MOMOIQA420180417
Public key :
Java key format:
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkpa+qMXS6O11x7jBGo9W3yxeHEsAdyDE
40UoXhoQf9K6attSIclTZMEGfq6gmJm2BogVJtPkjvri5/j9mBntA8qKMzzanSQaBEbr8FyByHnf226dsL
t1RbJSMLjCd3UC1n0Yq8KKvfHhvmvVbGcWfpgfo7iQTVmL0r1eQxzgnSq31EL1yYNMuaZjpHmQuT2
4Hmxl9W9enRtJyVTUhwKhtjOSOsR03sMnsckpFT9pn1/V9BE2Kf3rFGqc6JukXkqK6ZW9mtmGLSq3
K+JRRq2w8PVmcbcvTr/adW4EL2yc1qk9Ec4HtiDhtSYd6/ov8xLVkKAQjLVt7Ex3/agRPfPrNwIDAQAB
C# key format:
<RSAKeyValue><Modulus>kpa+qMXS6O11x7jBGo9W3yxeHEsAdyDE40UoXhoQf9K6attSIclTZMEGf
q6gmJm2BogVJtPkjvri5/j9mBntA8qKMzzanSQaBEbr8FyByHnf226dsLt1RbJSMLjCd3UC1n0Yq8KKvf
HhvmvVbGcWfpgfo7iQTVmL0r1eQxzgnSq31EL1yYNMuaZjpHmQuT24Hmxl9W9enRtJyVTUhwKhtj
OSOsR03sMnsckpFT9pn1/V9BE2Kf3rFGqc6JukXkqK6ZW9mtmGLSq3K+JRRq2w8PVmcbcvTr/adW4
EL2yc1qk9Ec4HtiDhtSYd6/ov8xLVkKAQjLVt7Ex3/agRPfPrNw==</Modulus><Exponent>AQAB</Exp
onent></RSAKeyValue>
Endpoint: [Link]
Security method: SSL/TLS encryption protocols and RSA encrypt body data
with public key

2) All-in-one Online payment:

Partner code: MOMOIQA420180417
Access key: SvDmj2cOTYZmQQ3H
Secret key: PPuDXq1KowPT1ftR8DvlQTHhC03aul17
Endpoint: [Link]
Security method: SSL/TLS encryption protocols and SHA256 signature verify.

3) App-to-app payment:
Partner code : MOMOIQA420180417
Public key :
Java key format:
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkpa+qMXS6O11x7jBGo9W3yxeHEsAdyDE
40UoXhoQf9K6attSIclTZMEGfq6gmJm2BogVJtPkjvri5/j9mBntA8qKMzzanSQaBEbr8FyByHnf226dsL
t1RbJSMLjCd3UC1n0Yq8KKvfHhvmvVbGcWfpgfo7iQTVmL0r1eQxzgnSq31EL1yYNMuaZjpHmQuT2
4Hmxl9W9enRtJyVTUhwKhtjOSOsR03sMnsckpFT9pn1/V9BE2Kf3rFGqc6JukXkqK6ZW9mtmGLSq3
K+JRRq2w8PVmcbcvTr/adW4EL2yc1qk9Ec4HtiDhtSYd6/ov8xLVkKAQjLVt7Ex3/agRPfPrNwIDAQAB
C# key format:

5| MoMo Payment APIs – M_Service

 <RSAKeyValue><Modulus>kpa+qMXS6O11x7jBGo9W3yxeHEsAdyDE40UoXhoQf9K6attSIclTZMEGf
q6gmJm2BogVJtPkjvri5/j9mBntA8qKMzzanSQaBEbr8FyByHnf226dsLt1RbJSMLjCd3UC1n0Yq8KKvf
HhvmvVbGcWfpgfo7iQTVmL0r1eQxzgnSq31EL1yYNMuaZjpHmQuT24Hmxl9W9enRtJyVTUhwKhtj
OSOsR03sMnsckpFT9pn1/V9BE2Kf3rFGqc6JukXkqK6ZW9mtmGLSq3K+JRRq2w8PVmcbcvTr/adW4
EL2yc1qk9Ec4HtiDhtSYd6/ov8xLVkKAQjLVt7Ex3/agRPfPrNw==</Modulus><Exponent>AQAB</Exp
onent></RSAKeyValue>
Endpoint: [Link]
Security method: SSL/TLS encryption protocols and RSA encrypt body data
with public key

VI. POS PAYMENT TECHNICAL GUIDE

1) Use case
Step 1: User logging in to MoMo app, the end-user tap the “MÃ THANH TOÁN”
feature in the home screen show in Figure 1.1

Step 2: Cashier scan bar code or QR Code Figure 1.2 shown in the end-user MoMo
app that in step 1 and the transaction order is submitted to the Vendor POS
server.

Step 3: Vendor POS server send the transaction include order amount, vendor
transaction id and MoMo POS payment code to MoMo POS server. If the payment
verified successful, the end-user will see a successful message in MoMo app and
error will display when failed in Figure 1.3.

6| MoMo Payment APIs – M_Service

 Step 4: Vendor POS terminal server will receive the result from MoMo POS server
when verify completed. After received result from MoMo POS server, Vendor POS
server send result to Vendor Terminal POS.

Figure 1.1 MoMo home screen Figure 1.2 MoMo payment QR code Figure 1.3 transaction result

2) Participating Vendors
o Users can experience this method for themselves at stores and super
market accepted MoMo POS payment.
o Super market: [Link] mart, Lotte mart
o Coffee: The Coffee House, Gongcha
o Foods and beverages: Gogi, Kichi, Hoàng Yến Buffet
o Cinemas: CGV, Lotte Cinema
Note: The MoMo barcodes are constructed with 20 numbers, with the start value of MM.

7| MoMo Payment APIs – M_Service

3) Work flow

4) Exception Handling
Follow the instructions below to troubleshoot any payment exceptions:
If the Payer cannot find their order in their transaction history when they're
prompted of a payment error on MoMo, they will require the Vendor to
initiate the order again. if the order is successfully paid for, the Vendor’s
backend calls the Query Transaction Status API to query the actual payment
status again.
5) Submit MoMo POS payment server
After the Cashier scans a bar code or QR code on the MoMo app page shown by
the Payer, the payment parameters are transferred to the Vendor POS Server. The
Vendor POS server calls the Submit MoMo POS payment server to initiate a payment.

URL: [Link]
Method: HTTP POST
Request header: application/json
Response header: application/json

8| MoMo Payment APIs – M_Service

 Parameter request detail:

Parameter Data Requirement Description

type
partnerCode String √ Merchant identify code
partnerRefId String √ Transaction ID of Merchant system
description String Detail description of transaction
amount Numeric √ Payment amount
hash String √ RSA_Encrypt(
{
"partnerCode": "[partnerCode]",
"partnerRefId": "[partnerRefId]",
"amount": "[amount]",
"paymentCode": "[paymentCode]",
"storeId": "[store ID]",
"storeName": "[store Name]",
}
)
version Numeric √ Current version is 2.0 (double value)

Example:
{
"partnerCode": "MOMOIQA420180417",
"partnerRefId": "ref1122334422",
"description": "thanh toan MoMo",
"hash": "
VwnYQbw5eg2XGVO6uGgyOETG9dBQXjdOw8OyBptZ5zvsUTPiNxMc4hi1sd7TTRkifG0kaOJ
VgplrLlyogFxcegyZzQ7LtjDr/4FtN8MfFKWozhxSWW2JYQyJ/klegGVpOTSkXkfUoueGdTSI2IJF
S1pe5rxkmBdMWRilbyfOqbTdrWt50gjY2mQbhke7+9puGLgg8mh+NfYCbEZtHDKyDODA0M
VNMNh3ATd31KwfNLm0zx6QQ6KXBq5M04cpTA6rIZ9uz3fxEwTvPycuxJtLvtFDpLapNAmUw
qA2Rej3mTgOTN1+Jq9isqEueA0Ix3ip++d8GbJXJYkvYfr0XgT3zA==",
"version": 2.0
}
Detail hash parameter
Parameter Data type Requirement Description
partnerCode String √ MoMo provide for Mechant
when enter into the contract or
find in
[Link]
partnerRefId String √ Transaction ID of Merchant
system

9| MoMo Payment APIs – M_Service

 amount Integer √ Payment amount
paymentCode String √ Customer payment code
(maximum 20 characters)
storeId String The Merchant store ID
storeName String The Merchant store name

Example:
{
"partnerCode": "MOMOIQA420180417",
"partnerRefId": "Merchant123556666",
"amount": 30000,
"paymentCode": "MM627755248085056826",
"storeId": "1",
"storeName": "Cua hang doi tac MoMo"
}
Encrypted Hash string
VwnYQbw5eg2XGVO6uGgyOETG9dBQXjdOw8OyBptZ5zvsUTPiNxMc4hi1sd7TTRkifG0ka
OJVgplrLlyogFxcegyZzQ7LtjDr/4FtN8MfFKWozhxSWW2JYQyJ/klegGVpOTSkXkfUoueGdTSI2IJF
S1pe5rxkmBdMWRilbyfOqbTdrWt50gjY2mQbhke7+9puGLgg8mh+NfYCbEZtHDKyDODA0MV
NMNh3ATd31KwfNLm0zx6QQ6KXBq5M04cpTA6rIZ9uz3fxEwTvPycuxJtLvtFDpLapNAmUwqA
2Rej3mTgOTN1+Jq9isqEueA0Ix3ip++d8GbJXJYkvYfr0XgT3zA==

Parameter response detail

Parameter Data Type Description
status String Result code
message Json Detail of the result code
transid Number MoMo transaction ID
description String Description of transaction
amount Number amount of transaction

Example:
{
"status": 0,
"message": {
"transid": 12436514111,
"description": "Thành công",
"amount": 30000
}
}

10 | MoMo Payment APIs – M_Service

 6) Query transaction status
URL: [Link]

Method: HTTP POST

Request header: application/json
Response header: application/json

Parameter request detail:

Parameter Data type Requirement Description

partnerCode String √ MoMo provide for Mechant
when enter into the contract or
find in [Link]
partnerRefId String √ Transaction ID of Merchant
system
momoTransId String Unique MoMo transaction Id
description String Detailed description of
transaction
hash String √ RSA_Encrypt(
{

"partnerCode":"[partnerCode]",
"partnerRefId":"[partnerRefId]",
"requestId": "[requestId]"
}
)
version Numeric √ Current version is 2.0 (double
value)

Example:
{
"partnerCode": "MOMOIQA420180417",
"partnerRefId": "Merchant123556666",
"description": "thanh toan MoMo",
"hash": "
jClksw/4LI+lMdBHpfX++fYDKpUg4a8W/heOY3PQbxI7NJI3GFlRQGsi70CSTZuW0KKgBXSuvpI
Fd5zpzzxOi7MJg4qqNWRIEn2/PAiHjB2J6R4w+wdnz9yIAGkN8E9P4l4VAKFfR01quOWjIczjFx
T7V8ibOa92dYWtAEtms86Z7QYu4ZIw8m8b1IBgeifxm9T8k5Np3cati0QLUCEFkW+oKEWeV3
f3EGpxc7qFed4kPvxZAcBUzzQZHWUBxUVcH7d3tw7n6eGLI6lk+KvFjQRIMr94wvaPpVFXF04
9wexoUgPri8hUYJyPhEcchZDmeNJUZTWrB/1O1sJLKbSJgQ==",

11 | MoMo Payment APIs – M_Service

 "version": 2.0
}
Detail hash parameter
Parameter Data type Requirement Description
partnerCode String √ Merchant identify code
partnerRefId String √ Transaction ID of Merchant
system
requestId String √ Unique request id generated by
Merchant
momoTransId String Unique MoMo transaction Id

Example:
{
"partnerCode": "MOMOIQA420180417",
"partnerRefId": "Merchant123556666",
"requestId": "8374736463"
}

Encrypted “Hash” string

jClksw/4LI+lMdBHpfX++fYDKpUg4a8W/heOY3PQbxI7NJI3GFlRQGsi70CSTZuW0KKgBXSuvpIFd5zpz
zxOi7MJg4qqNWRIEn2/PAiHjB2J6R4w+wdnz9yIAGkN8E9P4l4VAKFfR01quOWjIczjFxT7V8ibOa92dYWtAEt
ms86Z7QYu4ZIw8m8b1IBgeifxm9T8k5Np3cati0QLUCEFkW+oKEWeV3f3EGpxc7qFed4kPvxZAcBUzzQZHW
UBxUVcH7d3tw7n6eGLI6lk+KvFjQRIMr94wvaPpVFXF049wexoUgPri8hUYJyPhEcchZDmeNJUZTWrB/1O1sJ
LKbSJgQ==

Parameter response detail:

Parameter Data type Description
status Number Status of request
message String Detail message of request
data Json Status of transaction

Example:
{
"status": 0,
"messages": "Thành công",
"data": {
"status": 1014,
"message": "Mật khẩu bạn nhập không chính xác.",
"partnerCode": "MOMOIQA420180417",

12 | MoMo Payment APIs – M_Service

 "billId": "Merchant123556666",
"amount": 30000,
"discountAmount": 0,
"fee": 0,
"phoneNumber": "0938***061",
"storeId": null,
"requestDate": "2018-07-12 09:46:32.872",
"responseDate": "2018-07-12 09:46:33.646",
"customerName": "DOAN CAO KHANG",
"transid": 147938695
}
}

7) Refund transaction

URL: [Link]

Method: HTTP POST

Request header: application/json
Response header: application/json

Parameter request detail:

Parameter Data Type Required Description

partnerCode String √ MoMo provide for Mechant
when enter into the contract or
find in [Link]
requestId String √ Unique request id per request
refund
hash String √ RSA_Encrypt({
"partnerCode":"[partnerCode]",
"partnerRefId":"[partnerRefId]",
"amount": "[amount]",
"momoTransId":"[momoTransId]"
})
version double √ Current is 2.0

Example:
{
"partnerCode": "MOMOIQA420180417",

13 | MoMo Payment APIs – M_Service

 "requestId": "1512529262248",
"hash": "
J0PyqdM8Mn8ZJAy8GSe1F/CwI9V4pYE66edb/lxKqRNboWh5eIy203M1xOpfisOmVTRuD5sF
DcVXjzWncQHi++75620shnFoh/ZPBqo2kQK8PhMcLjE5+aj+LkQo7ClqYh1o/ZFNDKDSvp2K+Y
MgMFSpFW3sW7fdamxqMxjQpA0yxUykQg4w0uEzU8ARCak5rcYfWqO9k75zJdKAYZhSrM3l
9a2DMZW5G8/PKKa1G+wonLInKiuzCZpf4P2gHNldob2aalBMdqptzlh/nsZ0ALRuXH3GzvWfE
FUNZCb/BLqQWBy4840rcjQDFJCa4UP4iXVvzkcV647481Si47TrXQ==",
"version": 2.0
}

Detail hash parameter:

Parameter Data type Required Description
partnerCode String √ MoMo provide for Mechant
when enter into the contract or
find in
[Link]
partnerRefId String √ Transaction ID of Merchant
system
momoTransId String √ Unique request ID generated by
Merchant
amount Number √ MoMo amount

Example:
{
"partnerCode": "MOMOIQA420180417",
"partnerRefId": "Merchant123556666",
"momoTransId": " 147938695 ",
"amount": 30000
}

Encrypted “Hash” field string

J0PyqdM8Mn8ZJAy8GSe1F/CwI9V4pYE66edb/lxKqRNboWh5eIy203M1xOpfisOmVTRuD5sFDcVXjz
WncQHi++75620shnFoh/ZPBqo2kQK8PhMcLjE5+aj+LkQo7ClqYh1o/ZFNDKDSvp2K+YMgMFSpFW
3sW7fdamxqMxjQpA0yxUykQg4w0uEzU8ARCak5rcYfWqO9k75zJdKAYZhSrM3l9a2DMZW5G8/PK
Ka1G+wonLInKiuzCZpf4P2gHNldob2aalBMdqptzlh/nsZ0ALRuXH3GzvWfEFUNZCb/BLqQWBy4840r
cjQDFJCa4UP4iXVvzkcV647481Si47TrXQ==

Parameter response detail:

Parameter Data type Description
status String Status of request
message String Detail message of request
transid number Status of transaction

14 | MoMo Payment APIs – M_Service

 amount Number Amount of refund transaction
partnerRefId String Vendor transaction id

Example:
{
"status": 0,
"message":"Thành công"
"transid": 12436514111,
"amount": 30000,
"partnerRefId": "Merchant123556666"
}

8) Error code
Preference in section 9

VII. ALL-IN-ONE ONLINE PAYMENT TECHNICAL GUIDE (M2 Payment)

1) Use case
Step 1: End User send request payment to Vendor server.

Step 2: Vendor server call M2 Payment system to get payUrl.

Step 3: Vendor submit request (redirect request) payUrl that returned in step
2.

Step 4: M2 payment show payUrl and user interact with M2 payment in figure
2.1 (Mobile web) or figure 3.2 (PC web). After paied successful, M2 payment
return result to Vendor server and end-user.

15 | MoMo Payment APIs – M_Service

If the end-user entering Vendor online shopping on Mobile website

Figure 2.1 M2 payment mobile web Figure 2.2 opening MoMo app Figure 2.3 Login MoMo account

Figure 2.4 confirm payment screen Figure 2.4 choose another money source Figure 2.5 MoMo transaction result

16 | MoMo Payment APIs – M_Service

If the end-user entering Vendor online shopping on PC web. M2 payment will show QR code
for user scan and pay.

Figure 3.1 M2 payment show QR code on PC web

Payment Rules:
Amount should be greater than 1,000 VND
Expire order depend on vendor, default is 10 minutes

2) Participating Vendors
Shopping: Robins Online, Akulaku
Online ticket: CGV, Ticket box, VnTrip
Entertainment: Bigo Live, Online Games, …
Other: VTV Cab, Utilities,…

17 | MoMo Payment APIs – M_Service

 3) Work flow

4) Exception Handling
Follow the instructions below to troubleshoot any payment exceptions:
If the Payer cannot find their order in their transaction history when they're
prompted of a payment error on MoMo, they will require the Vendor to
initiate the order again. if the order is successfully paid for, the Vendor’s
backend calls the Query Transaction Status API to query the actual payment
status again.

18 | MoMo Payment APIs – M_Service

 5) Submit M2 payment to get payUrl

URL: [Link]

Method: HTTP POST

Request header: application/json
Response header: application/json

Parameter request detail:

Parameter DataType Description

partnerCode String MoMo provide for Mechant when enter into the
contract or find in [Link]
accessKey String MoMo provide for Merchant when integration or find
in [Link]
requestId String Request ID is unique for each request
amount String Order amount in VND (>=1,000 vnđ).
orderId String Unique, transaction id of request (<= 100 characters)
orderInfo String Order information for each request
returnUrl String URL M2 payment redirect to Vendor to notify result for
end user with HTTP GET request type. M2 Payment will
get this information default if merchant passes empty
value.
notifyUrl String - Known as Instant Payment Notification (IPN)
is a message service that notifies you of
events related to MoMo transactions
([Link]
ipn/integration-guide/IPNIntro/ )

- After user confirm payment, M2 payment

will notify this URL 01 times at server side to
server side. Vendor server need to build this
URL to receive results from M2 Payment
send to with HTTP POST request type with
header application/x-www-form-
urlencoded. M2 will get default from MoMo
Business if Vendor passes empty value.
extraData String String contains extra data
requestType String Request type is captureMoMoWallet

19 | MoMo Payment APIs – M_Service

 signature String Signature for security. Signature is a string was hashed
by HMAC_SHA256 algorithm with format

(partnerCode=$partnerCode&accessKey=$accessKey&
requestId=$requestId&amount=$amount&orderId=$o
derId&orderInfo=$orderInfo&returnUrl=$returnUrl&n
otifyUrl=$notifyUrl&extraData=$extraData,
$secretKey)

Example:
{
"partnerCode": "MOMOIQA420180417",
"accessKey": "F8BBA842ECF85",
"requestId": "112233445566",
"amount": "10000",
"orderId": "1505359852755",
"orderInfo": "order info",
"returnUrl": "[Link]
"notifyUrl": "[Link]
"requestType": "captureMoMoWallet",
"signature":"b11f56378efd8810186e9...71be292d891ca4b6089"
}
Return parameter detail:

Parameter Description
requestId Request ID is unique for each request
payUrl URL that Merchant server submit request (redirect)
errorCode Error code
orderId Merchant transaction is stored on M2 payment system
message Error message in English
localMessage Error message In Vietnamese
requestType Request type is captureMoMoWallet
signature Signature for security. Signature is a string was hashed by
HMAC_SHA256 algorithm

(requestId=$requestId&orderId=$orderId&message=$message&l
ocalMessage=$localMessage&payUrl=$payUrl&errorCode=$error
Code&requestType=$requestType, $secretKey)

Example:
{
"requestId": "112233445566",
"orderId": "1505359852755",

20 | MoMo Payment APIs – M_Service

 "errorCode": "Error Code",
"payUrl":
"[Link]
=123456&access_key=F8BBA842ECF85&order_id=MoMo1507190134118&order_info=Test
%20MoMo%20Web%20payment&amount=98000&signature=7c32e644649fad1947bb816b
82c6c229210db147cc2086f174b3b07bc37b7ff5&return_url=[Link]
081/gw_payment/test_momo_pay&notify_url=[Link]
ment/test_momo_pay&extra_data=",
"message": "Success",
"localMessage": "Thành công",
"requestType": "captureMoMoWallet",
"signature": "b11f56378efd8810186e98d6…df71be292d891ca4b6089"
}
6) Processing the response from M2 payment server
Use case:
When user confirm the payment M2 Payment will response to returnUrl and
notifyUrl after end user payment completed, M2 Payment will return result
for Vendor with URLs that vendor provided in steps (2) include returnUrl and
notifyUrl.

Response result to Vendor:

NotifyUrl:

Method: HTTP POST

Header: x-form-url-encoded

ReturnUrl:

Method: HTTP GET and get parameter from URL.

Both nofityUrl and returnUrl are same parameter from M2 Payment.

Parameter Description
partnerCode MoMo provide for Mechant when enter into the contract or find
in [Link]
accessKey MoMo provide for merchant when integration
requestId Request ID for each request
amount Amount in VND that user purchased
orderId Transaction ID of Merchant
orderInfo Order information
orderType Transaction type is momo_wallet
transId Momo transaction

21 | MoMo Payment APIs – M_Service

 message Description about status of transaction in English
localMessage Description about status of transaction in Vietnamese
responseTime Transaction response time.
errorCode Status code of transaction.
payType web or qr
extraData Extra data
signature Signature for security. Signature is a string was hashed by HMAC
HMAC_SHA256 algorithm

(partnerCode=$partnerCode&accessKey=$accessKey&requestId
=$requestId&amount=$amount&orderId=$oderId&orderInfo=$
orderInfo&orderType=$orderType&transId=$transId&message=
$message&localMessage=$localMessage&responseTime=$respo
nseTime&errorCode=$errorCode&payType=$payType&extraDat
a=$extraData, $secretKey)

7) Query transaction status

Use case:
o When merchant want to know exactly the status of one transaction that
MoMo return from notifyUrl and returnUrl
o When merchant want to check the status of transaction when need.
URL: [Link]

Method: HTTP Post

Request header: application/json
Response header: application/json

Parameter request detail

Parameter DataType Description

partnerCode String MoMo provide for Merchant when enter into the
contract or find in [Link]
accessKey String MoMo provide for merchant when integration
requestId String Request ID is unique for each request
orderId String Merchant transaction ID
requestType String Request type is transactionStatus
signature String Signature for security. Signature is a string was hashed
by HMAC_SHA256 algorithm with format

22 | MoMo Payment APIs – M_Service

 (partnerCode=$partnerCode&accessKey=$accessKey&r
equestId=$requestId&orderId=$orderId&requestType=
$requestType, $secretKey)

Example:
{
"partnerCode": "MOMOIQA420180417",
"accessKey": "F8BBA842ECF85",
"requestId": "112233445566",
"orderId": "1505359852755",
"requestType" : "transactionStatus",
"signature": "b11f56378efd8810186e98d6ace…f71be292d891ca4b6089"
}
Parameter response detail:

Parameter Description
partnerCode MoMo provide for Merchant when enter into the contract or find
in [Link]
accessKey MoMo provide for Merchant when enter into the contract or find
in [Link]
requestId Request ID is unique for each request
orderId Merchant transacition ID
errorCode Error code
amount Payment amount
transId MoMo transaction ID
message Error message in English
localMessage Error message In Vietnamese
extraData Extra data
requestType Request type
payType Type payment: web or qr
signature Secure transaction in SHA256 verify with signature by
HMAC_SHA256 algorithm with format

(partnerCode=$partnerCode&accessKey=$accessKey&requestId
=$requestId&orderId=$orderId&errorCode=$errorCode&transId
=$transId&amount=$amount&message=$message&localMessag
e=$localMessage&requestType=$requestType&payType=$payT
ype&extraData=$extraData, $secretKey)

Example:

23 | MoMo Payment APIs – M_Service

 {
"partnerCode": "partner Code",
"accessKey": "access key",
"requestId": "request id",
"orderId": "Merchant transaction Id",
"amount": "Momo account",
"errorCode": "Error code",
"transId": "MoMo transaction ID",
"message": "SUCCESS",
"localMessage": "Description result of transaction",
"requestType": "Request Type",
"signature": "secure string"
}

8) Refund MoMo wallet

URL: [Link]

Method: HTTP Post

Request header: application/json
Response header: application/json

Parameter request detail:

Parameter DataType Description
partnerCode String MoMo provide for Merchant when enter into the
contract or find in [Link]
accessKey String MoMo provide for Merchant when enter into the
contract or find in [Link]
requestId String Request ID is unique for each request
amount String Refund amount
orderId String Transaction ID of Merchant
transId String MoMo SALE transaction ID
requestType String Request type is refundMoMoWallet
signature String Signature for security. Signature is a string was
hashed by HMAC_SHA256 algorithm
partnerCode=$partnerCode&accessKey=$accessKey
&requestId=$requestId&amount=$amount&orderI
d=$orderId&transId=$transId&requestType=$reque
stType

Example:
{
"partnerCode": "MOMOIQA420180417",

24 | MoMo Payment APIs – M_Service

 "accessKey": "F8BBA842ECF85",
"requestId": "112233445566",
"amount": "10000",
"orderId": "1505359852755",
"transId": "4756463547",
"requestType": "refundMoMoWallet",
"signature":
"b11f56378efd8810186e98d6ace63d8867860ba1d2cdf71be292d891ca4b60
89"
}

Parameter response detail:

Parameter Description
partnerCode MoMo provide for Merchant when enter into the contract or find
in [Link]
accessKey MoMo provide for Merchant when enter into the contract or find
in [Link]
requestId Request ID is unique for each request
orderId Merchant transacition ID
errorCode Error code
transId MoMo refund transaction ID
message Error message in English
localMessage Error message In Vietnamese
requestType Request type
signature Signature for security. Signature is a string was hashed by
HMAC_SHA256 algorithm

(partnerCode=$partnerCode&accessKey=$accessKey&requestId
=$requestId&orderId=$orderId&errorCode=$errorCode&transId
=$transId&message=$message&localMessage=$localMessage&r
equestType=$requestType, $secretKey)

Example:
{
"partnerCode": "MOMOIQA420180417",
"accessKey": "SvDmj2cOTYZmQQ3H",
"requestId": "1533362283",
"orderId": "1533362283",
"amount": "10000",
"errorCode": "0",
"transId": "149164337",
"message": "Success",
"localMessage": "Thành công",
"requestType": "Request Type",

25 | MoMo Payment APIs – M_Service

 "signature": "2597d8e9f20f2a2016d9a457087b32869de9c6417552718c667da948d74f6b32"
}

9) Query refund status

URL: [Link]

Method: HTTP Post

Request header: application/json
Response header: application/json

Parameter request detail:

Parameter DataType Description
partnerCode String MoMo provide for Merchant when enter into the
contract or find in [Link]
accessKey String MoMo provide for Merchant when enter into the
contract or find in [Link]
requestId String Request ID is unique for each request
orderId String Merchant’s transaction
requestType String Request type is refundStatus
signature String Signature for security. Signature is a string was
hashed by HMAC_SHA256 algorithm

(partnerCode=$partnerCode&accessKey=$accessKey
&requestId=$requestId&orderId=$orderId&requestT
ype=$requestType, $secretKey)

Example:
{
"partnerCode": "MOMOIQA420180417",
"accessKey": "F8BBA842ECF85",
"requestId": "112233445566",
"orderId": "1505359852755",
"requestType" : "refundStatus",
"signature": "b11f56378efd8810186e98d6ace…f71be292d891ca4b6089"
}
Parameter response detail:

Parameter Description
partnerCode MoMo provide for Merchant when enter into the contract
accessKey MoMo provide for merchant when integration

26 | MoMo Payment APIs – M_Service

 requestId Request ID is unique for each request
orderId Merchant SALE transacition ID
errorCode Error code
amount Amount of transaction
transId MoMo transaction ID
message Error message in English
localMessage Error message In Vietnamese
requestType Request type
signature Secure transaction in HMAC_SHA256 verify with signature

(partnerCode=$partnerCode&accessKey=$accessKey&request
Id=$requestId&orderId=$orderId&errorCode=$errorCode&tra
nsId=$transId&amount=$amount&message=$message&local
Message=$localMessage&requestType=$requestType,
$secretKey)

Example:

When have 1 refund transaction

{
"partnerCode": "PCODE_7S20171227",
"accessKey": "YDTbS8NIUbbRedLg",
"requestId": "1519305242170",
"orderId": "1519305242170",
"amount": "150000",
"errorCode": 24,
"requestType": "queryRefund",
"transId": "137192601",
"message": "Amount is larger than the remains",
"localMessage": "Amount is larger than the remains",
"signature": "a9ac22c41528597b103fe73b2e70e347eda02a…0396ed"
}
When have more than 1 refund transaction
[
{
"partnerCode": "PCODE_7S20171227",
"accessKey": "YDTbS8NIUbbRedLg",
"requestId": "1519303850746",
"orderId": "MM1519133538275",
"amount": "3000",
"errorCode": 0,
"transId": "137101515",
"requestType": "queryRefund",
"message": "Success",
"localMessage": "Thành công",
"signature": "0d6e226c0c0a496ae2a1d0…21904deebc0bc5b998450f"
},
{

27 | MoMo Payment APIs – M_Service

 "partnerCode": "PCODE_7S20171227",
"accessKey": "YDTbS8NIUbbRedLg",
"requestId": "1519303850746",
"orderId": "MM1519133538275",
"amount": "3000",
"errorCode": 0,
"transId": "137101827",
"requestType": "queryRefund",
"message": "Success",
"localMessage": "Thành công",
"signature": "0498136e88129f6088b61e1dd…73b2dbece4aff7f31e1c"
},
{
"partnerCode": "PCODE_7S20171227",
"accessKey": "YDTbS8NIUbbRedLg",
"requestId": "1519303850746",
"orderId": "MM1519133538275",
"amount": "3000",
"errorCode": 0,
"transId": "137101873",
"requestType": "queryRefund",
"message": "Success",
"localMessage": "Thành công",
"signature": "2f7593f5fd9bbc17ce70…5e77567e3f5d171d94ef64064"
}
]

10) Error Code

Error Code Message

0 SUCCESS
-1 Transaction init
1 Empty accessKey or partnerCode
2 OrdeId wrong format
4 Amount invalid. It should be between 1,000đ and 20,000,000đ
5 Signature wrong. Check raw signature before signed
6 OrderId exists. Please create new transaction
11 General system failure. Contact MoMo system admin
12 Duplicate request id. Please create new request id
14 Partner is not actived
22 Invalid Wallet id
29 System maintenance. Please try in few minutes
31 User failed authentication in MoMo system
32 Transaction was purchased
33 Cannot refund transaction
34 Transaction refunded
35 Undefined status of transaction. Transaction under reviews
36 Expired transaction

28 | MoMo Payment APIs – M_Service

 38 Insufficient funds
44 Service not support your request
49 Order was canceled by user
63 Pay by bank source is failure
99 Error undefined

VIII. APP-TO-APP ONLINE PAYMENT TECHNICAL GUIDE

1) Use case
Step 1: Merchant Mobile App get token through MoMo app

Step 2: The end-user confirm payment on MoMo app and MoMo app response
token

Step 3: Merchant Mobile app receive data package from MoMo app and send this
package to Vendor server.

Step 4: Merchant server update payment data and send to MoMo Payment
server.

Step 5: MoMo Payment server do payment and response to Vendor server.

Step 6: Vendor server notify result to Vendor app.

29 | MoMo Payment APIs – M_Service

 Figure 4.1 Vendor checkout screen Figure 4.2 MoMo confirm payment screen
2) Participating Vendor
Online: CGV, Tiki, Ahamove, VNtrip
3) Work flow

4) Exception Handling
Follow the instructions below to troubleshoot any payment exceptions:
o If the Payer cannot find their order in their transaction history when
they're prompted of a payment error on MoMo, they will require the
Vendor to initiate the order again. if the order is successfully paid for, the
Vendor’s backend calls the Query Transaction Status API to query the
actual payment status again.

30 | MoMo Payment APIs – M_Service

5) Mobile integration

Request MoMo app parameter in step 1

Parameter Description Required

merchantname Vendor brand name is brand name √
merchantcode MoMo provider known as partnerCode √
merchantnamelabel Vendor name
amount Amount of transaction √
fee Service fee
description Description of order √
username Account/email of customer
extra Additional information
appScheme IOS ONLY. Config in CFBundleURLTypes √
Plist
MoMo will callback to partner app when
user action on confirm payment screen
include cancellation and confirmation
button

4) Response parameters from MoMo app in step 2

Parameter Description
status Status (0: success)
message Message
data Data returned from MoMo app, will be send to MoMo server (call
as Token)
phonenumber Customer phone number

5) Status defination

Status Description
0 SUCCESS. Continue to step 3 with
[data,phonenumber] to Merchant Server
1 Please input MoMo Password

31 | MoMo Payment APIs – M_Service

 2 Please choose money source (MoMo
Wallet or bank account)
3 Transaction timeout (60s)
4 User cancel transaction

*Only status=0, Vendor App send [[Link]] to Vendor Server

6) Example:

Android: [Link]

IOS: [Link]

7) Submit to MoMo App-in-App Payment server

After the receive token from MoMo app, Vendor server build data and send to
MoMo App-in-App payment server

URL: [Link]

Method: HTTP POST

Request header: application/json
Response header: application/json

Parameter request detail:

Parameter Datatype Require Description

ment
partnerCode String √ MoMo provide for Merchant when
enter into the contract or find in
[Link]
partnerRefId String √ Transaction ID of Merchant system
customerNumber String √ MoMo customer phone number. Data
received from MoMo Application
(Android/iOS)
amount Integer Payment amount
appData String √ MoMo App data. Data received from
MoMo Application (Android/iOS)

32 | MoMo Payment APIs – M_Service

 hash String √ RSA_Encrypt(
{
"partnerCode": "[partnerCode]",
"partnerRefId ":"[partnerRefId]",
"amount": [amount],
"partnerTransId":"[partnerTransId]",
"userName": "[userId]"
}
)
description String Detail description of transaction

version Numeric √ Current version is 2.0 (double value)

Example:
{
"customerNumber": "0966787273",
"partnerCode": "MOMOIQA420180417",
"partnerRefId": "Merchant123556666",
"appData":
"v2/qml0PbOlrBYjFlZvXwRWjoMpmFmvqStTJt4DCXfE0cgMtyH5Akv+FxL2Nu8lDmxt0P3Mu
+YeCGB+UFfwXICo7D07jR6f2VhauglozphNgkK7724sO3qVKC9ZI8KCdr0k4AHuuUNF4AT6Iy2
rOmaCVF1WeyS/y/n2E4DArwaHG2J+8StiawfZPiKoUGvywNHV",
"hash":
"
A7WFmmnpn6TRX42Akh/iC5DdU5hhBT9LR5QSG6rJAl70hfEkkGUx2pTCai8s+M9KMVUcJ7m
52iv74yhmeEjjN10TtEJoqITBIYBG2bqcTprhDijyhV4ePU7ytDNuLxzzIvGfTYyvbsEJ2jZTSf556y
od12vhYqOJSFL/U2hVuxjUahf5Rnu5R/OLalg8QmlU6nQooEuNdzEXPMd6j9EaxOCiB2oM5/9
QiTN0tCNSTIVvPtnlHu5mIbBHChcwfToIL4IAiD1nbrlDuBX//CZcrZj6hFqjvU31yb/DuG02c3aq
WxbZKZ8csOwF9bL30m/yGr/0BQUWgunpDPrmCosf9A==",
"description": "Thanh toan cho don hang Merchant123556666 qua MoMo",
"version": 2.0
}

Detail hash parameter:

Parameter Data type Requirement Description
partnerCode String √ MoMo provide for Merchant when
enter into the contract or find in
[Link]
partnerName String Merchant name
partnerRefId String √ Transaction ID of Merchant
system

33 | MoMo Payment APIs – M_Service

 partnerTransId String Unique request id generated by
vendor
amount Number √ MoMo amount
description String Description of transaction
customerNumber String Customer phone number
userName String Customer username
storeId String The partner store id
storeName String The partner store name

Example:
{
"partnerCode": "MOMOIQA420180417",
"partnerRefId": "Merchant123556666",
"partnerTransId": "8374736463",
"amount": 40000,
"description": "Thanh toan momo"
}

Encrypted: Hash string

A7WFmmnpn6TRX42Akh/iC5DdU5hhBT9LR5QSG6rJAl70hfEkkGUx2pTCai8s+M9KMVUcJ7m52iv7
4yhmeEjjN10TtEJoqITBIYBG2bqcTprhDijyhV4ePU7ytDNuLxzzIvGfTYyvbsEJ2jZTSf556yod12vhYqOJ
SFL/U2hVuxjUahf5Rnu5R/OLalg8QmlU6nQooEuNdzEXPMd6j9EaxOCiB2oM5/9QiTN0tCNSTIVvPtn
lHu5mIbBHChcwfToIL4IAiD1nbrlDuBX//CZcrZj6hFqjvU31yb/DuG02c3aqWxbZKZ8csOwF9bL30m/y
Gr/0BQUWgunpDPrmCosf9A==

Return parameter detail:

Parameter Description
status MoMo status transaction
message Status message
transid MoMo transaction ID
amount Amount return by MoMo
signature Signature for security. Signature is a string was hashed by
HMAC_SHA256 algorithm

(status=$status&message=$message&amount=$amount&transid=
$transid, $secretKey)

Example:
{
"status":0,
"message": "Thành công",

34 | MoMo Payment APIs – M_Service

 "amount": 40000,
"transId": "43121679",
"signature": "307b0ee753798e3aff6eb69b2d7966bf0fab29f88336ce0763532fcfafadbe28"
}
8) Query transaction status
Preference in section 6.6
9) Refund transaction
Preference in section 6.7

IX. ERROR CODE

Code Description Note
0 Success
-1 Transaction not exist or wrong format
3 Agent not found
4 Agent not registered
6 Agent suspended
7 Access denied
8 Bad password
9 Password expired
11 Password retry exceed
13 Target not found
14 Target not registered
17 Invalid amount
23 Amount too small
27 Agent expired
29 Invalid password
31 User not exist in MoMo system
32 Request expired
33 Transaction reversed
34 Transaction error
45 In timeout
46 Amount out of range
47 Target is not special
48 Billpay account invalid

35 | MoMo Payment APIs – M_Service

 151 Amount not in range from [A] to [B]
153 Decrypt hash data fail
Payment capset limited by user. Current user
payment capset is [X]. Please contact MoMo
161 customer support for assistance
162 The payment code has been used
208 Partner is not active
210 Service maintenance
403 Permission denied
404 Request not found
1001 Insufficient funds
1002 Transaction recovered
1003 Wallet Balance Exceeded
1004 Wallet Cap Exceeded
1006 System Error
1007 DB Error
1008 Bad request
1013 Auth expired
1014 Wrong password
1020 Invalid param required
2101 User not login
2111 The payment information was missing
2117 Bill expired
2125 Cannot refund transaction
2126 Partner is not config
2127 Partner config not found or wrong format
2128 Duplicate request ID
2129 Signature not match
2131 Bill not exist or expired
2132 Transaction processed
2135 Partner payment fail
2137 Partner account had linked
2138 User session has been expired
2400 Bad format data
9000 Transaction processing

36 | MoMo Payment APIs – M_Service

X. MOMO PRERRED EPA (Electronic Payment Advice) FILE SPECIFICATION
This document describes the preferred format for EPA (Electronic Payment Advice) files in
the CSV (Comma-Separated Values) format in a single currency environment.

Every EPA file consists of two parts:

● a header containing consolidated information (one line) 


● line items containing transaction information (multiple lines, one for each
transaction)

Header Format:
The header consists of one line, which has the following values

H,"VND", 1259855, 37795, 975, 20080403,

The string 'H' (for Header) is fixed – all header lines should start with this string.
 The
following table details the meaning, format and possible values of the following values:

Fields description:

37 | MoMo Payment APIs – M_Service

 # Name Format Description and Example
1 RecordType String The constant string 'H' for 'Header'
2 settlementCurrency String The settlement currency in ISO 4217, all caps.
Example: “VND”
3 totalSettlementAmount Number The total amount settled. Example: 123000800
4 commissionAmount Number The total amount of commission. Example:
1230800
5 nrTransactions Number Total number of transaction settled
6 date YYYYMMDD The date of settlement. Example
20180305
Line Item Format:
Every line corresponds with exactly one settled transaction. The total number of
transactions should equal the nrTransactions field from the header.

The Line Items look like the following:

D,MOMO, 149455831, 1112072150543935, 25000, 0, 20180401,25000, VND, SETTLED,

D,MOMO, 149455832, 1112072150543936, 100000, 0, 20180401,100000, VND, SETTLED,
D,MOMO, 149455833, 1112072150543937, 23000, 0, 20180401,23000, VND, SETTLED,
D,MOMO, 149455834, 1112072150543938, 78000, 0, 20180401,78000, VND, SETTLED,
D,MOMO, 149455835, 1112072150543939, -25000, 0, 20180401,-25000, VND, REFUNDED,

Fields description:

# Name Format Description and Example

1 RecordType String The constant string 'D' for 'Data'
2 mid String Merchant ID known as partnerCode
3 tid String The unique MoMo transaction ID
4 txReference String The unique Merchant transaction ID
5 settlementAmount Number The net settlement amount. Example: 25000
6 commissionAmount Number The commission amount. Example: 25
7 transactionDate YYYYMMDD The date of transaction.
8 txAmount Number The original transaction amount.
Example: 25000
9 txCurrency String The original transaction currency in ISO
4217, all caps. Example: VND
10 type String The transaction status type. Usually
SETTLED.
11 extra String Space for additional information
(optional)

38 | MoMo Payment APIs – M_Service

 Separators:
Lines should be terminated by a LF character (0x0A), a CR character (0x0D) or a combination
CRLF (0x0D,0x0A). Fields are optionally enclosed by double quotes.

Refunds:
Commission amounts can be refunded to the merchant, but it is also possible not to refund
the commission to the merchant. In the latter case, the Transaction Types SETTLED
REFUNDED CHARGED_BACK

Transaction Types:
SETTLED The transaction settlement is included in this batch.
REFUNDED A partial or full refund of a transaction
CHARGED_BACK A reversal of a transaction

If you use other statuses, please contact us.

Method of Transmission
Please use one of the following means for communication the EPA files to us:

* FTPS, S/FTP pull or push

* HTTPS download or upload

* GPG-encrypted email

File Name Convention [optional]

Please include the settlement date in the file name, using the format YYYYMMDD.

39 | MoMo Payment APIs – M_Service