Please read Onboarding first!!

Overview

This document describes the API methods that partner uses to interact with the MoMo.

Web authentication flow

Mobile authentication flow

Unbind from Vendor flow

Unbind from MoMo flow

Using methods:

Authentication
Bind
Bind & Sale
Authorize / Sale
Capture
Rollback
Refund
Unbind
OTP

I - Authentication

1. Init authenticate

The following endpoint initiates an authentication.

SERVER	CLIENT	END POINT	METHOD	HEADERS
MOMO	PARTNER	/auth/v1/authenticate	POST	Reference to Headers

Sample Request

{
  "requestId": "UNIQUE_REQUEST_ID_wQbrU3t8Wye67g3yIi9k",
  "partnerClientId": "UNIQUE_PARTNER_CLIENT_ID_uewkjrhoi",
  "returnUrl": "https://momo.partner.com/callback",
  "notifyUrl": "https://momo.partner.com/notify",
  "amount": 30000
}

Sample Response

{
  "requestId": "UNIQUE_REQUEST_ID_wQbrU3t8Wye67g3yIi9k",
  "referenceId": "TRACE_ID_CJGvpInCyl",
  "resultCode": 0,
  "message": "Success",
  "localMessage": "Thành công",
  "data": {
    "payUrl": "https://payment.momo.vn/gw/authorize/qr?id=1947590028485",
    "qrCode": "https://payment.momo.vn/gw/authorize/s?id=1947590028485"
  }
}

Payload

Request Parameters

Name	Type	R	L	Description
requestId	String	x	L1	Unique identifier for each request
partnerClientId	String	x	L1	Unique user identifier like user id or email
returnUrl	String	x	L1	MoMo user will be redirect to this URL to get result 2. Callback
notifyUrl	String	x	L1	MoMo will invoke 3. Notification
amount	Integer		L1	Payment amount

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code. "0" means SUCCESS
message	String	x	L1	The result message
localMessage	String	x	L1	The result message, in Vietnamese
data	JsonObject	x	L1	Response data when resultCode is 0
payUrl	String	x	L2	This URL is used to redirect user to MoMo app/web to confirm binding
qrCode	String	x	L2	MoMo QR code to be displayed on partner site, which user can scan to open MoMo app and confirm binding

2. Callback

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

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

Sample request

https://momo.partner.com/callback?data=VGhpcyBpcyBzYW1wbGUgYmFzZWQ2NA==

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

{
  "requestId": "REQUEST_ID_1511347353577",
  "referenceId": "TRACE_ID_1511347353577",
  "resultCode": 0,
  "message": "Success",
  "localMessage": "Thành công",
  "sessionKey": "g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3",
  "signature": "B3ABE5D8C69B38733AD57EA75E83BCAE42BBBBAC75E3A5445862ED2F8A2CD677"
}

Query string with these parameters:

Name	Type	R	L	Description
requestId	String	x	L1	Same with requestId in [Init authenticate request]
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code
message	String	x	L1	The result message
localMessage	String	x	L1	The result message, in Vietnamese
sessionKey	String	x	L1	Session key, to be used to get Access token
signature	String	x	L1	All field's values will be encryted by SHA256. Notes: all fields values are appended together without space.

The signature is:

SHA256(
    <requestId>
    <referenceId>
    <resultCode>
    <message>
    <localMessage>
    <sessionKey>
    <checksumKey>
)

3. Notification

The following endpoint pushes the authentication result to partner.

Partner returns the HTTP Status 200 to signal that they received authentication info.

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

Sample Request

{
  "requestId": "REQUEST_ID_1511347353577",
  "referenceId": "TRACE_ID_1511347353577",
  "resultCode": 0,
  "message": "Success",
  "localMessage": "Thành công",
  "sessionKey": "g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3"
}

Sample response

{
  "requestId": "REQUEST_ID_1511347353577",
  "resultCode": 0,
  "message": "Success"
}

Payload

Request Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with requestId in Init Payment request
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code
message	String	x	L1	Result message
localMessage	String	x	L1	The result message, in Vietnamese
sessionKey	String	x	L1	Session key, to be used to get Access token

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
resultCode	Number	x	L1	Result code, partner return it based on Result Code
message	String(100)	x	L1	Result message

II - Bind

The following endpoint exchanges the Session Key for an Access Token

SERVER	CLIENT	END POINT	METHOD	HEADERS
MOMO	PARTNER	/auth/v1/associateAccount	POST	Reference to Headers

Sample Request

{
  "requestId": "REQUEST_ID_1511347353577",
  "sessionKey": "g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3",
  "partnerClientId": "UNIQUE_PARTNER_CLIENT_ID_uewkjrhoi"
}

Sample response

{
  "requestId": "REQUEST_ID_1511347353577",
  "referenceId": "TRACE_ID_1511347353577",
  "resultCode": 0,
  "message": "Success",
  "localMessage": "Thành công",
  "data": {
      "accessToken": "ACCESS_TOKEN_g98jhUYh3bGsyqaeWVdvfrwej",
      "maskWalletId": "******1714",
      "aliasWalletId": "78bs8sbs9e6aq93458vbw321z"
  }  
}

Payload

Request Params

Name	Type	R	L	Description
requestId	String	x	L1	Unique string for each request
sessionKey	String	x	L1	Session key, received from authenticate processor in previous step
partnerClientId	String	x	L1	Unique user identifier like user id or email

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code. "0" means SUCCESS
message	String	x	L1	Result message
localMessage	String	x	L1	The result message, in Vietnamese
data	JsonObject	x	L1	Response data when resultCode is 0
accessToken	String	x	L2	Token used to initiate purchases with the payment processor
maskWalletId	String	x	L2	MoMo masked wallet ID (only show last 4 digits)
aliasWalletId	String	x	L2	MoMo hash wallet ID

III - Bind & Sale

The following endpoint exchanges the Session Key for an Access Token and get (sale) money from MoMo wallet.

SERVER	CLIENT	END POINT	METHOD	HEADERS
MOMO	PARTNER	/auth/v1/associateAndSale	POST	Reference to Headers

Sample Request

{
  "requestId": "REQUEST_ID_1511347353577",
  "sessionKey": "g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3",
  "partnerClientId": "UNIQUE_PARTNER_CLIENT_ID_uewkjrhoi",
  "partnerRefId": "UNIQUE_PARTNER_REF_ID_o32ihkdsf",
  "amount": 50000
}

Sample response

{
  "requestId": "REQUEST_ID_1511347353577",
  "referenceId": "TRACE_ID_1511347353577",
  "resultCode": 0,
  "message": "Success",
  "localMessage": "Thành công",
  "data": {
      "accessToken": "ACCESS_TOKEN_g98jhUYh3bGsyqaeWVdvfrwej",
      "maskWalletId": "******1714",
      "aliasWalletId": "78bs8sbs9e6aq93458vbw321z"
  }  
}

Payload

Request Params

Name	Type	R	L	Description
requestId	String	x	L1	Unique string for each request
sessionKey	String	x	L1	Session key, received from authenticate processor in previous step
partnerClientId	String	x	L1	Unique user identifier like user id or email
partnerRefId	String	x	L1	Unique merchant payment transaction ID
amount	Integer	x	L1	Payment amount

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code
message	String	x	L1	Result message
localMessage	String	x	L1	The result message, in Vietnamese
data	JsonObject	x	L1	Response data when resultCode is 0
accessToken	String	x	L2	Token used to initiate purchases with the payment processor
maskWalletId	String	x	L2	MoMo masked wallet ID (only show last 4 digits)
aliasWalletId	String	x	L2	MoMo hash wallet ID

IV - Authorize / Sale

Partner either uses 1-step (Sale) or 2-step (Authorize + Capture) Flow

Authorize + Capture: Recommended for use cases where there is a delay between the time when user books a product/service and the time when the product/service is delivered, where partner might need to adjust the transaction amount or rollback the transaction. Example: delivery/ ride sharing service

Sale: Recommended for all other use cases

SERVER	CLIENT	END POINT	METHOD	HEADERS
MOMO	PARTNER	/pay/v1/authorize	POST	Reference to Headers
MOMO	PARTNER	/pay/v1/sale	POST	Reference to Headers

Sample Request

{
  "requestId": "REQUEST_ID_1511347353577",
  "partnerClientId": "UNIQUE_PARTNER_CLIENT_ID_uewkjrhoi",
  "partnerRefId": "UNIQUE_PARTNER_REF_ID_o32ihkdsf",
  "accessToken": "ACCESS_TOKEN_g98jhUYh3bGsyqaeWVdvfrwej",
  "amount": 50000,
  "description": "Thanh toán dịch vụ",
  "extraData": "Extra data"
}

Sample response

{
  "requestId": "REQUEST_ID_1511347353577",
  "referenceId": "TRACE_ID_1511347353577",
  "resultCode": 0,
  "message": "Success",
  "localMessage": "Thành công",
  "data": {
      "momoTransId": "15239559159890"
  }  
}

Payload

Request Params

Name	Type	R	L	Description
requestId	String	x	L1	Unique string for each request
partnerClientId	String	x	L1	Unique user identify likes user id or email
partnerRefId	String	x	L1	Unique merchant payment transaction ID
accessToken	String	x	L1	Token for payment
amount	Integer	x	L1	Payment amount in VND
description	String		L1	Description request
extraData	String(300)		L1	String contains extra data

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code
message	String	x	L1	Result message
localMessage	String	x	L1	The result message, in Vietnamese
data	JsonObject	x	L1	Response data when resultCode is 0
momoTransId	String	x	L2	MoMo transaction ID. Using for capture function or rollback function

V - Capture

The following endpoint allow partner get capture on MoMo wallet after invoke authorize function.

SERVER	CLIENT	END POINT	METHOD	HEADERS
MOMO	PARTNER	/pay/v1/capture	POST	Reference to Headers

Sample Request

{
  "requestId": "REQUEST_ID_1511347353577",
  "partnerClientId": "UNIQUE_PARTNER_CLIENT_ID_uewkjrhoi",
  "partnerRefId": "UNIQUE_PARTNER_REF_ID_o32ihkdsf",
  "accessToken": "ACCESS_TOKEN_g98jhUYh3bGsyqaeWVdvfrwej",
  "momoTransId": "15239559159890"

}

Sample response

{
  "requestId": "REQUEST_ID_1511347353577",
  "referenceId": "TRACE_ID_1511347353577",
  "resultCode": 0,
  "message": "Success",
  "localMessage": "Thành công",
  "data": {
      "acceptAmount": 50000
  }  
}

Payload

Request Params

Name	Type	R	L	Description
requestId	String	x	L1	Unique string for each request
partnerClientId	String	x	L1	Unique user identifier like user id or email
partnerRefId	String	x	L1	Unique merchant payment transaction ID
accessToken	String	x	L1	Token for payment
momoTransId	String	x	L1	Get from authorize

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code. "0" means SUCCESS
message	String	x	L1	Result message
localMessage	String	x	L1	The result message, in Vietnamese
data	JsonObject	x	L1	Response data when resultCode is 0
acceptAmount	String	x	L2	Payment amount in VND, which equals Authorize amount

VI - Rollback

The following endpoint allows partner to rollback the authorized function. If the transaction has already been captured, use Refund endpoint.

SERVER	CLIENT	END POINT	METHOD	HEADERS
MOMO	PARTNER	/pay/v1/rollback	POST	Reference to Headers

Sample Request

{
  "requestId": "REQUEST_ID_1511347353577",
  "partnerClientId": "UNIQUE_PARTNER_CLIENT_ID_uewkjrhoi",
  "partnerRefId": "UNIQUE_PARTNER_REF_ID_o32ihkdsf",
  "accessToken": "ACCESS_TOKEN_g98jhUYh3bGsyqaeWVdvfrwej",
  "momoTransId": "15239559159890"

}

Sample response

{
  "requestId": "REQUEST_ID_1511347353577",
  "referenceId": "TRACE_ID_1511347353577",
  "resultCode": 0,
  "message": "Success"
  "localMessage": "Thành công"
}

Payload

Request Params

Name	Type	R	L	Description
requestId	String	x	L1	Unique string for each request
partnerClientId	String	x	L1	Unique user identifier like user id or email
partnerRefId	String	x	L1	Unique merchant payment transaction ID
accessToken	String	x	L1	Token for payment
momoTransId	String	x	L1	Get from authorize

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code. "0" means SUCCESS
message	String	x	L1	Result message
localMessage	String	x	L1	The result message, in Vietnamese

VII - Refund

The following endpoint allow partner refund.

SERVER	CLIENT	END POINT	METHOD	HEADERS
MOMO	PARTNER	/pay/v1/refund	POST	Reference to Headers

Sample Request

{
  "requestId": "REQUEST_ID_1511347353577",
  "partnerClientId": "UNIQUE_PARTNER_CLIENT_ID_uewkjrhoi",
  "partnerRefId": "UNIQUE_PARTNER_REF_ID_o32ihkdsf",
  "accessToken": "ACCESS_TOKEN_g98jhUYh3bGsyqaeWVdvfrwej",
  "momoTransId": "15239559159890"  
}

Sample response

{
  "requestId": "REQUEST_ID_1511347353577",
  "referenceId": "TRACE_ID_1511347353577",
  "resultCode": 0,
  "message": "Success"
  "localMessage": "Thành công",
  "data": {
      "momoTransId": "152378372736472"
  }
}

Payload

Request Params

Name	Type	R	L	Description
requestId	String	x	L1	Unique string for each request
partnerClientId	String	x	L1	Unique user identifier like user id or email
partnerRefId	String	x	L1	Unique merchant payment transaction ID for refund
accessToken	String	x	L1	Token for payment
momoTransId	String	x	L1	Get from payment transaction

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code. "0" means SUCCESS
message	String	x	L1	Result message
localMessage	String	x	L1	The result message, in Vietnamese
data	JsonObject	x	L1	Response data when resultCode is 0
momoTransId	String	x	L2	Refund MoMo transaction ID

VIII - Unbind

1. Unbind from vendor

The following endpoint allow partner to delete an access token. Examples include: User deactivate account on Vendor’s system, user wants to remove binding with current MoMo wallet.

SERVER	CLIENT	END POINT	METHOD	HEADERS
MOMO	PARTNER	/auth/v1/unbind	POST	Reference to Headers

Sample Request

{
  "requestId": "REQUEST_ID_1511347353577",
  "partnerClientId": "UNIQUE_PARTNER_CLIENT_ID_uewkjrhoi",
  "accessToken": "ACCESS_TOKEN_g98jhUYh3bGsyqaeWVdvfrwej"  
}

Sample response

{
  "requestId": "REQUEST_ID_1511347353577",
  "referenceId": "TRACE_ID_1511347353577",
  "resultCode": 0,
  "message": "Success",
  "localMessage": "Thành công"
}

Payload

Request Params

Name	Type	R	L	Description
requestId	String	x	L1	Unique string for each request
partnerClientId	String	x	L1	Unique user identifier like user id or email
accessToken	String	x	L1	Token for payment

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code. "0" means SUCCESS
message	String	x	L1	Result message
localMessage	String	x	L1	The result message, in Vietnamese

2. Unbind from MoMo

MoMo server will send a notify Delete token to the Partner server with URL and body as below.

Partner returns the HTTP Status 200 to signal that they received delete token info.

SERVER	CLIENT	END POINT	METHOD	HEADERS
PARTNER	MOMO	`unbindUrl` in Partner server	POST	Reference to Headers

Sample Request

{
  "requestId": "REQUEST_ID_1511347353577",
  "partnerClientId": "UNIQUE_PARTNER_CLIENT_ID_uewkjrhoi"
}

Sample response

{
  "requestId": "REQUEST_ID_1511347353577",
  "resultCode": 0,
  "message": "Success",
  "localMessage": "Thành công"
}

Payload

Request Params

Name	Type	R	L	Description
requestId	String	x	L1	Unique string for each request
partnerClientId	String	x	L1	Unique user identifier like user id or email
accessToken	String	x	L1	Token for payment

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
resultCode	Number	x	L1	Response status. “0” means result is SUCCESS
message	String	x	L1	Result message
localMessage	String	x	L1	The result message, in Vietnamese

IX - OTP

Each recurring token is linked with only one MoMo user account. If partner detects suspicious / risky activities from user’s account and want to validate user’s identity: partner can request OTP to be sent from MoMo, display a screen for user to input the OTP, and validate this OTP with MoMo. Specific use cases recommended: - Request from untrusted device - User login from new device - Unusually high value payment - Unusually high purchase frequency - New shipping address

1. Send OTP

The following endpoint allows partner to request send OTP:

Can only send a limit number of sms per day, default is 5 sms/day and can config for each partner.
Delay time between 2 request is 3 seconds

SERVER	CLIENT	END POINT	METHOD	HEADERS
MOMO	PARTNER	/auth/v1/sendOtp	POST	Reference to Headers

Sample Request

{
  "requestId": "REQUEST_ID_1511347353577",
  "partnerClientId": "UNIQUE_PARTNER_CLIENT_ID_uewkjrhoi",
  "accessToken": "ACCESS_TOKEN_g98jhUYh3bGsyqaeWVdvfrwej",
  "language": "vi"  
}

Sample response

{
    "requestId": "REQUEST_ID_1511347353577",
    "referenceId": "TRACE_ID_1511347353577",
    "resultCode": 0,
    "message": "Success",
    "localMessage": "Thành công",
    "data": {
        "otpId" : "693184163549263518"
    }
}

Payload

Request Params

Name	Type	R	L	Description
requestId	String	x	L1	Unique string for each request
partnerClientId	String	x	L1	Unique user identify likes user id or email
accessToken	String	x	L1	Token for payment
language	String	x	L1	Language of OTP message sent to user. Current value allowed is `vi` or `en`. (Default is `vi`)

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code
message	String	x	L1	Result message
localMessage	String	x	L1	The result message, in Vietnamese
data	JsonObject	x	L1	Response data when resultCode is 0
otpId	String	x	L2	Id of OTP when send success. Will be use when call confirm

2. Confirm OTP

The following endpoint allows partner to request confirm OTP. Success response means the OTP user has input is correct:

Cannot send/request OTP until next day if user inputs the incorrect OTP 5 times
OTP expiration time is 5 minutes.

SERVER	CLIENT	END POINT	METHOD	HEADERS
MOMO	PARTNER	/auth/v1/confirmOtp	POST	Reference to Headers

Sample Request

{
  "requestId": "REQUEST_ID_1511347353577",
  "otpId": "693184163549263518",
  "otp": "464325"
}

Sample response

{
  "requestId": "REQUEST_ID_1511347353577",
  "referenceId": "TRACE_ID_1511347353577",
  "resultCode": 0,
  "message": "Success",
  "localMessage": "Thành công"
}

Payload

Request Params

Name	Type	R	L	Description
requestId	String	x	L1	Unique string for each request
otpId	String	x	L1	Identifier of the OTP that MoMo sent
otp	String	x	L1	The OTP that user input

Response Params

Name	Type	R	L	Description
requestId	String	x	L1	Same with request
referenceId	String	x	L1	Unique for each response
resultCode	Number	x	L1	Result code. "0" means SUCCESS
message	String	x	L1	Result message
localMessage	String	x	L1	The result message, in Vietnamese

Result Code

Code	Result message
0	SUCCESS
-1	Transaction initiate (init)
3	User/Agent not found
4	Agent not registered
5	Agent inactive
6	Agent suspended
14	Partner is not activated
36	Expired transaction
45	Request timeout
151	Amount not in range
153	Decrypt Hash data failed
208	Partner is not active/create
210	Check amount failed. The payment enable amount from %sđ up to %sđ.
403	Permission denied
404	Request not found
1001	Insufficient funds
1004	Wallet Cap Exceeded
1006	General system failure
2004	Access token invalid
2005	Token expired
2007	Capset per day limit
2101	User not login
2110	Confirm OTP wrong many times
2111	Request send OTP too fast
2113	Send OTP failed
2114	Send OTP request not found
2115	OTP expired. It cannot be confirmed
2116	OTP not match with any OTP
2118	OTP was used. Send another OTP request to renew.
2125	BillId can't refund.
2129	Check signature fail
2131	Bill not exists or expired
2132	Transaction has been processed
2137	Account has been linked with another MoMo account
2138	Data invalid
2146	Duplicate request
2400	Bad format data
9000	Transaction is processing
9043	User has not completed KYC requirement (map bank)