Please read Onboarding first!!

Ver. Create date Author Description PDF
1.0 24-12-2018 Phuc Dang Init document
1.1 27-09-2019 Phuc Dang - Add dateInMillis into STATUS API and NOTIFY PAYMENT.
- Add validate callbackUrl in INIT API
1.2 22-11-2019 Vu Huynh - Modify collection standard document to "payment on MoMo App" and "Payment on Partner Side"
1.3 10-04-2020 Phuc Dang - Modify something
1.4 22-09-2020 Phuc Dang - Modify fields name
- add repaymentPeriod field in BillInfo
1.5 28-09-2020 Phuc Dang - Add walletId field, used for store debitor wallet id
1.6 19-11-2020 Phuc Dang - Modify some field PDF
1.7 09-03-2021 Phuc Dang - Modify description flow
1.8 13-05-2022 Duy Le - Add FAQs section

OVERVIEW

Payment from Parner site

Using methods:

METHODS

1. INIT PAYMENT

The following endpoint init a transaction.

SERVER CLIENT END POINT METHOD HEADERS
MOMO PARTNER /api/gw_payment/init POST Reference to Headers

SAMPLE

Sample request

{
  "requestId": "LetsChangeItForEachRequest",
  "reference1": "OrderID",
  "reference2": "",
  "client": "webinapp",
  "callbackUrl": "https://sample.partner.url/callback",
  "notifyUrl": "https://sample.partner.url/notify",
  "description": "",
  "totalAmount": 100000,
  "checksumKey": "ChecksumKey",
  "accountInfo": {
    "name": "What Your Name"
  },
  "billList": [
    {
      "billId": "OrderID",
      "totalAmount": 100000,
      "description": "",
      "extras": {}
    }
  ],
  "extras": {}
}

Sample response

{
  "requestId": "1615261513",
  "referenceId": "1210744185270711_5295",
  "resultCode": 0,
  "message": "Success",
  "data": {
    "target": "https://testing.momo.vn:22447/fi/authorize?r=1615261513&s=gwpayment_dev_1615261513&t=1210744185270711_5295",
    "qrCode": "https://testing.momo.vn:22447/fi/gw_payment/authorize/s?r=1615261513&s=gwpayment_dev_1615261513&t=1210744185270711_5295"
  }
}

TRY IT

curl without PGP encrypt

curl -L -X POST 'https://testing.momo.vn:22446/api/gw_payment/init' -H 'Accept: application/pgp-encrypted' -H 'Content-Type: application/pgp-encrypted' -H 'partner-code: gwpayment_dev' --data-raw '{
  "requestId": "LetsChangeItForEachRequest",
  "reference1": "OrderID",
  "reference2": "",
  "client": "webinapp",
  "callbackUrl": "https://sample.partner.url/callback",
  "notifyUrl": "https://sample.partner.url/notify",
  "description": "",
  "totalAmount": 100000,
  "checksumKey": "ChecksumKey",
  "accountInfo": {
    "name": "What Your Name"
  },
  "billList": [
    {
      "billId": "OrderID",
      "totalAmount": 100000,
      "description": "",
      "extras": {}
    }
  ],
  "extras": {}
}'

$response:

{
    "requestId": "LetsChangeItForEachRequest_1615878006714",
    "referenceId": "1826709321828577_6887",
    "resultCode": 0,
    "message": "Success",
    "data": {
        "target": "https://momodev.page.link/2Bj5rNb4VTo7advWv7",
        "qrCode": "https://testing.momo.vn:22447/fi/gw_payment/authorize/s?r=LetsChangeItForEachRequest&s=gwpayment_dev_LetsChangeItForEachRequest_1615878006714&t=1826709321828577_6887",
        "storeUrl": ""
    }
}

curl with PGP encrypt

curl -L -X POST 'https://testing.momo.vn:22446/api/gw_payment/init' -H 'Accept: application/pgp-encrypted' -H 'Content-Type: application/pgp-encrypted' -H 'partner-code: gwpayment' --data-raw '-----BEGIN PGP MESSAGE-----
Version: BCPG v1.65

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
+NxjHA==
=3DFl
-----END PGP MESSAGE-----'

$response:

-----BEGIN PGP MESSAGE-----
Version: BCPG v1.65

hQEMA+3PmYCXiyI4AQf+MjhPF45SHzJV6h4eLVYC6bvqDFWkbKXFqochPnF9NdVy
lOWn8/atAKZHhCTJqGQPxAyLW8jfblx2lbKElPRaouYY0YCcziS7sBEvnSK1DcBl
sSUBCI7qiv5iRV+F7FAKgt1bA/TPL6MKHTquT3AsoGgyDDRt7iLQbuI3AtLJQfrG
z7+H5GhJ9mXnaY/XbjMq29w8kN4fEWiJGf1qQ5eM0b1Eo6NVocdNUXhqI4pumRDZ
Bc5NvjZfgFYkOuMaag7MrPUqwUt19+MsYa+KkSFb7967rPHwlapwI2RGNN23qIBl
MJwBKUDYRmSQK1ui5qrnKadIGn9ntfA9SDMF63+HTIUBDANRmJMq4kZPPQEH/3zf
VF73FjY2oAkrquRxLjpq06h3MCmYQaUWBtYo4xPw/PZye5ltY8MLRPKxOvq9eqrI
Taz/G+AGxTGoMIgvkNBAnLE1WIZts3JvoGQeHxOsj31sGk28bSqrqIQQf1/f2IYB
AkbnM+dH8sw3+LRBEyU0/ChtUT6VlMqR5EiGJXqw4dwXEEIF0+B4QgxilQFWOopY
IwLRF12EuRu7Uu3ijkZI7t3Ju8EQJ5jeWoOpsNqFDuEKp8I4HtoFFEixdOS97gna
xterkiI6nJ3eype/q85T9SLmykkhADYnkvp7rtFQzX1Ms9agoPpQ5Y4Jvn1Yc1m2
ExG0RliOICP7BgSJa6yFAQwDrP2jbteVgPIBB/40tc/6tzzURs8XJpv2h5ELb4Jl
S9r99agRqTUJKnujcXDYkms/VtZHkMhyzbdQPe7/IA6Fp4dlW108HcaRjfvGBgse
GmYGPrpcapZoktcxoEhc0qxXg8kNU1gLTPqTAvXpxqT4t9xMN2DK41MqvDFThkSz
YafVNY6etOHyiSawlx3K7u2UnTz+bsqSSEYjF3dOSAU009XokodTUDd26K7sGeEE
7uRQnboXcrYyDHW2QpxX2cW0f6J55uvDRq/ia6DSyA7m7YLFhmxzUY4BWhSSvOXj
gXHeHPIpZHX0wanxABVX2RelwZiEVfAK0wyazk0aFP/tRBnX1VZ9eppp9+16ycGr
fmemrHgrAMqOYEoYGLqxJ7d5/UorrHoTx2OEmSyZ9VwsLOR5/lAodckOLlzb5QTh
PitnCoge3jjkqUBlnB2ExhT1t9dghau34kaSSZQ6yxQA0aGFc6Fr5eJU6dLaugmq
6euZ7ZeiDdXlpKqJiuGaAko8VoobzD14UxkTn+680Ptlp1xdtkmihg+cM0G5IIzk
UyPn/CtNy5GqHJnCgsdK4GS5KaQWmTWYtXqbEYYibexsL6PTE+2fXT1ODmTlgQow
70PvAoIwXqz+c4Ga0aEMVPVAvgXjqjsayp7p3Y7XtGvNegIYe58cVYbByiGaKPqc
8jPDhgz5aoUFfmRE12i8GlxheL3CxwTPPO0w5hc8QpoZaAyYXTlF6a9S5ajoS/xY
syl+5BAU4TPVrRPEr2VN2clVKgtR2hTMRVKM1/IwMv8fM7uYdgh+SuRRtrkMyly+
c+IMJKJ0YXEeJ3HRNWofDDiw+iEFsYh5DPAd93LmKzqRSMWoM8Q09HoJ32febVyE
JA20EUrBOb1ENtWnRqvfnjo4O0LufIR3zHzJQNcvt7BLhVZw3h0P4b/tzHkEjudb
9/Vj+SRsJYuy0x8HEnp+ePDAWXDUC7Wwo3ybzYqtR6veyu4a0kJnvdgdZYkxrZXG
QquXQ6FcGIA4gOx7XBDjhR1DWkR5R3J0Yap32pwhDJrU5PPQJ49EA6IfYJNb0i7u
glXt2R/w2Dx3wkOmlBLU7136EUaGbD1NHvx8i8b97tBYNwtx0hEHP4ONgvNtftxZ
xt/0+ERfcTRMvyEQY0bse9e3D2oFpVYMlDsl9adz5tVlFyBvJP83HCGN3w==
=TPLu
-----END PGP MESSAGE-----

Abtributes

Request Parameters

Name Type R L Description Error
requestId String(50) R L1 Unique string for each request 2003
client String(20) R L1 webinapp open Momo App by web
android_app open Momo App by Android App
ios_app open Momo App by iOS App		 2001
callbackUrl String(100) L1 Momo will redirect to it from the MoMo Web/App to push the payment result.
notifyUrl String(100) L1 Momo will invoke Notification Method from MoMo Backend, otherwise leave it blank
reference1 String(50) R L1 It's contract id / bill id etc. (depends on the partner)
It's related to the Callback and Notification Method.
Info displayed on the Momo App		 2001
reference2 String(50) L1 Extra info for support reference1 (depends on the partner)
It's related to the Callback and Notification Method.
description String(100) L1 Description for this transaction.
Info displayed on the Momo App
totalAmount Number R L2 Total of totalAmount in billList
Info displayed on the Momo App
checksumKey String(50) R L1 Used to check data when Callback
extras JsonObject L1 Used to store extras information
accountInfo JsonObject R L1 The contract owner information 2005
name String R L2 Holder bill
billList JsonArray R L1 Used to store bills
billId String R L2 Bill id
totalAmount Number R L2 Total Amount of this bill
description String L2 Bill description
extras JsonObject L2 Bill extras infomation

Response Params

Name Type R L Description
requestId String R L1 Same with request
referenceId String R L1 Unique for each response
resultCode Number R L1 The result code of transaction
message String R L1 The result message, which describes the code
data JsonObject R L1 data exist when resultCode is 0
target String R L2 Target link, use for redirect to MoMo App
qrCode String R L2 MoMo QR code, use camera scan it to open MoMo App.

2. Check info

The following endpoint check status of payment request by request id

SERVER CLIENT END POINT METHOD HEADERS
MOMO PARTNER /api/gw_payment/info POST Reference to Headers

TRY IT

curl without PGP encrypt

curl -L -X POST 'https://testing.momo.vn:22446/api/gw_payment/info' -H 'Accept: application/pgp-encrypted' -H 'Content-Type: application/pgp-encrypted' -H 'partner-code: gwpayment_dev' --data-raw '{
    "requestId": "LetsChangeItForEachRequest",
    "requestIdCheck": "1614927872"
}'

{
    "requestId": "1615263370",
    "resultCode": 0,
    "message": "Success",
    "data": {
        "requestId": "1614927872",
        "reference1": "OrderId",
        "reference2": "",
        "resultCode": 0,
        "resultMessage": "Success",
        "totalAmount": 80000,
        "amount": 80000,
        "creditAmount": 0,
        "paymentId": 1234567890,
        "paymentDate": "01-01-1970",
        "paymentMillisTime": 0,
        "billList": [
            {
                "billId": "OrderId",
                "description": "",
                "totalAmount": 80000,
                "repaymentPeriod": 0,
                "extras": {},
                "required": []
            }
        ]
    }
}

curl with PGP encrypt

curl -L -X POST 'https://testing.momo.vn:22446/api/gw_payment/info' -H 'Accept: application/pgp-encrypted' -H 'Content-Type: application/pgp-encrypted' -H 'partner-code: gwpayment' --data-raw '-----BEGIN PGP MESSAGE-----
Version: BCPG v1.65

hQEMAy0qeEWFdvPfAQgAzgQQQMk0Hgeo85iEKHWPPG02SZk+jLgKLI+48aQsSITu
Q9WnuBljn9jHeryCliv9+lOScrLkuQNt5rmRleMLoRay/EHqZHr7DLTiWzjfQQMB
jiuaGtybrjTZuzcJnFn0bjVkaDoVVRJq1in/3CoV6Ntt2BHc0NdwTzY2XUMrDv28
OI/P0fwaAx9LSQaT4PDHCdgXmxTAtC8hVRV0NYl/8ZbAY2CN+l3vXsyYz8JxIFha
yak0JAeiNk5kFR+JS44tzdSmY5RpSsIA77+rCLVqtvUERlMoWYwoLHLvZVp3c5Px
+wnWlCjX6E9vB5XogA+okBXVRnSXyoyvtnGqWA27IIUBDAOpz8P95mmetAEH/2L9
F7LaqH7U2TysVS+djdrmMe7mumqqbi0kREeMuvf6o7pjcZCdG7aMsUuHozAIiFMx
0wWov8Otqi4Kqmn1aITf+6TC+mvz3HSdjjsRqJM8CnB64313CeXBWeXSRLcNrjhA
2FGTqq/qrYaygVtPAoIu3Z/fu+/xzP+XDaoXLDHf771vJh9W5H/oQfBV+U182u8k
SN4WtNttoQtpGw0XuuWJhxH4lCTByJaWvaQfV67EiqOSjUxM6GtlVm5LTD/Vl+2Z
ptJngkLN/fMdY0NQjSbvxDkgX0VuwyukK7mUi8s5L0KiuGi5oSXyyhznYsIE5BJe
1MHlCbxPrYzmVXW9Q5SFAQwDI7kt/H2R/0MBB/wJCMghLJoLm8PpeCoXnLmvOaBR
51QXnuLpX/Gu92X6+xMxP9Qxs3kGFLIAsSlYEljo6g3JDIo/kc0pl8ZULKIlI2da
gumd5FhBMV5r8bLAmod+vi3zduPoFkmr0PweSKdPLAOeuTJidPdnNdIyTw612m/9
tacr9Xnuy+/OGyhbFKToGCaIdyBi2H+slyDXZq4UvJIhMfEyYasTUY22wZ/w9PfB
K8Vyo9wqi52Mud34DPINiOkOSbvlVgj0EHsGHsXQQv3wNVPpANRkwhjeb1GHPVPW
unBHmDiTrwwucuoK2r2ARHO3MgnoDjA9uZpjKXbETOqwNXA1sWvs9Oh9yXECycD7
tqKQvTqipfttTsB8g7sJ2GtzWP3CI5j9JL0z+nUlq4HTURQTSOwqC8VfppOYTOsg
46qqZ//WnZU2iUCctKzdkW2HP1dTlv+P5GNClnj5jG96ErRz3OjcqB/khBl3rKvr
BZA7yMPf4Qu8l9ux9Hhg3P7aNbjIcUR/m62yjKfuZuEuXlU2fD0H4+IMzrE5iW83
3ourSl8u9HxcwIOc+BPKkhhRQcEX7wgVPSTcJ+MAdeK+VP2NR5Kljwze1BzIEKdA
4s1JtHWBxxQfu+TygPV3QH4n1R/PqQZAbKK0htUV63Q+eFLO/CpHfKnZMiDGcxq3
eZRh9/RYsGfdCUu1k1CNAvHU1gXGIqcVP4vz2QLzmyh07S/XAwjvoKlHfMXG6lYj
iugVwJmrBX7nivedqInzSXv9FABtN7SfBFrfDkb9EQDtLDAMWu0nvfzJZJkucWiZ
7otWHqjlrRqKlaGt4JE9uGvIeRJ/t9YmMPgHPYsmali6/eDGGQ/3qJXVcztZZ9m4
/XRcLVouIot86ea0iGCb3ZV0NVzhIpeQVv4AW+SGZ6oiVh6EfvvGQHSxlqrcniDx
qSINy4EEb2mr94M=
=RRuT
-----END PGP MESSAGE-----'

$response

-----BEGIN PGP MESSAGE-----
Version: BCPG v1.65

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
=/oYH
-----END PGP MESSAGE-----

Attributes

Request params

Name Type R L Description Error code
requestId String(50) R L1 Unique string for each request 2003
requestIdCheck String(50) R L1 This is the requestId to check, it's the same as the requestId in INIT API 2008

Response params

Name Type R L Description
requestId String R L1 Same with request
referenceId String R L1 Unique for each response
resultCode String R L1 Request's result code
message String R L1 Result message
data Object R L1 Object include below information
requestId String R L2 The same with requestId in INIT API
reference1 String R L2 The same with reference1 in INIT API
reference2 String L2 The same with reference2 in INIT API
totalAmount Number R L2 The same with totalAmount in INIT API
amount Number R L2 Paid amount in MoMo app
creditAmount Number R L2 Total credit amount user has payment (Depend on partner)
paymentId Number R L2 Payment transaction id
paymentDate String R L2 Payment time in MService system
paymentMillisTime Number R L2 Current milli second of payment date
billList Json Object R L1
billId String R L2 Bill id, in multi-bill case billId is 1 reference1 has multi billId
amount Number R L2 Amount Momo money source
creditAmount Number R L2 Credit amount
extras Json Object L2 Extras info

3. Callback

The following endpoint sends the payment results to the partner via URL, please validate the encryptedData param to make sure the info received is correct.

SERVER CLIENT END POINT METHOD
PARTNER MoMo app/web PARTNER-CALLBACK-URL?data=QUERY-STRING-BASED64 GET

Sample request

https://sample.partner.url/callback?data=VGhpcyBpcyBzYW1wbGUgYmFzZWQ2NA==

This data param will encrypted Base64 before send to partner in query string

{
  "requestId": "1511347353577",
  "referenceId": "1511347353577",
  "reference1": "REF1_INFOISPLAYINMOOMOAPP",
  "reference2": "REF2_OPTIONALBILLID",
  "resultCode": 0,
  "paymentId": 1511347353577,
  "amount": 10000,
  "creditAmount": 0,
  "encryptedData": "B3ABE5D8C69B38733AD57EA75E83BCAE42BBBBAC75E3A5445862ED2F8A2CD677"
}

Query string with these parameters:

Name Type R L Description
requestId String R L1 Same with requestId in Init Payment request
reference1 String R L1 Same with reference1 inInit Payment request
reference2 String L1 Same with reference2 in Init Payment request
resultCode Number R L1 Payment Result code
paymentId Number R L1 Payment ID in MoMo
amount Number R L1 Payment amount
creditAmount Number R L1 Payment credit amount
encryptedData String R L1 All field's values will be encryted by SHA256.
Notes: all fields values are appended together without space.

The encryptedData is:

SHA256(
    <value_of_requestId_field>
    <value_of_reference1_field>
    <value_of_reference2_field>
    <value_of_resultCode_field>
    <value_of_paymentId_field>
    <value_of_amount_field>
    <value_of_creditAmount_field>
    <value_of_checksumKey_field>
)

4. Payment Notification

The following endpoint push the payment results to partner.

Partner returns the HTTP Status 200 to ensure received payment info.

SERVER CLIENT END POINT METHOD HEADERS
PARTNER MOMO notifyUrl in Init Payment request POST Content-Type application/pgp-encrypted
Accept application/pgp-encrypted

Sample

Sample Request

{
  "requestId": "2300699797",
  "referenceId": "REF1_EACTJNDPWP",
  "reference1": "REF1_EACTJNDPWP",
  "reference2": "REF2_WRATJNDPWP",
  "amount": 999000,
  "creditAmount": 0,
  "resultCode": 0,
  "resultMessage": "Success",
  "paymentId": 2300699797,
  "paymentDate": "2019-04-01T10:49:45+07:00",
  "paymentMillisTime": 1560233760000
}

Sample response

{
  "requestId": "2300699797",
  "resultCode": 0,
  "resultMessage": "Success",
  "referenceId": "MS_12375894762"
}

Attributes

Request Params

Name Type R L Description
requestId String(50) R L1 Unique String for each request
reference1 String(50) R L1 It depends on partner
reference2 String(50) L1 It depends on partner
amount Number R L1 Total paid amount
creditAmount Number R L1 Credit amount
resultCode Number R L1 Result of payment transaction
resultMessage String(50) L1 Result message, description for resultCode
paymentId Number R L1 Unique number for each payment request
paymentDate String(50) R L1 Payment date, format: YYYY-MM-DDThh:mm:ssTZD
paymentMillisTime Number R L1 UNIX time for payment date

Response Params

Name Type R L Description
requestId String(50) R L1 Same with request
referenceId String(50) R L1 Unique for each response
resultCode Number R L1 Result code, partner return it based on Result Code
resultMessage String(100) R L1 Result message

5. Result Code

Payment Gateway uses conventional MoMo result code to indicate the success or failure of an API request.

Code Result message API Description Status
0 SUCCESS All The request perform success Success
2 INVALID_ENCRYPT_DATA All Error when encrypt data Fail
4 INVALID_WALLET_ID PAYMENT-NOTIFY Fail
8 DUPLICATE_REQUEST_ID All The requestId field for each transaction is unique. Fail
9 INVALID_PARTNER_CODE All The partner-code in Request Header, MoMo will be provide. Fail
11 OTHER_ERROR All Error in Momo's system Fail
15 MAINTENANCE_SYSTEM INIT CHECK-INFO Mainternance system, please try later ! Fail
45 PENDING_TRANSACTION PAYMENT-NOTIFY CHECK-INFO Error when payment in MoMo app, the transaction is pending Pending
1001 INSUFFICIENT_FUNDS PAYMENT-NOTIFY CHECK-INFO Error when payment in MoMo app, the wallet is insufficient funds Fail
1004 WALLET_CAP_EXCEEDED PAYMENT-NOTIFY CHECK-INFO Error when payment in MoMo app, the wallet cap exceeded Fail
2001 INVALID_CLIENT INIT CHECK-INFO The client field invalid Fail
2002 INVALID_REFERENCE_1 INIT CHECK-INFO The reference1 field invalid Fail
2003 INVALID_REQUEST_ID INIT CHECK-INFO The requestId field invalid Fail
2004 INVALID_CHECKSUM_KEY INIT CHECK-INFO The checksumKey field invalid Fail
2005 INVALID_ACCOUNT_INFO INIT CHECK-INFO The accountInfo field invalid Fail
2006 INVALID_TOTAL_AMOUNT INIT CHECK-INFO PAYMENT The totalAmount value invalid Fail
2007 INVALID_BILL_TOTAL_AMOUNT INIT CHECK-INFO The totalAmount in bill info not equal totalAmount outside Fail
2008 INVALID_CHECK_REQUEST_ID CHECK-INFO The requestIdCheck field invalid Fail
2009 TRANSACTION_EXPIRED CHECK-INFO CALL-BACK The init transaction expired Fail
2010 TRANSACTION_NOT_FOUND CHECK-INFO The transaction not found Fail
2011 TRANSACTION_CANCELED_BY_USER CHECK-INFO The user cancel transaction in MoMo web Fail
2013 INVALID_BILL_INFO INIT Fail
2014 OVER_TRANS_IN_MONTHS INIT MoMo server check number trans in months Fail
2015 OVER_TRANS_IN_DAYS INIT MoMo server check number trans in days Fail

*Other error codes: System error -> Fail

5. FAQs (Frequently Asked Questions)

1. What is the flow of PGP Key?
There are 2 key pairs:
Partner: private and public
Momo: private and public

A. From partner, sending request to Momo side: 1. Init pgp with private_partner + public_momo 2. Encrypt and sign body request -> generate an encrypted request -> send to momo

B. Partner receive response from Momo: 1. Init pgp with private_partner + public_momo 2. Partner then decrypt and verify the encrypted response from Momo

2. Where can i get some PGP Key example code?
Java
Net
PHP
NodeJS


3. Where can i get the testing app of Momo?
Here
OTP and Pass:0000

4. How can i test fail case on Momo environment?
Login using this number: 01686026779 (Password:000000) and testing will only yield fail result

5. I already intergrated succesfully but one day error turned up? What should i do?
Contact us with the request ID that encounter error (Zalo,Skype,...)

6. Is reference_1 the same as bill_id?
Yes, as well as orderID

7. Where can we transfer more field?
In the extras field (note that it will not show to customer)

8. Why my "nội dung" (description) field show 'undefined' in momo app?
Make sure you fill in the "description" field, right below the notifyURL field, because it will be showed as description in momo app for customer.

9. Is callBack parameter "amount" mean user actual amount of payment?
Yes it is

10. When transaction state is pending as error code 45, do Momo side still send Payment Notification?
Yes we do

11. What is the connection details of Momo flow?
1. Partner call Momo with this endpoint: https://payment.momo.vn:22446/ -Public IP:118.69.212.158
2. Momo return Payment Notification with this public IP:118.69.210.244

12. If my system fail, will MoMo App only callback after my system return content, or it will not wait and callback directly?
Momo will try to wait for response 3 times if timeout, then proceed to callback no matter the result

13. My system received PAYMENT NOTIFY but encounter problems, so we don't want to debit money. What returnCode should we response to "MoMo Server" (returnCode=11 or returnCode=45), to make MoMoPay won't debit money?
In payment notify we just send result payment, so you cannot cancel debit money.

14. What is the Base URL during the integration process?
https://testing.momo.vn:22446 (UAT environment).

15. What is the value of partner-code in Header?
gwpayment

16. Should I use PGP Key-Pairs provided by MoMo or generate PGP Key-Pairs with Sample Codes?
Please use the pairs from the email, and the passphrase is: mservice

17. What should I fill in the value of checksumKey field in INIT PAYMENT?
Your choice