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

      Overview

      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.


      #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

      The domain name for each environment are listed in the following table.

      Location

      Domain name

      North America

      https://open-na.alipay.com

      Asia

      https://open-sea.alipay.com

      Europe

      https://open-eu.alipay.com (Only for in-store payments)

      Table 1. Domain name


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

      request.png

      Figure 1. Request structure 


      #Request URL

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

      where,

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


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


      #Request method

      POST


      #Request header

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


      Client-Id Required

      Client-Id is used to identify a client, and is associated with the keys that are used for signature. For details about how to obtain a client ID, see Alipay Developers Center user guide


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

      copy
      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

      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. 


      For example:

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


      Request-Time Required

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

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


      #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

      copy
      "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%2Fki2rYY2lPtuKVgMNz%2BtuCU%2FjzRpohDbrOd8zYriiukpGAxBQDIVbatGI7WYOcc9YVQwdCR6ROuRQvr%2FD1AfdhHd6waAASu5Xugow9w1OW7Ti93LTd0tcyEWQYd2S7c3A73sHOJNYl8DC1PjasiBozZ%2FADgb7ONsqHo%2B8fKHsLygX9cuMkQYTGIRBQsvfgICnJhh%2BzXV8AQoecJBTrv6p%2B7MQC4VcqJGcoLE9aqNnPCX1O8G4stEPwspYwShsjhp5AVjeCNvk0ar9JIqQ6VZ0nMQGwZoZ6gcFw%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:

      response.png

      Figure 2. Response structure 


      #Response header

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


      Response-Time Required

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


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


      Field

      Data type

      Required

      Description

      resultStatus

      String

      No

      Result status. Valid values are:

      • S : Successful
      • F : Failed
      • U : Unknown
      • A : accepted, not yet succeed, but can proceed with some actions.

      resultCode

      String (64)

      No

      Result code

      resultMessage

      String (256)

      No

      Result message that describes the result code and status in details

      Table 2. Response body


      #Response sample

      copy
      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
      {
          "actualPaymentAmount": {
              "currency": "CNY",
              "value": "732.13"
          },
          "paymentAmount": {
              "currency": "USD",
              "value": "100"
          },
          "paymentCreateTime": "2020-03-13T02:59:20-07:00",
          "paymentId": "202003131940108001001883A0204400004",
          "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

      The whole interacting sequence is illustrated below:


      Message transmission workflow.png


      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:

      • 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.
      • To ensure the message transmission security, you 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, validate the signature of the response.


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