Skip to content

API Introduction

Last updated: 2023-01-08

Introduction

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

The MTPay API uses API keys to authenticate requests. You can view and manage your API keys in the 'Merchant Service' - 'API Token Management' section within our system.

Your API keys carry many privileges, so be sure to keep them secure. It is advised not to disclose your confidential API keys in publicly accessible domains, such as GitHub, client-side code, and similar platforms.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

To act as connected accounts, clients can issue requests using the blow special headers:

access_key

You can obtain the access_key and private_key information generated by the system. In this special HTTP header, what you need to pass in is the clear text of the access_key value.

timestamp

The value that needs to be entered is the UTC timestamp of the request, ensuring accuracy down to the millisecond.

signature

After you have obtained the access_key and secret_key, you need to compute this information using the HmacSHA256 algorithm:

{access_key}_{timestamp}

For instance, if your access_key is B6QKwx0NnKaQ14zf24Ux5Oc9Gy1xlf2R, secret_key is WUYx7DTQZakugtP9gOAimYUphcnc3jWuPRi1UVnWmwXSnMnsCVBzz1ILdaxisvz9, and the current time is 1625546438154. The data that needs to be calculated is:

B6QKwx0NnKaQ14zf24Ux5Oc9Gy1xlf2R_1625546438154

By employing the secret_key as the computed password for HmacSHA256, the resultant generated signature is the value of this item:

EDB15CF33C232128BDF118CEB147C453181939F8B37EC43886F68B3BCC2C19CD

Code example:

String originSignature = String.format("%s_%s", accessKey, timestamp);

Mac hashInstance = Mac.getInstance("HmacSHA256");
hashInstance.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"));

byte[] hash = hashInstance.doFinal(originSignature.getBytes());

String signature = DatatypeConverter.printHexBinary(hash);

Structures

When the API returns data in JSON encoding, the default response structure is:

{
  "data": {},
  "statusCode": "SUCCESS",
  "message": null,
  "success": true
}

data

Encoded response data is provided in generic type.

statusCode

  • SUCCESS: Request processed successfully.
  • TIMESTAMP_ERROR: Timestamp verification failed, please make sure the timestamp is passed in correctly.
  • SIGNATURE_ERROR: Signature verification failed. Please verify with the Authentication section. If the problem persists, please contact our support team for help.
  • ACCESS_KEY_ERROR: Wrong access_key provided.
  • PARAMETER_ERROR: Other parameters are incorrect.
  • ACCOUNT_STATUS_ERROR: Account status is abnormal.
  • SYSTEM_ERROR: System encountered an exception.
  • NO_ADVERTISEMENT: Deprecated.

message

The response message serves as an auxiliary means to identify the cause of positioning errors.

success

Whether the request has been successfully executed.