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:

HTTP Request

POST /v2/gateway/api/create

Attribute	Type	Required	Description
partnerCode	String		Integration information
partnerName	String		Partner 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: 10.000 VND Max: 50.000.000 VND Currency: VND Data type: Long
orderId	String		OrderId of partner, unique for each request
orderInfo	String		Order's information
redirectUrl	String		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		initiate
userInfo	Object		Info of the customer
extraData	String		Default value is empty "" Encode base64 follow Jsonformat: {"key": "value"} Example with data: {"username": "momo"}=> data of extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0=
partnerClientId	String		Default 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
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 &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

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Same as the original request
orderId	String		OrderId of partner, unique for each request
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	Integer		Result Code
partnerClientId	String(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.
mToken	String		This 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 code	Description	Final Status	Recommended actions
0	Successful.	Yes
11	Permission denied.	No	Merchant settings issue. Please check your settings in M4B portal, or contact MoMo for configurations.
20	Bad format request	No	Please check the request format or any missing parameters.
41	Duplicated orderId.	No	Please inquiry the orderId's transaction status, or retry with a different orderId.
22	Invalid transaction amount.	No	Please check if the amount is within the allowed range of each payment method.