Account Binding

Recurring payments offers a one-click payment experience for your website or mobile app enabling payments via MoMo E-Wallet. Your customers need to once authorize and link their MoMo account with your application (binding) and later enjoy fast checkout every time.

Process Flow

Binding (and payment)

• URL can serve the dual purpose of account binding AND / OR request payment at the same time. If Merchant wants to bind account ONLY, amount (data field within URL) is set at 0 VNĐ; if Merchant wants to bind account AND request payment, amount is set at or greater than 1.000 VNĐ.
• URL's default expire time is 15 minutes, but can be customized for each Merchant.

Next payments using token

API Configuration

HTTP Information

Initiate binding method

HTTP Request

POST /v2/gateway/api/create

Attribute	Type	Required	Description
partnerCode	String(20)		Merchant ID 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		Order amount in VND (0 or greater)
orderId	String(50)		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
orderInfo	String(200)		Order info from merchant
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(200)		MoMo Payment will redirect end-user back to Vendor using this URL, to notify result for end-user using HTTP GET request type
ipnUrl	String(200)		MoMo Payment will notify this URL. Vendor server needs to build this URL to receive results sent from MoMo, using HTTP POST request type with header application/json.
partnerClientId	String		Vendor’s unique identifier for each user (e.g.: user ID or email). This ID will be linked with end-user’s MoMo account. Regex: ^[0-9a-zA-Z]([-_.@]*[0-9a-zA-Z]+)*$
extraData	String		Default value is empty "" Encode base64 follow Jsonformat: {"key": "value"} Example with data: {"username": "momo"}=> data of extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0=
requestType	String(20)		linkWallet
userInfo	Object		User Info Example Data: {"partnerClientAlias": "abc@gmail.com" }
lang	String(20)		Language return: vi or en
signature	String(65)		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

Data of userInfo

Attribute	Type	Required	Description
partnerClientAlias	String		An identifier of the user account (ex: phone number, email, name or nickname,..,), which will be displayed for user recognition during binding and checking payment history.

In addition, in case the merchant has a partnerClientId code that wants to link with multi MoMo wallets (rule 1: multi), the merchant can transmit additional code nxxx_partnerClientId with xxx being the link number. For example, for the first time binding for user A, merchant transmits n000_abc@gmail.com, and user A needs to binding for a second time, merchant will transmit n001_abc@gmail.com.

Example Request

{
  "partnerCode": "MOMOIQA420180417",
  "accessKey": "SvDmj2cOTYZmQQ3H",
  "requestId": "1516771499398",
  "amount": "0",
  "orderId": "1516771499398",
  "ipnUrl": "http://localhost:1001",
  "redirectUrl": "http://localhost:8081",
  "partnerClientId": "abc@gmail.com",
  "requestType": "linkWallet",
  "userInfo": {
    "partnerClientAlias": "abc@gmail.com"
  },
  "lang": "vi",
  "signature": "ca3c203f0c16873e688fada17…ee116b636ff407d6fe39"
}

HTTP Response

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Same as the original request
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
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.
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.
resultCode	int		Error code
message	String		Error description, error language is based on lang
responseTime	Long		Time to respond payment results to partner Format: timestamp
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.

Example Response

{
  "partnerCode": "MOMOIOLD20190129",
  "requestId": "1616577794003",
  "orderId": "1616577794003:0123456778",
  "amount": 10000,
  "responseTime": 1616577795018,
  "message": "Thành công",
  "resultCode": 0,
  "payUrl": "https://test-payment.momo.vn/gateway/pay?t=TU9NT...NTY3Nzg=",
  "qrCodeUrl": "https://test-payment.momo.vn/gateway/pay?t=TU9NT...NTY3Nzg=",
  "deeplink": "momo://?action=link&amount=1...25c&source=websdk&type=sale&v=1.1",
  "partnerClientId": "932024090117"
}

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
requestId	String		Each Request’s Identification
amount	Long		Amount to pay
orderId	String		Partner Transaction ID
orderType	String		momo_wallet
orderInfo	String		Order info
partnerClientId	String		Identifier of user
callbackToken	String		Token info used to get payment token
transId	Long		MoMo's transaction ID
resultCode	Integer		Order status
message	String		description of resultCode based on lang
payType	String		Payment Type: webApp, app,qror miniapp
responseTime	Long		Time to return payment result in miliseconds
extraData	String		Additional info
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&callbackToken= $callbackToken&extraData=$extraData&message=$message &orderId=$orderId&orderInfo=$orderInfo&orderType= $orderType&partnerClientId=$partnerClientId &partnerCode=$partnerCode&payType=$payType&requestId= $requestId&responseTime=$responseTime&resultCode= $resultCode&transId=$transId

The signature is encrypted using secretKey and accessKey, so you must keep it secret, not expose to any chat channels, or in source code, git, etc.

Receive recurring token

After receiving callbackToken from transaction result, merchant will send a request to MoMo to get user's token info

HTTP Request

POST /v2/gateway/api/tokenization/bind

Parameter	Type	Required	Description
partnerCode	String		Integration information
callbackToken	String		callbackToken as access token, received from payment result
requestId	String(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
orderId	String		Must match with the orderId when calling linkWallet
partnerClientId	String		Must match with the partnerClientId when calling linkWallet
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&callbackToken=$callbackToken&orderId= $orderId&partnerClientId=$partnerClientId&partnerCode= $partnerCode&requestId=$requestId

Example request

{
  "partnerCode": "MOMO_ATM_DEV",
  "requestId": "03dc5a00-b37c-11e9-b3a3-2f10f50d933d",
  "callbackToken": "v2/qml0PbOlrBYjFlZv…8StiawfZPiKoUGvywNHV",
  "orderId": "03dc32f0-b37c-11e9-b3a3-2f10f50d933d",
  "partnerClientId": "user@momo.vn",
  "signature": "fa8b66df31cc7045783323f1e4492d7b71c1de4c9e1b71002f95a1aa869e885a",
  "lang": "vi"
}

HTTP Response

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Each Request’s Identification
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$entification
aesToken	String		token object json encrypted using AES
resultCode	Integer		Order status
partnerClientId	String		Vendor’s unique identifier for each user (e.g.: user ID or email). This ID will be linked with end-user’s MoMo account
responseTime	Long		Time to respond payment results to partner Format: timestamp
message	String		Result description based on lang

Data of token after decrypted

Attribute	Type	Required	Description
value	String		Token Value using for pay token
userAlias	String		MoMo masked wallet ID (only show last 4 digits)
profileId	String		MoMo hash wallet ID

Example response

{
  "partnerCode": "MOMO_ATM_DEV",
  "requestId": "03dc5a00-b37c-11e9-b3a3-2f10f50d933d",
  "orderId": "03dc32f0-b37c-11e9-b3a3-2f10f50d933d",
  "partnerClientId": "user@momo.vn",
  "resultCode": 0,
  "responseTime": 145784525,
  "message": "Success",
  "aesToken": "NplHKEhGuFoo5o5vbMeJwrsk7wXEPnCjSZv6DgivW1a8JKw1gdXq2WS7UsPwoJv0yf6rbGiVV6nOKAxU8kTNg4SZraqJnf7GAq9OSE2LiNs="
}

After receiving aesToken from MoMo, Merchant server must decrypt aesToken to get real token and store it in the Merchant's system. Decrypting payment token by AES algorithm will require secret key, which can be found in https://business.momo.vn

For more information, see AES Encryption.

Pay using Token

HTTP Request

POST /v2/gateway/api/tokenization/pay

Parameter	Type	Required	Description
partnerCode	String		Integration information
partnerName	String		Partner name
storeId	String		Store ID
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$
amount	Long		Payment amountMin: 1.000 VND Payment amountMax: 30.000.000 VND Currency: VND.
requestId	String(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
token	String		Encrypt a object json by RSA using public Key RSA Encryption
partnerClientId	String		Merchant's unique user info
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.
redirectUrl	String		2in1 will be applied only when redirectUrl is available, in order to redirect back from MoMo to merchant page after user direct payment Supported: AppLink and WebLink.
ipnUrl	String		Merchant’s API Endpoint. 2in1 will be applied only when ipnUrl is available, in order to send payment results via IPN method after a user direct pament.
extraData	String		Default value is empty "" Encode base64 follow Jsonformat: {"key": "value"} Example with data: {"username": "momo"}=> data of extraData: eyJ1c2VybmFtZSI6ICJtb21vIn0=
userInfo	Object		User Info Example Data: `{"partnerClientAlias": "abc@gmail.com" }
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&partnerClientId= $partnerClientId&partnerCode=$partnerCode&requestId= $requestId&token=$token

Data of token before encrypted

Attribute	Type	Required	Description
value	String		Token Value as recurring token
requireSecurityCode	Boolean		- If set to false, the security code parameter is not used and payment will be directly sent to the payment provider. - If set to true, it means that you detect suspicious / risky activities from user’s account and request to validate user’s identity before payment. MoMo will help to make two-factor authentication (such as OTP,...). In this case, MoMo responses result code 8200, which means "waiting for 2FA confirmation". A call for Two-factor Authentication Confirmation from your site will be needed to process payment.

Data of userInfo

Attribute	Type	Required	Description
partnerClientAlias	String		An identifier of the user account (ex: phone number, email, name or nickname,..,), which will be displayed for user recognition during binding and checking payment history.

In addition, in case the merchant has a partnerClientId code that wants to link with multi MoMo wallets (rule 1: multi), the merchant can transmit additional code nxxx_partnerClientId with xxx being the link number. For example, for the first time binding for user A, merchant transmits n000_abc@gmail.com, and user A needs to binding for a second time, merchant will transmit n001_abc@gmail.com.

Example request

{
    "token": "sa5s4a54s5a4s5a4s5",
    "partnerCode": "MOMO_ATM_DEV",
    "partnerName": "Test",
    "storeId": "MoMo test store",
    "ipnUrl": "abc.com",
    "redirectUrl": "abc.com",
    "orderId": "12545465654656",
    "amount": "20000",
    "lang": "vi",
    "autoCapture": true,
    "orderInfo": "Thanh toan MoMo",
    "requestId": "365656d56sd",
    "extraData": "",
    "partnerClientId": "test@momo.vn",
    "signature": "2512s1d2s1ds21d2s1d1ce5d1a251#@"
}

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		Amount to pay
transId	Long		MoMo's transaction ID
responseTime	Long		Time to respond payment results to partner Format: timestamp
partnerClientId	String		Vendor’s unique identifier for each user (e.g.: user ID or email). This ID will be linked with end-user’s MoMo account.
resultCode	Integer		Order status
message	String		Result description, language is based on lang
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.
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.

Example response

{
  "partnerCode": "MOMO_ATM_DEV",
  "requestId": "1599645548172",
  "orderId": "1599645548172:0123456778",
  "amount": 50000,
  "responseTime": 145758545,
  "partnerClientId": "user@momo.vn",
  "resultCode": 0,
  "message": "Success"
}

• If you receive resultCode 8000, payUrl and deeplink are supported in order to redirect user to the payment provider for re-authorizing (user direct payment).
  
• If you receive resultCode 8200, a call for Two-factor Authentication Confirmation from your site will be needed to process payment.

Two-factor authentication confirm

After receiving 8200 for Pay using token request, you need to send a Two-factor authentication Confirm to ask for processing payment. This request includes the securityCode recorded from user (ex: OTP inputted by user from your interface). Success response means the securityCode is correct, two-factor authentication is passed and payment using token will be processed.

Rules for securityCode

• You can only request a limited number of SMS per user per day. The default limit is 5 SMS/user/day, and can be changed for each Merchant. Delay time between 2 continuous requests is 3 seconds.
  
• Merchant cannot request to send/confirm securityCode for a user’s account until next day if the Merchant has sent 5 wrong confirm securityCode request for that user in a round.
• Expiring time for each securityCode is 5 minutes.

HTTP Request

POST /v2/gateway/api/tokenization/verify

Parameter	Type	Required	Description
partnerCode	String		Integration information
orderId	String		Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$ Must be orderId with pay token
requestId	String(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
securityCode	String		securityCode that Merchant’s system recorded from user’s input
token	String		Encrypt a object json by RSA using public Key RSA Encryption
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&partnerClientId= $partnerClientId&partnerCode=$partnerCode&requestId= $requestId&token=$token

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		Amount to pay
transId	Long		MoMo's transaction ID
responseTime	Long		Time to respond payment results to partner Format: timestamp
partnerClientId	String		Vendor’s unique identifier for each user (e.g.: user ID or email). This ID will be linked with end-user’s MoMo account.
resultCode	Integer		Order status
message	String		Result description, language is based on lang
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.
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.

Delete token

Merchant can request to delete token

HTTP Request

POST /v2/gateway/api/tokenization/delete

Parameter	Type	Required	Description
partnerCode	String		Integration information
requestId	String(50)		Request ID, unique for each request, MoMo's partner uses the requestId field for idempotency control
orderId	String		OrderId of partner, unique for each request
storeId	String		store Identification
token	String		Encrypt a object json by RSA using public Key RSA Encryption
partnerClientId	String		Merchant's unique user info
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&orderId=$orderId&partnerClientId= $partnerClientId&partnerCode=$partnerCode&requestId= $requestId&token=$token

Example request

{
  "partnerCode": "MOMO_ATM_DEV",
  "requestId": "15454561",
  "orderId": "sa1s5a1",
  "lang":  "en",
  "partnerClientId": "test@momo.vn",
  "token": "sa1a25s1a21s2a1asasa21s2a1s2",
  "signature": "xmznmznxkakajdkkcbkscbkbcs@#dczcxz"
}

HTTP Response

Attribute	Type	Required	Description
partnerCode	String		Integration information
requestId	String		Each Request’s Identification
message	String		Result description, language is based on lang
resultCode	Integer		Order status
partnerClientId	String		Merchant's unique user info
responseTime	Long		Time to respond payment results to partner Format: timestamp

Example response

{
  "partnerCode": "MOMO_ATM_DEV",
  "orderId": "1600838954650:0123456778",
  "requestId": "1600838954650",
  "resultCode": 0,
  "message": "Success",
  "partnerClientId": "test@momo.vn",
  "responseTime": 14548754653232
}

Unbind

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

MoMo also allowed to unbind (token to be provoked) from MoMo App

Merchant have to provide the endpoint to receive notify unbind sent from MoMo, using HTTP POST

HTTP Request

Attribute	Type	Required	Description
partnerCode	String		Merchant ID
requestId	String		Unique ID for each request
orderId	String		OrderId of MoMo, unique for each request
requestType	String		unbind
partnerClientId	String		Vendor’s unique identifier of each user (e.g.: user ID or email) that linked with MoMo wallet
tokenType	String		wallet
signature	String		Signature to confirm information. Secure transaction in Hmac_SHA256  algorithm with format accessKey=$accessKey&orderId=$orderId&partnerClientId=$partnerClientId &partnerCode=$partnerCode&requestId=$requestId &requestType=$requestType&tokenType=$tokenType

Example

{
    "partnerCode": "MOMOIQA420180417",
    "requestId": "0e0ceb2a-ea06-4ca7-b63a-e5c8948a5bfc",
    "orderId": "012457855:231454545",
    "partnerClientId": "sangle@mservice.com.vn",
    "requestType": "unbind",
    "tokenType": "wallet",
    "signature": "bd4df3f3bad6815a9a7be1f1f5c8576f3f97eab25327247425f12a3fb4a78873"
}

You need to respond with HTTP code 204 (No Content)!

callbackToken inquiry

Vendor system cannot receive or record callbackToken, Vendor can request MoMo Payment to query callbackToken. Note that callbackToken has a default expire date of 10 minutes, counting from the time it is generated.

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

HTTP Request

POST /v2/gateway/api/tokenization/cbQuery

Attribute	Type	Required	Description
partnerCode	String		Merchant ID
requestId	String		Request ID, unique for each request
orderId	String		It must be matched with orderId used in linkWallet
partnerClientId	String		It must be matched with partnerClientId used in linkWallet
lang	String		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&orderId=$orderId &partnerClientId=$partnerClientId&partnerCode=$partnerCode &requestId=$requestId

Example

{
  "partnerCode": "123456",
  "requestId": "1527246504579",
  "orderId": "1527246478428",
  "partnerClientId": "MoMoAccountTest",
  "lang": "vi",
  "signature": "13be80957a5ee32107198920fa26aa85a4ca238a29f46e292e8c33dd9186142a"
}

HTTP Response

Attribute	Type	Description
partnerCode	String	Merchant ID
requestId	String	Request ID, unique for each request
orderId	String	Partner Transaction ID Regex: ^[0-9a-zA-Z]([-_.]*[0-9a-zA-Z]+)*$, stored on MoMo payment system
callbackToken	String	The callback token generated by MoMo.
resultCode	int	Result code
message	String	Description regarding result code, based on lang
responseTime	long	Response time

Example

{
  "partnerCode": "123456",
  "requestId": "1527246504579",
  "orderId": "1527246478428",
  "callbackToken ": "u7YYQZnAbLQivB0p5SHT9LIhjshqarXyobE_WzCCa4vDt58r",
  "resultCode": 0,
  "message": "Success",
  "responseTime": 127264428
}

Result Codes & Messages

These result codes and messages are exclusively assigned for the Account Binding flow within Tokenization Payments. Additionally, kindly locate other result codes and messages in the comprehensive list of result codes provided here.

Result code	Description	Final Status	Recommended actions	Type
0	Successful.	Yes
2001	Transaction failed due to invalid token.	Yes	The token has been deleted, please update accordingly.	Merchant error
2007	Transaction failed due to inactive token.	Yes	The token is inactive due to user decided to temporary lock the binding.	User error
2012	Request rejected due to invalid token.	Yes	The token does not exist or has been deleted. Token status can not be updated.	Merchant error
3001	Binding failed because user has denied to confirm the authorization.	Yes		User error
3002	Binding rejected due to authorization restrictions.	Yes	Please contact MoMo for the restriction details.	System error
3003	Unbinding rejected due to authorization restrictions.	Yes	Please contact MoMo for the restriction details.	System error
3004	Token cannot be provoked due to pending transactions.	Yes	Please contact MoMo for the restriction details.	System error
8000	Transaction is pre-authorized, waiting for user confirmation.	No	Please wait for the user to confirm the payment for the transaction to be authorized.	System error
9000	Transaction is authorized successfully.	No	For 1-step payment, please mark this transaction as success. For 2-step payment, please proceed with either capture or cancel request. For binding, please proceed to request the recurring token.	Pending

See also

• Check Transaction Status
• Reverse & Refund
• Confirm Payment