Alipay+ DocsAlipay+ Docs

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.

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:

image.png

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.

Header field

Required

Code sample 

signature

Yes

signature: algorithm=RSA256, keyVersion=1, signature=****

Content-Type

No

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

client-id

Yes

client-id: ****

Request-Time

Yes

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

Agent-Token

No

Agent-Token: ****

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:

copy
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

copy
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:

image.png

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

signature: algorithm=RSA256, keyVersion=1, signature=****

Content-Type

No

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

client-id

Yes

client-id: ****

response-Time

Yes

response-Time: 2019-04-04T12:08:56+05:30

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:

copy
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

copy
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:

  • S : Successful
  • F : Failed
  • U : Unknown

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+:

image

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.     

  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.