Integration Process

1. Convention

1.1. HTTP Status Code

Status Code	Description
200	Requests are received and processed successfully by the server. There might be a business-related issue which is clarified by status field in the response body.
400	Any issue related to input format and validation. Details is provided in the response body.
Other HTTP Status	See standard HTTP Status Code specification

1.2. HTTP Request Header

Property	Type	Required	Description
Authentication	String	Y (*)	The access token obtained in the login request. See Create access token API
Content-Type	String	Y	Application/JSON
X-Request-Id	String	Y	Unique for each request (UUID)

(*) This header is required for all requests except the login request.

1.3. HTTP Response Body

Following fields are always included in the response body of a request

Property	Type	Description
status	String	Specify any business related issue. See section 1.4 for more details
message	String	The description of the above status code

Example of a Successful Request

{
  "status": "SUCCESS",
  "message": "Thành công"
}

1.4. Common status codes

Status code	Description
SUCCESS	Request was processed successfully.
FAIL	Request was processed failed

1.5. Date time format

#	Format	Example
1	UNIX timestamp in millisecond	1649993539000

2. Authentication

Partner needs to be granted access to its merchants' data.

Overall

Partner uses provided clientId and clientSecret to get an access token (using the Create Access Token API) and pass the token as Bearer in the Authorization header of all subsequent requests. MoMo will throw errors for expired or invalid access tokens.

Create access token API

API to get an access token for subsequent API requests.

HTTP Request

POST <{Environment Domain}/authentication/login>

Request body

Field	Type	Description
clientId	String	The identifier provided by MoMo
clientSecret	String	The secret provided by MoMo

Example

{
  "clientId": "clientId",
  "clientSecret": "clientSecret"
}

HTTP Response

Field	Type	Description
status	String	See convention for common status code
message	String	The description of the above errorCode
data	Object	Described below

Describe data Model

Property	Type	Description
accessToken	String	The access token
expiresIn	Long	Expiration time in milliseconds. The default value is 86400000 (24 hours)

Example of a Successful Request

{
    "status": "SUCCESS",
    "message": "Thành công",
    "data": {
        "accessToken": "eYa...",
        "expiresIn": 86400000
    }
}

3. Environments and credentials

MoMo will provide the Partner with the following credentials. For each environment, the credentials will be different.

• Partner Id: Partner’s Id at MoMo side
• Client Id and Client Secret: used for authentication

MoMo provides two environments to integrate with the MoMo API:

1. UAT: used during the integration and testing process

• Domain: https://uat-business.momo.vn/api

2. Production: used to deploy to end-users

• Domain: https://business.momo.vn/api

The PartnerId, ClientId, and ClientSecret will be sent in a private channel.