Overview
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. It is recommended that you use an accelerated domain name to enable faster access to Alipay+. If you have any problem setting up the accelerated domain name, contact the Alipay+ Solution Architect for help.
Region | Common domain name | Accelerated domain name (recommended) |
North America | ||
Other regions |
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
orV2
.
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.
Header field | Required | Code sample |
signature | Yes |
|
Content-Type | No |
|
client-id | Yes |
|
Request-Time | Yes |
|
Agent-Token | No |
|
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 supported algorithm is RSA256, which refers to SHA256withRSA. The value is case-insensitive.
- keyVersion: Specifies the version of key pairs that are used to generate and validate the signature. If you maintain versions for your key pairs, set the value of this parameter as the latest key version; otherwise, set it as 1.
- 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 assigned by Alipay+ to identify a Partner and is associated with the keys used for the signature. You can obtain the value of this parameter from Alipay+ Developer Center.
Note: The client IDs used for the Sandbox and Production environments are different and obtained through different paths.
- For Sandbox, access the client ID through the Applications > Sandbox > Settings > Integration Information panel.
- For Production, access the client ID through the Applications > Production > Settings > Integration Information panel.
Request-time
The parameter 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 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.
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.
Header field | Required | Code sample |
signature | Yes |
|
Content-Type | No |
|
client-id | Yes |
|
response-Time | Yes |
|
Table. Response header
For details of each header field, see the following descriptions:
Signature
The parameter 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 supported algorithm is RSA256, which refers to SHA256withRSA. The value is case-insensitive.
- 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 assigned by Alipay+ to identify a Partner and is associated with the keys used for the signature. You can obtain the value of this parameter from Alipay+ Developer Center.
Note: The client IDs used for the Sandbox and Production environments are different and obtained through different paths.
- For Sandbox, access the client ID through the Applications > Sandbox > Settings > Integration Information panel.
- For Production, access the client ID through the Applications > Production > Settings > Integration Information panel.
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.
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 illustrates the message transmission workflow from Acquiring Service Provider to Alipay+:
Figure 1. Message transmission workflow
The message transmission consists of the following steps:
- The ACQP adds the signature to the request and sends the request to Alipay+ (Steps 1-2).
- After receiving the request, Alipay+ validates the signature, handles the request, and adds the signature to the response (Steps 3-5).
- After receiving the response from Alipay+, the ACQP validates the signature and handles the response (Steps 6-8).
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.
- Sign the request message. Message signing and signature validation are mandatory for all requests and responses. For more information, see sign a request.
- 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.