Alipay+ offers a set of Application Programming Interfaces (APIs) to achieve various capabilities, such as 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 v1. The version is specified in the URL as a path prefix, for example,

https://{host}/aps/api/v1/payments/pay.

Environment

You can select one of the domain names listed below according to your region. If you are not sure about which domain to use, contact your solution architect for help.

Message structure

Before you make any request, it is important to understand how Alipay+ APIs work and how requests and responses are structured. This section provides general information (such as message structure, message fields, and message transmission) of online messages between a partner and Alipay+.

Request structure

The following figure illustrates the request structure:

Figure 1. Request structure

Request URL

The request URL is https://{host}/{endpoint}, where:

• host is the standard domain name assigned by Alipay+.
• endpoint is the path to the interface, for example, /aps/api/{version}/payments/pay

• version is the version of the API, for example, v1 or V2.

An interface can be uniquely identified by endpoint. For example, /aps/api/v1/payments/pay is different from /aps/api/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 descriptions:

Signature

Signature contains key-value pairs that are separated by commas (,). Each key-value pair is an equation, which is a key joined with its value by 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 case-insensitive. RSA256 and ECC256 are supported. By default, RSA256 is used.
• 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=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrTpMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3JrbRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%3D%3Dxxxx

Content-Type

Optional. Content-Type indicates the media type of the request body, where charset is used for generating and validating signatures. For more information about the Content-Type field, see RFC2616.

For example：

Content-Type: application/json; charset=UTF-8

Client-Id

Client-Id is a unique ID that is assigned by Alipay+ to identify a Partner and is associated with the keys that are used for the signature.

Request-Time

Specifies the time when the request is sent, as defined in ISO 8601.

Note: This field must be accurate to seconds. For example, 2019-05-28T12:12:12+08:00 and 2021-04-21T01:47:04Z.

Agent-Token

Agent-Token is an agent token that is issued by the ACQP to authorize its TSP for API calls. When processing API calls that are requested by a TSP, Alipay+ will verify whether the value of Agent-Token is valid.

Notes:

• Obtain the value for this parameter on the Alipay+ Developer Center. For more information, see Alipay+ Developer Center User Guide for TSPs.
• Currently, the value of Agent-Token that is generated automatically on the Alipay+ Developer Center is a 48-digit string, while the maximum length of this parameter is 128.

Request body

The request body contains detailed request information in 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.

Note: Field names are case-insensitive.

Table. Response header

For details of each header field, see the following descriptions:

Signature

Signature contains key-value pairs that are separated by commas (,). Each key-value pair is an equation, which is a key joined with its value by 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 case-insensitive. RSA256 and ECC256 are supported. By default, RSA256 is used.
• 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=KEhXthj4bxxxJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrTpMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3JrbRFvcowQwt0lP1XkoPmSLGpBevxxxDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%2FFYDAwSd%2B6%xxxx

Content-Type

Optional. Content-Type indicates the media type of the response body, where charset is used for generating and validating signatures. For more information about the Content-Type field, see RFC2616.

For example：

Content-Type: application/json; charset=UTF-8

Client-Id

Client-Id is a unique ID that is assigned by Alipay+ to identify a Partner and is associated with the keys that are used for the signature.

Response-Time

Specifies the time when the response is returned, as defined in ISO 8601.

Note: This field must be accurate to seconds. For example, 2019-05-28T12:12:12+08:00 and 2021-04-21T01:47:04Z.

Response body

Response body contains the information responding to the client. Fields in this section vary depending on services. However, the result parameter, which indicates the result of an API call, is always contained.

When the result status ( resultStatus) is "Failed"(F) or "Unknown" (U), the result code ( resultCode ) indicates an error code, and the result message ( resultMessage ) indicates an error message, which is used for troubleshooting. For more information about how to resolve errors, see Error codes.

Message transmission workflow

The following figure illustrates the message transmission workflow from Acquiring Service Provider to Alipay+:

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

1. Construct a request

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

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

1. Sign the request message. Message signing and signature validation are mandatory for all requests and responses. For more information, see sign a request.
2. Encode the 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 now send a request with your preferred platform or tool, for example, via 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 receiving the response, you need to validate the signature of the response. For more information, see validate the signature of the response.

4. Check the status code

If an error occurs, an error response is returned where the result parameter indicates the error code and error message for you to troubleshoot issues. For more information, see the error codes in the Result/Error codes section in the specific API specification.