Skip to main content

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 mToken (used for simplifying other requests following this API).

API Configuration

API information to retrieve mToken:

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

HTTP Request

POST /v2/gateway/api/create

AttributeTypeRequiredDescription
partnerCodeStringIntegration information
partnerNameStringPartner name
storeIdStringStore ID
requestIdString(50)Request ID, unique for each request,
MoMo's partner uses the requestId field for idempotency control
amountLongAmount needs to be paid
Min: 10.000 VND
Max: 50.000.000 VND
Currency: VND
Data type: Long
orderIdStringOrderId of partner, unique for each request
orderInfoStringOrder's information
redirectUrlStringA partner's URL. This URL is used to redirect from MoMo page to partner's page after customer's payment.
Support: AppLink and WebLink
ipnUrlStringPartner API. Used by MoMo to submit payment results by IPN method (server-to-server) method
requestTypeStringinitiate
userInfoObjectInfo of the customer
extraDataStringDefault value is empty ""
Encode base64 follow Jsonformat: {"key": "value"}
Example with data: {"username": "momo"}=> data of extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0=
partnerClientIdStringDefault value is empty ""
Vendor’s unique identifier for each user (e.g.: user ID or email).
This ID will be linked with end-user’s MoMo account. Either partnerClientId is required when generateCardToken = true or generateCardToken will be ignore in Pay Transaction request
langStringLanguage of returned message (vi or en)
signatureStringSignature 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
&ipnUrl=$ipnUrl&orderId=$orderId&orderInfo=$orderInfo
&partnerClientId=$partnerClientId&partnerCode=
$partnerCode&redirectUrl=$redirectUrl&requestId=
$requestId&requestType=$requestType

Example Request

{
"partnerCode": "MOMO",
"partnerName" : "Test",
"storeId" : "MoMoTestStore",
"requestType": "initiate",
"partnerClientId": "abc@gmail.com",
"ipnUrl": "http://www.example.com",
"redirectUrl": "http://www.example.com",
"orderId": "6d0a1b10-b382-11e9-8fda-91fa25841420",
"amount": 100000,
"lang": "vi",
"orderInfo": "pay with MoMo ATM",
"requestId": "1666756278085id",
"extraData": "email=abc@gmail.com",
"signature": "5344e1f4244173fe0ba2b4c865881aad79b86beff8154b4f74f3b92634ffa711",
}

Example UserInfo

{
"name": "Nguyen Van A",
"phoneNumber": "0999888999",
"email": "email_add@domain.com",
}

Try yourself

HTTP Response
AttributeTypeRequiredDescription
partnerCodeStringIntegration information
requestIdStringSame as the original request
orderIdStringOrderId of partner, unique for each request
amountLongSame as the original payment amount
responseTimeLongTime to respond payment results to partner
Format: timestamp
messageStringError description, error language is based on lang
resultCodeIntegerResult Code
partnerClientIdString(50)Vendor’s unique identifier for each user (e.g.: user ID or email). This ID will be linked with end-user’s MoMo account.
mTokenStringThis is the unique transaction token. It's valid for a specific time depending on merchant's account setting

Example Response

{
"partnerCode": "MOMOIOLD20190129",
"orderId": "1666756278085:0123456778",
"requestId": "1666756278085id",
"amount": 100000,
"responseTime": 1666756278549,
"message": "Giao dịch thành công.",
"resultCode": 0,
"partnerClientId": "abc@gmail.com",
"mToken": "bd9ba8e038cda3cd87887bf3e9d9e258757a0d1333cbb68babbfd0e3"
}

Response Codes & Messages

Result codeDescriptionFinal StatusRecommended actions
0Successful.Yes
11Permission denied.NoMerchant settings issue. Please check your settings in M4B portal, or contact MoMo for configurations.
20Bad format requestNoPlease check the request format or any missing parameters.
41Duplicated orderId.NoPlease inquiry the orderId's transaction status, or retry with a different orderId.
22Invalid transaction amount.NoPlease check if the amount is within the allowed range of each payment method.