The following specifies the rules for calling the API when a merchant accesses Trusty open platform：

Security Specifications

General steps to create a signature:

Step 1:

Presume all data sent and received is the set M. Sort non-empty values in M in ascending alphabetical order (i.e., lexicographical sequence), and join them into string A via the corresponding URL key-value format (e.g., key1=value1& key2=value2…).

Step 2:

Add "key= (API key value) to the end of stringA to get stringSignTemp, perform MD5 arithmetic on stringSignTemp, convert all result chars to upper case, thus get sign's value (signValue).

For the following transferred parameters:

{
  "body": "testbody",
  "appNo": "zav3pgg7rafzcxa0",
  "ddName": "testddd"
}
            

• Sort ASCII code of parameter names by lexicographical sequence based on the format of "key=value":

  
  String stringA ="appNo=zav3pgg7rafzcxa0&body=testbody&ddName=testddd";
                      

• Join API Key

  Add "key= (API key value) to the end of stringA to get stringSignTemp, perform MD5 arithmetic on stringSignTemp, convert all result chars to upper case, thus get sign's value (signValue)

  
  //Note：The key is created by Trusty Open Platform for the merchant.
  String stringSignTemp = stringA + "&key=192006250b4c09247ec02edce69f6a2d"
  //Note:Signature Algorithm
  //default:MD5
  String sign = MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"
  Or
  //Note:HMAC-SHA256
  String sign= HMACSHA256(stringSignTemp,key).toUpperCase()="6A9AE1657590FD6257D693A078E1C3E4BB6BA4DC30B23E0EE2496E54170DACD6"
                      

Signature sample code

  /**
     * Create MD5
     *
     * @param data to be handle
     * @return MD5 result
     */
    public static String MD5(String data) throws Exception {
        java.security.MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] array = md.digest(data.getBytes("UTF-8"));
        StringBuilder sb = new StringBuilder();
        for (byte item : array) {
            sb.append(Integer.toHexString((item & 0xFF) | 0x100).substring(1, 3));
        }
        return sb.toString().toUpperCase();
    }

    /**
     * Create HMACSHA256
     *
     * @param data data to be handle
     * @param key
     * @return HA256 Result
     * @throws Exception
     */
    public static String HMACSHA256(String data, String key) throws Exception {
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(key.getBytes("UTF-8"), "HmacSHA256");
        sha256_HMAC.init(secret_key);
        byte[] array = sha256_HMAC.doFinal(data.getBytes("UTF-8"));
        StringBuilder sb = new StringBuilder();
        for (byte item : array) {
            sb.append(Integer.toHexString((item & 0xFF) | 0x100).substring(1, 3));
        }
        return sb.toString().toUpperCase();
    }


            

Get the final data to be sent:

{
  "nonce_str": "VMBTKNGu0r8nxrtpY8auCrEJcTYYrD9V",
  "mchnt_id": "1000",
  "sign": "E7EB3EFFEF4DE0D2BC63E00E08516D74",
  "app_id": "zav3pgg7rafzcxa0",
  "body": "testbody",
  "appNo": "zav3pgg7rafzcxa0",
  "ddName": "testddd"
}

            

Random String Algorithm

nonce_str is included in Trusty payment API protocols to ensure unpredictability for signatures. We suggest calling the random() function to create a signature and convert its value into a string.

Public request parameter

Public response parameter

Merchant’s backend calls this API to create an advance transaction in the Trusty payment service backend, and initiates the payment process via payment by appUrl.

1. Place an order:

Submit a pre-order request for payment by scanning code through this interface.
If payments made on websites, physical stores, media advertising, or other scenarios. obtain the appUrl corresponding to the QR code. The merchant's background system will generate the QR code image based on the appUrl value, and the user will initiate payment after scanning the code with Trusty App.
If in Merchant’s App, Open appUrl directly. Customer will be redirected to the Trusty App for payment.

2. Query:

The merchant is required to take the initiative to check the order status after placing an order for a certain period of time. If the notifyUrl notification address is configured, the payment result will be notified to the merchant backend interface through the HTTP protocol after the customer makes a successful payment.Then modify the order status. If you do not have a notification API or have not received the payment result, you can use the query API to query the payment result.

API Description: Unified Order API

Request URL:/openapi/v1/trusty/unifiedorder

Request Method：POST

consumes:["application/json"]

produces:["*/*"]

Request Parameter：

Field Name	Description	Required	Type	Length
app_id	Public Parameter	true	string	64
mchnt_id	Public Parameter	true	string	32
nonce_str	Public Parameter	true	string	64
sign	Public Parameter	true	string	128
sign_type	Public Parameter	true	string	12
tradeNo	The unique No. of the payment transaction which is provided by merchant.	true	string	32
attach	attach data: merchants can define the data by self.	false	string	500
body	Product name or payment brief description	true	string	128
detail	Detail information of products	false	string	128
deviceInfo	Device No.[Define by the merchant, example: the store NO.]	false	string	128
notifyUrl	The callback address to receive Trusty Pay result notifications asynchronously. The notification URL must be accessible by external networks, and is not allowed to carry any parameters. Use the HTTPS protocol URL. Example: https://www.trusty-pay.com/trustypay/pay.	false	string	128
frontendUrl	Specifies the callback address for receiving Trusty payment notifications. Format:your_app_scheme://your_app_host Example: merchant-app://trustypay/payresult. Create Deep Links to App Content: https://developer.android.com/training/app-links/deep-linking?hl=en	false	string	128
spbillCreateIp	IP address of terminal	false	string	64
timeExpire	Set the timeout period to set the number of minutes after which the order will be automatically cancelled. Default: 30 minutes	false	string	5
totalAmount	amount,For example: 1 MMK Format：100	true	String	20
tradeType	[ [Reference to the appendix] Trade type] Set to NATIVE, or APP	true	string	12
trnCcy	Currency [Reference to the appendix]	true	string	12
version	Fixed value: 1.0 Example：1.0	false	string	12

Request Sample：

{
    "app_id": "121775250444445490",
    "mchnt_id": "1000",
    "nonce_str": "121775250444445490",
    "sign": "xxxxxx",
    "sign_type": "MD5",
    "attach": "attach data: merchants can define the data by self.，XXX",
    "body": "Ipadmini16G white",
    "detail": "",
    "deviceInfo": "013467007045764",
    "notifyUrl": "http://www.google.com/",
    "frontendUrl":"your_app_scheme://your_app_host",
    "tradeNo": "P8888888888",
    "spbillCreateIp": "127.0.0.1",
    "timeExpire": "30",
    "totalAmount": "10000",
    "tradeType": "NATIVE",
    "trnCcy": "MMK",
    "version": "1.0"
}

Response Parameter:

Field Name	Description	Required	Type	Length
app_id	Public Parameter	true	string	64
mchnt_id	Public Parameter	true	string	32
nonce_str	Public Parameter	true	string	64
sign	Public Parameter	true	string	128
sign_type	Public Parameter	true	string	12
return_code	Public Parameter	true	string	32
return_msg	Public Parameter	true	string	128
tradeNo	The unique No. of the payment transaction which is provided by merchant.	true	string	32
applyNo	Specifies the advance transaction ID created by Trusty. It is used to call the Trusty Payment API later. Example: ty2021102720093950.	true	string	32
tradeType	The transaction type submitted. The value could be NATIVE, or APP. Example: APP	true	string	12
appUrl	The URL of opening the Trusty APP.	true	string	128

Response Sample：

xxxxxxxxxx
{
    "mchnt_id": "1003",
    "app_id": "vth8f3uvb5d8devq",
    "nonce_str": "ZvKdOf4civQ6NHZhI3cZyoCGUuOUjdyb",
    "sign": "A18EB41E3E92B361A12241D1F16B0966",
    "return_code": "SUCCESS",
    "return_msg": "",
    "body": "Ipadmini256G",
    "applyNo": "9c622f92364d48f484de2fc215a4b5d3",
    "tradeNo": "P888888888888121221",
    "appUrl": "MMQR Code string...",
    "tradeType": "NATIVE"
}

Return Code

code	Description
SUCCESS	Processed successfully
PARAM_ERROR	Parameter error.
MERCHANT_NOT_EXIST	Merchant does not exist.
SIGN_ERROR	Incorrect signature result.
ORDER_ALREADY_EXIST	Order already exists.
SYSTEM_ERROR	System error.

 

 

API Description: Inquire the Pay and Refund result

Request URL:/openapi/v1/trusty/query

Request Method：POST

consumes:["application/json"]

produces:["*/*"]

Request Parameter:

Field Name	Description	Required	Type	Length
app_id	Public Parameter	true	string	64
mchnt_id	Public Parameter	true	string	32
nonce_str	Public Parameter	true	string	64
sign	Public Parameter	true	string	128
sign_type	Public Parameter	true	string	12
tradeNo	Use the returned 'tradeNo' to inquire the payment order, and use the returned 'refundNo' to inquire the refund order.	true	string	32

Request Sample：

xxxxxxxxxx
{
    "app_id": "121775250444445490",
    "mchnt_id": "1000",
    "nonce_str": "121775250444445490",
    "sign": "xxxxxx",
    "sign_type": "MD5",
    "tradeNo": "P8888888888"
}

Response Parameter:

Field Name	Description	Type	Length
app_id	Public Parameter	string	64
mchnt_id	Public Parameter	string	32
nonce_str	Public Parameter	string	64
sign	Public Parameter	string	128
sign_type	Public Parameter	string	12
return_code	Public Parameter	string	12
return_msg	Public Parameter	string	128
applyNo	Specifies the advance transaction ID created by Trusty. It is used to call the Trusty Payment API later. Example: ty2021102720093950.	string	32
tradeNo	Unique trade NO. which is provided by merchant.	string	32
openId	Unique user ID under the merchant	string	32
orderAmt	Order amount , For example: 1 MMK Format：100	string	20
actualAmt	Actual amount , For example: 1 MMK Format：100	string	20
body	Product name or payment brief description	string	128
attach	attach data: merchants can define the data by self.	string	256
detail	Detail information of the product	string	256
currency	Currency	string	MMK
deviceInfo	Device No.	string	128
payStartDate	Payment Start Time : yyyy/MM/dd HH:mm:ss	string
payEndDate	Payment End Time:yyyy/MM/dd HH:mm:ss	string
payMsg	Payment Return Message	string	128
payStatus	Payment status [Reference to the appendix - payment status]	string	12
refundDate	Refund time : yyyy/MM/dd HH:mm:ss	string
refundNo	Refund No.	string	32
timeExpire	timeExpire	string	32
tradeType	[Reference to the appendix - Trade Type]	string	12
errCode	If payStatus is PAY_FAIL, [Reference to the appendix - ErrCode]	string	12

Response Sample：

xxxxxxxxxx
{
    "app_id": "121775250444445490",
    "sign": "xxxxxx",
    "sign_type": "MD5",
    "nonce_str": "121775250444445490",
    "mchnt_id": "1000",
    "return_code":"SUCCESS",
    "return_msg":"",
    "openId": "P454545454",
    "actualAmt": 888,
    "attach": "",
    "body": "topup 1000 MMK",
    "channel": "mpuapy",
    "currency": "MMK",
    "detail": "",
    "deviceInfo": "",
    "payMsg": "余额不足",
    "payStartDate": "",
    "payStatus": "PAY_FAIL",
    "errCode":"ERR99999",
    "refundDate": "",
    "refundNo": "",
    "spbillCreateIp": "",
    "timeExpire": "30",
    "orderAmt": 888,
    "applyNo": "xxsswww",
    "tradeNo": "xxxxx",
    "tradeType": "APP"
}

Return Code

code	Description
SUCCESS	Processed successfully
PARAM_ERROR	Parameter error.
MERCHANT_NOT_EXIST	Merchant does not exist.
SIGN_ERROR	Incorrect signature result.
ORDER_NOT_EXIST	This order does not exist.
SYSTEM_ERROR	System error.

 

API Description: Refund API

Request URL:/openapi/v1/trusty/refund

Request Method：POST

consumes:["application/json"]

produces:["*/*"]

 

Request Parameter：

Field Name	Description	Length	Required	Type
app_id	Public Parameter	64	true	string
mchnt_id	Public Parameter	32	true	string
nonce_str	Public Parameter	64	true	string
sign	Public Parameter	128	true	string
sign_type	Public Parameter	12	true	string
tradeNo	The unique No. of the payment transaction which is provided by merchant.	32	true	string
refundNo	The unique sequence No. of the refund transaction which is provided by merchant.	32	true	string

Request Sample：

xxxxxxxxxx
{
    "app_id": "121775250444445490",
    "mchnt_id": "1000",
    "nonce_str": "121775250444445490"
    "sign": "xxxxxx",
    "sign_type": "MD5",
    "tradeNo": "P8888888881",
    "refundNo": "P88888888882"
    
}

Response Parameter：

Field Name	Description	Required	Type
app_id	Public Parameter	true	string
mchnt_id	Public Parameter	true	string
nonce_str	Public Parameter	true	string
sign	Public Parameter	true	string
sign_type	Public Parameter	true	string
return_code	Public Parameter	true	string
return_msg	Public Parameter	true	string
refundStatus	Refund status [Reference to the appendix - Refund Status]	true	string
refundNo	The unique sequence No. of the refund transaction.	true	string

Response Sample:

xxxxxxxxxx
{
    "app_id": "121775250444445490",
    "sign": "xxxxxx",
    "sign_type": "MD5",
    "nonce_str": "121775250444445490",
    "mchnt_id": "1000",
    "return_code": "SUCCESS",
    "return_msg": "",
    "refundNo": "xxxxsdsdwewewew",
    "refundStatus": "REFUND_PROCESSING"
}

Return Code:

code	Description
SUCCESS	Processed successfully
PARAM_ERROR	Parameter error.
MERCHANT_NOT_EXIST	Merchant does not exist.
SIGN_ERROR	Incorrect signature result.
ORDER_NOT_EXIST	This order does not exist.
SYSTEM_ERROR	System error.
CHANNEL_NOT_ALLOWED	Channel does not allow refund.
ORDER_NOT_ALLOWED	Order does not allow refund.

Refund Status:

code	Description
REFUND_SUCCESS	refund success
REFUND_FAIL	refund fail.
REFUND_PROCESSING	refund processing.

 

After completing pay or refund, the Trusty payment system will send the refund result to the Merchant.

API intro

Request URL: The URL is set by the parameter notify_url submitted in 【Unified Order】and the https protocol is required. If the URL cannot be accessed, the merchant will not receive any Trusty notifications. The URL must be directly accessible without any parameters. For example: notify_url: http://openapi.merchart.com/trusty/callback

Notification Rules

After the payment or refund status changes, Trusty will send the refund results to the merchant.

When notifying the interaction to the backend, if the response received by Trusty is unsuccessful or timeout,Trusty will no longer be notified. the merchant need to call the 【Query Order API】to confirm the order status.

Notification Message

For payment or refund result notifications, access the notification URL set up by the merchant with the `POST` method, and the notification data is transmitted through the request body (BODY) in the `JSON` format. The notification data contains the details of the encrypted payment or refund result.

The procedure of how to decrypt the notification data is described as follows：

• Obtain the merchant's notification key from the merchant platform, and record it as `key`.
• Obtain the corresponding parameters `sign_type` for the algorithm described in `sign_type` ( `MD5` or `HMACSHA256`).
• Encrypt the received request parameters sort non-empty values not included[app_id,mchnt_id,nonce_str,sign,sign_type]. Please refer to the 【API Rule】 for the encryption method.
• Compare the sign in the return parameter

Backend Callback API（Provide by merchant）

API Description: Call back API（Provide by merchant）

Request URL:Call back URL

Request Method：POST

consumes:["application/json"]

Request Sample：

xxxxxxxxxx
{
  "app_id": "121775250444445490",
  "sign": "xxxxxx",
  "sign_type": "MD5",
  "nonce_str": "121775250444445490",
  "mchnt_id": "1000",
  "actualAmt": 888,
  "openId": "P0000232000",
  "attach": "",
  "body": "xxxx",
  "channel": "mpupay",
  "currency": "MMK",
  "detail": "",
  "deviceInfo": "",
  "payMsg": "",
  "payStartDate": "",
  "payStatus": "PAY_SUCCESS",
  "refundDate": "",
  "refundNo": "",
  "refundType": "",
  "spbillCreateIp": "",
  "timeExpire": "",
  "orderAmt": 888,
  "tradeNo": "",
  "tradeType": ""
}

Request Parameter：

Field Name	Description	Type	Length
applyNo	Payment authorization request number	string	32
openId	Unique user ID under the merchant	string	32
actualAmt	Actual amount ,For example: 1 MMK Format：100	string	11
attach	attach data: merchants can define the data by self.	string	256
body	Product name or payment brief description	string	128
channel	Payment Channel	string	8
currency	Currency ，MMK	string	8
detail	Detail information of the product	string
deviceInfo	Device No.	string	32
payEndDate	Payment End Time yyyy/MM/dd HH:mm:ss	string
payMsg	Payment Return Message	string	128
payStartDate	Payment Start Time : yyyy/MM/dd HH:mm:ss	string
payStatus	Payment status [Reference to the appendix - payment status]	string	128
refundDate	Refund time : yyyy/MM/dd HH:mm:ss	string
createDate	Create Date : yyyy/MM/dd HH:mm:ss	string
modifyDate	modify Date: yyyy/MM/dd HH:mm:ss	string
refundNo	Refund No.	string	32
timeExpire	timeExpire	string	5
orderAmt	Order amount , For example: 1 MMK Format：100	string	20
tradeNo	Trade number.	string	32
tradeType	[Reference to the appendix - Trade Type]	string	12
errCode	If payStatus is PAY_FAIL, [Reference to the appendix - ErrCode]	string	12

 

Response Status:

Status Code	Description	schema
200	OK