Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

      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


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


      API Response


      copy
      {
          "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 head


      The following parameters are included in the request head:

      ParameterNameTypeLengthRequiredDescriptionSample
      versionAPI versionString8Y-2.0.0
      functionAPI service nameString128Y-alipay.intl.acquiring.agreement.pay
      clientIdClient IDString32YThe unique ID assigned by Alipay to identify a client that makes API calls.211xxxxxxxxxxxxxxx044
      reqTimeRequest timeDatetime/YDateTime with timezone. See RFC 3339 Section 5.6 for details.2001-07-04T12:08:56+05:30
      reqMsgIdRequest message IDString64YThe unique ID assigned by client to identify a request message.1234567asdfasdf1123fda
      reserveReserved parameterString256NKey/Value formatted parameter for future use{key/value}


      #Request body


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



      #Response head


      The following parameters are included in the response head:

      ParameterNameTypeLengthRequiredDescriptionSample
      versionAPI versionString8YSame as that in request head2.0.0
      functionAPI service nameString128YSame as that in request headalipay.intl.acquiring.agreement.pay
      clientIdClient IDString32YThe unique ID assigned by Alipay to identify a client that makes API calls.Same as that in requst head
      respTimeResponse timeDatetime/YDateTime with timezone. See RFC 3339 Section 5.6 for details.2001-07-04T12:08:56+05:30
      reqMsgIdRequest message IDString64YA unique ID assigned by client to identify a request message.
      The value is copied from the API request.
      1234567asdfasdf1123fda
      reserveReserved parameterString256NKey/Value formatted parameter for future use{key/value}


      #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.

      ParameterNameTypeLengthRequiredDescriptionSample
      resultInfoResult infoResultInfo/Y-{
      "resultStatus": "S",
      "resultCodeId": "00000000",  
      "resultCode":"SUCCESS",  
      "resultMsg":
      "success"  
      }
      Other parms...


      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.



      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


      copy
      {
          "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


      copy
      {
          "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.