Alipay online payments and in-store payments products offer a set of Application Programming Interfaces (APIs) that provides the ability to integrate with Alipay. You can use 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.

Message structure

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

Request structure

The following figures illustrate the request message structure:

Figure 1. Request structure 

Request URL

The request URL is: https://{host}/api/v{version}/{restfulPath}

where,

• host: includes the host that is the standard domain name assigned by wallet backend.
• version: is the version of Open APIs, for example, v1.
• restfulPath: is the path to the interface.

An interface can be uniquely identified by restfulPath and version. For example, the https://{host}/v1/payments/pay interface is different from https://{host}/v2/payments/pay

Request method

POST method is used to make an HTTP request. 

Request header

The request header mainly contains fields such as Client-Id, Signature, Encrypt, Content-Type, Request-Time, and Agent-Token. 

Client-Id Required

Client-Id is used to identify a client, and is associated with the keys that are used for signature and encryption. 

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 (=). 

The following keys can be configured: 

• algorithm: Specifies the digital signature algorithm that is used to generate the signature. The value is not case-sensitive. RSA256 and ECC224 are supported, and RSA256 by default. 
• 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

Encrypt Conditional

This field is required when a message needs to be encrypted. Encrypt 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 symmetric key algorithm that is used to encrypt message. The value is not case-sensitive, and currently only RSA_AES is supported. 
• keyVersion: Specifies the symmetric key version that is used to encrypt message. By default, the value is the latest version of the key associated with clientId. 
• symmetricKey: Contains the encrypted symmetric key. 

For example:

Encrypt: algorithm=RSA, keyVersion=1,
symmetricKey=bqS8HSmdaRrpKSuPy7CqUlyd8lJurG93

Content-Type Optional

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 signature and encrypting/decrypting content. 

For example:

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

Request-Time Required

Specifies the time when the request is sent, as defined by RFC3339. Note: This field must be accurate to milliseconds.

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

Agent-Token Optional

An agent can obtain the token from Alipay, and then use this client authorized token to interact with Alipay. 

Request body

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

Request sample

curl -X POST \
https://open-na-sandbox.alipay.com/v1/payments/pay \
-H 'Content-Type: application/json' \
-H 'Client-Id: TEST_5X00000000000000' \
-H 'Request-Time: 2019-05-28T12:12:12.253+08:00' \
-H 'Signature: algorithm=RSA256, keyVersion=1,
signature=KrwDE9tAPJYBb4cUZU6ALJxGIZgwDXn5UkFPMip09n%2FkYKPhEIII%2Fki2rYY2lPtuKVgM
Nz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waA
ASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsL
ygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%2B7MQC4VcqJGcoLE9aqNnPCX1O8G4stEPwsp
YwShsjhp5AVjeCNvk0ar9JIqQ6VZ0nMQGwZoZ6gcFw%3D%3D' \
-d '{
"productCode": "IN_STORE_PAYMENT",
"paymentNotifyUrl": "http://yoursite.com/notify",
"paymentRequestId": "payment0000000001",
"paymentMethod": {
"paymentMethodId": "288888888888880000",
"paymentMethodType": "CONNECT_WALLET"
},
"paymentFactor": {
"inStorePaymentScenario": "PaymentCode"
},
"paymentAmount": {
"currency": "USD",
"value": "100"
},
"order": {
"orderDescription": "TestOrder",
"orderAmount": {
"currency": "USD",
"value": "100"
},
"merchant": {
"referenceMerchantId": "Merchant001ID",
"merchantName": "Merchant001",
"merchantMCC": "7011",
"store": {
"referenceStoreId": "Store001ID",
"storeName": "Store001",
"storeMCC": "7011"
}
}
}
}'

Response structure

The following figures illustrate the response structure:

Figure 2. Response structure 

Response header

Response header carries additional information about the response, such as the signature and the encryption. Most fields in the response header are the same as that of the request header, except:

traceId Required

The traceId field is used for troubleshooting when there is something wrong with a request processing. For example, use traceId to identify the specific request that has issues.

Response-Time Required

Specifies the time when the response is sent, as defined by RFC3339.

Response body

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 and the result message (resultMessage) means an error message, which is used for troubleshooting. For more information about how to resolve errors, see Error codes.

Response sample

client-id:TEST_5X00000000000000
content-type:application/json;charset=UTF-8
response-time:2020-03-13T09:59:22Z
signature:algorithm=RSA256,keyVersion=1,signature=rlux%2FDjx44EuIDEW3pEkttG1vw%2FAOdbyxHN7xF2SuHDJ8F%2BW4Q4fXZl7iVAn7zeR0CwWkqHZvJ6pdMVz5FNy7pFIQoACilNx1UJd3gT%2FNN0WLn%2BomEzTgBBu2oKy0nrE%2BHKZN9SbA0R9oWH2gpO1yiry%2FGZhW%2F9JYs2hHIufEx60MfAYaUOsU2m%2FpRpAgzsIV6Cxlb2bDaenMfUR8l1OtSfRp80jy%2BknR5JSQ77GKGU%2BXn6aFTJggnSTSqSO6MflWBQ8c1jF0%2BkN9u6KzSKRhNWuiBs3jQ80bt19xPyM8Du4FNKdAzGPkpIM7589Wa30XFdjnkSOmqJCmzr5UK5CXQ%3D%3D
tracerid:0be9923a15840935597895255e8e44.0.1.1
{
    "actualPaymentAmount": {
        "currency": "CNY",
        "value": "732.13"
    },
    "paymentAmount": {
        "currency": "USD",
        "value": "100"
    },
    "paymentCreateTime": "2020-03-13T02:59:20-07:00",
    "paymentId": "202003131940108001001883A0204400004",
    "paymentQuote": {
        "guaranteed": false,
        "quoteCurrencyPair": "123/156",
        "quotePrice": 7.32132343
    },
    "paymentRequestId": "payment0000000001",
    "paymentTime": "2020-03-13T02:59:21-07:00",
    "pspCustomerInfo": {
        "displayCustomerId": "san***@mock.com",
        "pspCustomerId": "20882020003621B1",
        "pspName": "ALIPAYCN"
    },
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

Message transmission workflow

If encryption is required, the message body should be encrypted before signed, the whole interacting sequence is illustrated below:

Figure 1. Message transmission workflow 

Overall procedure

Follow the overall procedure to call an API.

Preparations

• Use an API key to authenticate the request before sending the request.
• To prevent some potential errors that you might get in the response, consider the following factors:
• Encode a request to process special characters enclosed in a request
• Enable API idempontence

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 before sending a request.

1. Encrypt a request when the request contains sensitive information. If encryption is required, the message body should be encrypted before it is signed.
2. Must sign a message. Message signing and signature validation are required for all requests and responses.

2. Send a request

You can send a request via Postman or cURL command in CLI.

3. Check the response

The response is returned usually in JSON or XML format. For details about the response, see the Response structure section.

After you receive the response, perform the following actions:

1. Validate the signature of the response.
2. Decrypt the response if the request is encrypted.

4. Check the status code

The response data vary depending on 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. For more information, see the Error codes chapter.