Introduction¶

Summary¶

The MTPay API is organized and managed based on the REST architectural style. Our API features predictable resource-oriented URLs, accepts JSON-encoded requests, returns JSON-encoded responses, and utilizes standard HTTP response codes, authentication, and verbs.

If you require access to the MTPay API in a testing environment, kindly reach out to our customer service team. We will gladly assist you in setting up a sandbox environment specifically designed for testing purposes.

As we release new versions and customized functionalities, we strive to maintain backward compatibility with the API.

Please log in to the backend system to view your API key and associated data.

Authentication¶

All requests to the MTPay API must be authenticated using API keys. These keys are generated and managed through the Merchant Service > API Token Management section of your account dashboard.

⚠️ Security Notice: API keys grant privileged access to your account. Keep them confidential and never expose them in public repositories ( e.g., GitHub), client-side code, or any untrusted environment.

HTTPS Requirement¶

All API requests must be sent over HTTPS.

Authentication Headers¶

Each API request must include the following HTTP headers:

Header	Description
access_key	Your unique access key in plain text as provided by the system.
timestamp	Current UTC timestamp in milliseconds (epoch time).
signature	A HMAC-SHA256 signature generated using your secret key and request metadata.

Signature Generation¶

To generate the signature, follow these steps:

Concatenate the access key and timestamp using an underscore _: {access_key}_{timestamp}
Compute the HMAC-SHA256 hash of the above string using your secret_key as the secret.
Convert the result into a hexadecimal string (uppercase) — this is your final signature.

Example¶

access_key: B6QKwx0NnKaQ14zf24Ux5Oc9Gy1xlf2R
secret_key: WUYx7DTQZakugtP9gOAimYUphcnc3jWuPRi1UVnWmwXSnMnsCVBzz1ILdaxisvz9
timestamp: 1625546438154

Step-by-step¶

Concatenate:

B6QKwx0NnKaQ14zf24Ux5Oc9Gy1xlf2R_1625546438154

Compute HMAC-SHA256 with the secret_key:

EDB15CF33C232128BDF118CEB147C453181939F8B37EC43886F68B3BCC2C19CD

Response Structure¶

All API responses follow a unified structure for consistency and ease of integration.

Response Format¶

{
  "data": {
    /* response payload */
  },
  "isSuccess": true,
  "statusCode": "SUCCESS",
  "message": "",
  "version": "2.0"
}

Field Descriptions¶

Field	Type	Description
data	`Object` / null	Response payload of generic type T.
isSuccess	`Boolean`	Indicates whether the request was successful.
statusCode	`APIResponseCode`	Enum value indicating the result of the request.
message	`String`	Description of the result or error message.
version	`String`	API version identifier. Default value: "2.0".

`APIResponseCode` Enum¶

Code	Description
SUCCESS	Request completed successfully.
ACCESS_KEY_ERROR	Invalid or missing accessKey.
ACCOUNT_STATUS_ERROR	Account is suspended or disabled.
SIGNATURE_ERROR	Signature verification failed.
TIMESTAMP_ERROR	Request timestamp is invalid or expired.
PARAMETER_ERROR	One or more request parameters are incorrect or missing.
SYSTEM_ERROR	Internal system error. Please try again later.

Example - Successful Response¶

{
  "data": {
    "orderId": "ORD-20250317-0001",
    "status": "PENDING"
  },
  "isSuccess": true,
  "statusCode": "SUCCESS",
  "message": "",
  "version": "2.0"
}

Example - Failed Response¶

{
  "data": null,
  "isSuccess": false,
  "statusCode": "PARAMETER_ERROR",
  "message": "Missing required parameter: amount.",
  "version": "2.0"
}