Mini programs offer a set of OpenAPIs to achieve various capabilities, for example, the payment capability. You can use the POST method to send HTTPS requests and receive responses accordingly.

The following section mainly introduces the message structure and the end-to-end message transmission workflow.

Versioning

The current API version is v2. The version is specified in the URL. For example:

https://{domainName}/api/open/v2/payments/pay.

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 messages 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://{domainName}/api/open/{restfulPath}​, which has the following structure:

• ​​domainName: the standard domain name assigned by the wallet backend
• resfulPath: the path to the interface, for example, /{version}/payments/pay

• version: the version of OpenAPIs, for example, v1 or v2.

An interface can be uniquely identified by restfulPath. For example, the /v1/payments/pay is different from /v2/payments/pay.

Request method

POST method is used to make an HTTP request.

Request header

The request header mainly contains the following fields.

Note: Field names are case-insensitive.

Table. Request header

For details of each header field, 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: Specify the digital signature algorithm that is used to generate the signature. The only valid value is ​RSA256​ (case-insensitive), which indicates the algorithm is RSA with SHA256. Note that the signing key must be a 2048-bit RSA key.
• keyVersion: Specify 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: Contain 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

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 the signature.

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 the signature.

Also in Mini Program OAuth scenario, here the Client-Id is also the client ID of OAuth, which is filled in the Mini Program SAAS Platform as follow:

Request-Time

Specify the time when the request is sent, as defined by ISO8601.

Note: This field must be at least accurate to seconds.

Request-Time: 2019-04-04T12:08:56.253+05:30

Request body

The request body contains the detailed request information in JSON format. Fields enclosed in the request body vary depending on services. For more information, see the specific API specification document.

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.

Note: Field names are case-insensitive.

Table. Response header

For details of each header field, 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 only valid value is ​RSA256​ (case-insensitive), which indicates the algorithm is RSA with SHA256. Note that the signing key is a 2048-bit RSA key.
• 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

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. 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.

Response-Time

Specifies the time when the response is returned, as defined by ISO8601.

Note: This field must be at least accurate to seconds.

Response-Time: 2019-04-04T14:08:56.253+05:30

Response body

The 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. For more information about error codes, see the Error codes chapter.

Message transmission workflow

The following figure is an example that illustrates the message transmission workflow in Mini Program.

Figure 1. Message transmission workflow

Overall procedure

Follow the overall procedure to call an API.

Preparations

To prevent some potential errors that you might get in the response, consider the following factors:

• Understand API idempontency      

1. Construct a request

Construct a request by complying with the request structure, including the request header and body.

To ensure message transmission security, perform the following security measures when constructing a request. For details, see the Message transmission security chapter.

1. Must sign a request. Message signing and signature validation are mandatory for all requests and responses.
2. Encode a request to prevent errors or ambiguity that might be caused by special characters enclosed in a request. For more information, see the Message encoding chapter.

2. Send a request

You can send a request with your preferred platforms or tools, for example, Postman or cURL command.

3. Check the response

The response is usually returned in JSON or XML format. For details about the response, see the response structure section. After you receive the response, validate the signature of the response.

4. Check the status code

The response data can vary depending on the services. However, the result  field, which indicates the result of an API call, is always included. If an error occurs when you call an API, an error response is returned, where the result object indicates the error code and error message for you to troubleshoot issues. For more information, see the Error code chapter.