API specification (new)

Alipay APIs are HTTP-based RESTful APIs with request and response messages formatted in JSON. An API caller, uniquely identified by the clientId assigned by Alipay during the on-boarding process, can use the POST method to call the APIs.

Message structure
API request and response messages are formatted in JSON and encoded in UTF-8. A message contains three parts: head, body, and signature. The following examples illustrate the message structure:

API request

{
    "request": {
         <request header>
         <request body>
    },
    <signature>
}

API Response

{
    "response": { 
        <response header>
        <response body> 
    }, 
    <signature> 
}

API vs. SPI

Both API and SPI are used in the payment solutions. The differences are described as below:

API stands for Application Programming Interface. APIs refer to interfaces of services hosted or implemented by Alipay, in which client is the API caller and Alipay is the service provider.

SPI stands for Service Provider Interface. SPIs refer to interfaces that are intended to be implemented or extended by a third party. For example, the callback services implemented by client, for which Alipay is the caller and client is the service provider.

Request

Request head

The following parameters are included in the request head:

Request body

Service parameters in the request body section vary depending on services. For more information, see instructions of the specific interface.

Response

Response head

The following parameters are included in the response head:

Response body

Parameters in this section specify the variable parts of the resources, and vary depending on services. However, the resultInfo parameter, which returns the result of an API call, is fixed as the first parameter in the response body.

The resultInfo is a structure that contains four elements:

• resultStatus: The status value can be:

• S: The API call is successful.

• F: The API call is failed.

• U: The result of the API call is unknown. Mostly because of system error or intra-system timeouts. In some circumstances, client can retry the API call or actively query until a determined result is returned.

• resultCodeId: A unique digital number that represents the result code. Clients can ignore this ID.

• resultCode: The result code string.

• resultMsg: The descriptive message for the result code.

Digital signature

RSA signature is used to ensure the authenticity of the messages. To make the API call, client and Alipay must exchange their RSA public keys. Therefore, each party keeps its own RSA private key and shares the public key with the other side. When sending messages, sender uses its RSA private key to sign the message while the receiver uses sender's RSA public key to verify the received message.

For more information about how to sign a message and how to verify a signature, see Digital signature.

Sample

Sample request

{
    "request":{
        "head":{
            "version":"2.0.0",
            "function":"alipay.intl.acquiring.agreement.payCancel",
            "clientId":"211xxxxxxxxxxxxxxxxxx",
            "reqTime":"2001-07-04T12:08:56+05:30",
            "reqMsgId":"1234567asdfasdf1123fda",
            "reserve":"{}"
        },
        "body":{
            "merchantId":"218xxxxxxxxxxxxxxxxxx",
            "acquirementId":"2015032412007101547201352747"
        }
    },
    "signature":"signature string"
}

Sample response

{
    "response":{
        "head":{
            "version":"2.0.0",
            "function":"alipay.intl.acquiring.agreement.payCancel",
            "clientId":"211xxxxxxxxxxxxxxxxxx",
            "respTime":"2001-07-04T12:08:56+05:30",
            "reqMsgId":"1234567asdfasdf1123fda",
            "reserve":"{}"
        },
        "body":{
            "resultInfo":{
                "resultStatus":"S",
                "resultCodeId":"00000000",
                "resultCode":"SUCCESS",
                "resultMsg":"success"
            },
            "acquirementId":"2015xxxxxxxxxxxxxxxxxxxxxxxx",
            "merchantTransId":"510xxxxxxxxxxxxxxxxx",
            "cancelTime":"2001-07-04T12:08:56+05:30"
        }
    },
    "signature":"signature string"
}

Usage limitations

Whenever the interface description and specification limitations listed here are in conflict with that on a specific API doc, the information on the specific API doc prevails.