API fundamentals
Mini Programs offers a set of OpenAPIs to achieve various capabilities, for example, the payment capability. You can us e POST method d to send HTTPS requests and receive response accordingly.
Message structure
Before you make any request, it is important to understand how OpenAPI works and how requests and responses are structured. This section presents general information (such as message structure, message fields, and message transmission) of online message between your system and wallet backend.
Request structure
The following figure illustrates the request structure.
Figure 1. Request structure
Request URL
The request URL is:https://{host}/acl/api/{restful_path}
where,
- host: includes the host that is the standard domain name assigned by the wallet backend.
- restful_path : is the path to the interface, for example,
/{version}/payments/pay
- version : is the version of OpenAPIs, for example, or .
v1
v2
An interface can be uniquely identified by restful_path
. For example, the  is different from ./v1/payments/pay
/v2/payments/pay
Request method
POST method is used to make an HTTP request.
Request header
The request header mainly contains the following fields.
Tip: Field names are case-insensitive.
Header field | Required | Code sample |
Signature | Yes |
|
Encrypt | No (It is used only when data includes sensitive information)Â |
|
Content-Type | No |
|
Client-Id | Yes |
|
Request-Time | Yes |
|
                      Table.Request header
For details, see the following description.
Signature
Signature contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=).
The following keys can be configured:
- algorithm : Specifies the digital signature algorithm that is used to generate the signature. The value is not case-sensitive. RSA256 and ECC224 are supported, and RSA256 by default.
- keyVersion : Specifies the key version that is used to generate or validate the signature. By default, the value is the latest version of the key associated with Client-Id .
- signature : Contains the signature value of the request. For details about how to generate a signature, see the Generate a signature section.
Example:
Signature: algorithm=RSA256, keyVersion=1,
signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR
rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT
pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr
bRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%
2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%3D%3Dxxxx
Encrypt
This field is required when a message need to be encrypted, especially when sensitive information is included in the message. Encrypt contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=).
The following keys can be configured:
• algorithm: Specifies the symmetric key algorithm that is used to encrypt message. The value is not case-sensitive, and currently only RSA_AES is supported.
• keyVersion: Specifies the symmetric key version that is used to encrypt message. By default, the value is the latest version of the key associated with clientId.
• symmetricKey: Contains the encrypted symmetric key.
For example:
Encrypt: algorithm=RSA_AES, keyVersion=1,
symmetricKey=bqS8HSmdaRrpKSuPy7CqUlyd8lJurG93xxxx
Content-Type
Optional. Content-Type indicates the media type of the body of the request, as defined by RFC2616. In which, charset is used for generating/validating signature and encrypting/decrypting content.
For example:
Content-Type: application/json; charset=UTF-8
Client-Id
Client-Id is used to identify a client, and is associated with the keys that are used for signature and encryption.
Also in Mini Program OAuth scenario, here the Client-Id is also the client id of OAuth, which is filled in Mini Program SAAS platform as follow:
Request-Time
Specifies the time when the request is sent, as defined by RFC3339. Note: This field must be accurate to milliseconds.
Request-Time: 2019-04-04T12:08:56.253+05:30
Request body
The request body contains the detailed request information in a JSON format. Fields enclosed in the request body vary depending on services. For more information, see the specific API specification.
Response structure
The following figures illustrate the response structure:
Â
Figure 2. Response structure
Response header
The response header carries the information about the response, mainly containing the following fields.
Tip: Field names are case-sensitive.
Header field | Required | Code sample  |
signature | Yes |
|
Encrypt | No (It is used only when data includes sensitive information)Â |
|
Content-Type | No |
|
traceId | No |
|
client-id | Yes |
|
response-time | Yes |
|
Table. Response header
For details, see the following description.
signature
Signature contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=).
The following keys can be configured:
- algorithm: Specifies the digital signature algorithm that is used to generate the signature. The value is not case-sensitive. RSA256 and ECC224 are supported, and RSA256 by default.
- keyVersion: Specifies the key version that is used to generate or validate the signature. By default, the value is the latest version of the key associated with Client-Id.
- signature: Contains the signature value of the response.
Example:
signature: algorithm=RSA256, keyVersion=1,
signature=KEhXthj4bxxxJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR
rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT
pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr
bRFvcowQwt0lP1XkoPmSLGpBevxxxDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%
2FFYDAwSd%2B6%xxxx
Encrypt
This field is required when a response needs to be encrypted. Encrypt contains key-value pairs that are separated by comma (,). Each key-value pair is an equation, which is a key joined with its value with an equal sign (=).
The following keys can be configured:
• algorithm: Specifies the symmetric key algorithm that is used to encrypt a message. The value is not case-sensitive, and currently only RSA_AES is supported.
• keyVersion: Specifies the symmetric key version that is used to encrypt a message. By default, the value is the latest version of the key associated with clientId.
• symmetricKey: Contains the encrypted symmetric key.
For example:
Encrypt: algorithm=RSA_AES, keyVersion=1,
symmetricKey=bqS8HSmdaRrpKSuPy7CqUlyd8lJurG93xxxx
Content-Type
Optional. Content-Type indicates the media type of the body of the response, as defined by RFC2616. In which, charset is used for generating/validating the signature and encrypting/decrypting content.
For example:
Content-Type: application/json; charset=UTF-8
TraceId
The traceId field is used for troubleshooting when there is something wrong with a request processing. For example, use traceId to identify the specific request that has issues.
client-id
Client-Id is used to identify a client, and is associated with the keys that are used for signature and encryption.
response-time
Specifies the time when the response is returned, as defined by RFC3339. Note: This field must be accurate to milliseconds.
response-time: 2019-04-04T14:08:56.253+05:30
Response body
Response body contains the information responding to the client. Fields in this section vary depending on services. However, the result
object, which indicates the result of an API call, is always contained.
When the result status ( resultStatus
) is failed, unknown, or accepted, the result code ( resultCode
 ) means an error code and the result message ( resultMessage
 ) means an error message, which is used for error handling.
Field | Data type | Required | Description |
resultStatus | String | No | Result status. Valid values are:
|
resultCode | String | No | Result code. Max. length: 64 characters |
resultMessage | String | No | Result message that describes the result code in details. Max. length: 256 characters |
Message transmission workflow
The following figure is an example that illustrates the message transmission workflow in Mini Program.
Figure 1. Message transmission workflow
Processing rules of special characters
The following rules are about how to process special characters enclosed in the message.
base64
For byte data, such as the signature and the encrypted content, encode the data with the base64 algorithm before transmitting.
urlencode
For URL data, perform URL encoding first before transmitting. For example:
Original URL:https://www.merchant.com/authorizationResult
Converted URL:https%3A%2F%2Fwww.merchant.com%2FauthorizationResult