Alipay online and in-store payment products offer a set of APIs that provide the ability to integrate with Alipay. You can use the POST method to send HTTPS requests and receive responses accordingly.

The following section 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. For example, https://{domain name}/ams/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 Alipay Technical Support.

Table 1. Location domain names

Message structure

Before you make any payments, it is important to understand how Alipay APIs work and how requests and responses are structured. This section presents general information (such as message structure and message transmission workflow) of online messages between your system and Alipay. A message refers to the request message or the response message. 

Request structure

The following figure illustrates the request message structure:

Figure 1. Request structure 

URL

The request URL is https://{domain name}/ams/api/{version}/{endpoint}, which has the following structure:

• domain name: is the standard domain name assigned by the wallet backend.
• version: is the API version, for example, v1 or v2.
• endpoint: is the endpoint to the interface, for example, /{version}/payments/pay.

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

HTTPS method

POST

Request header

The request header mainly contains the following fields.
Note: Field names are case-insensitive.

Table 2. Request header 

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

signature Required

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 (=). For details about how to generate a signature, see the Generate a signature section. 

The following keys can be configured: 

• algorithm: specifies the digital signature algorithm that is used to generate the signature. RSA256 is supported.
• 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. 

Example:

Signature: algorithm=RSA256, keyVersion=1,
signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR
rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT
pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr
bRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%
2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%3D%3D

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

For example:

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

client-id Required

client-id is used to identify a client, and is associated with the keys that are used for the signature. For details about how to obtain a client ID, see Antom Dashboard. 

request-time Required

request-time specifies the timestamp of when the request is sent. The value of this field must be accurate to milliseconds. Use one of the programming language methods to get the timestamp:

• Java: System.currentTimeMillis()
• Python: round(time.time() * 1000)
• .Net: DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
• PHP: round(microtime(true) * 1000)

request-time: 1685599933871

agent-token Optional

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

Notes:

• Obtain the value for this parameter in the Antom Dashboard. 
• Currently, the value of agent-token that is generated automatically on the Antom Dashboard 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 section vary depending on services. For more information, see instructions on the specific API specification.

Response structure

The following figure illustrates 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 3. Response header

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

signature Required

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 (=). For details about how to generate a signature, see the Generate a signature section. 

The following keys can be configured: 

• algorithm: specifies the digital signature algorithm that is used to generate the signature. RSA256 is supported.
• 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. 

Example:

Signature: algorithm=RSA256, keyVersion=1,
signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGR
rWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrT
pMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3Jr
bRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%
2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%3D%3D

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

For example:

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

client-id Required

client-id is used to identify a client, and is associated with the keys that are used for the signature. For details about how to obtain a client ID, see Antom Dashboard. 

Response-time Required

Response-time specifies the time when the response is sent, as defined by ISO 8601.

Note: This field must be accurate to seconds.

response-time: 2019-04-04T14:08:56+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 field, which indicates the result of an API call, is always contained.

When the result status (resultStatus) is failed, the result code (resultCode) is an error code, the result message (resultMessage) is an error message, which is used for troubleshooting. For more information about how to resolve errors, see Result/Error codes in the specific API.

Table 4. Response body

Message transmission workflow

The whole interaction sequence is illustrated below:

Figure 3. 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:

• To prevent potential errors that you might get in the response, understand API idempotency.
• Encode a request that contains special characters.

1. Construct a request

Construct a request by complying with the request structure, for example, by adding the client-Id, request-time, signature, and other fields to the request header.

To ensure the message transmission security, perform the following security measures when constructing a request:

• Sign the request message. Message signing and signature validation are required for all requests and responses. For more information, see sign a request and validate the signature.
• Encode the request to prevent errors or ambiguity that might be caused by special characters enclosed in the request. For details, see Message encoding.

2. Send a request

You can 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 you receive the response, validate the signature of the response.

4. Check the status code

The response data varies depending on the services. However, the result field, which indicates the result of an API call, is always contained. If an error occurs, an error response is returned, where the result object indicates the error code and error message for you to troubleshoot issues.