API fundamentals


    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, message fields, and message transmission) of online message between your system and Alipay. A message refers to the request message or the response message.


    #Request message structure 

    The following figures illustrate the request message structure: 


    request message.png

    Figure 1. Request structure 


    #Request URL 

    The request URL is: https://{host}/ams/api/v1/{restfulPath}

    where, 

    host is the standard domain name assigned by Alipay.

    restfulPath is the path to the interface. 

    An interface can be uniquely identified by restfulPath and majorVersion


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

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

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

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

    copy
    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 message interface. 


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

    response message.png

    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:


    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 parameter, which indicates the result of an interface call, is always contained. 


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

    Read the following chapter for general information of message fields, such as data type, common data structure, and processing rules of special characters. 


    #Data type

    This following table describes the data types supported by Alipay. 

    Data type 

    Description 

    String 

    A sequence of bytes. 

    Email 

    Email format

    URL 

    URL format

    Datetime 

    Date time as defined by RFC3339. For example, 2020-01-01T23:59:59+08:00 

    Date 

    A three-part value (yyyyMMdd) designating a time point in time. 

    Boolean 

    The boolean value can be either true or false. 

    Integer 

    A numeric value without a decimal. 

    Decimal 

    A numeric value with a decimal. 

    Array 

    A homogeneous data structure (elements have same data type) that stores a sequence of consecutively numbered objects--allocated in contiguous memory. 

    Table 1. Data type


    #Process rules of special characters 

    The following rules are about how to process special characters enclosed in the message. 


    #base64 

    For byte data, such as the signature and the encrypted content, encode the data with the base64 algorithm before transmitting. 


    #urlencode 

    For URL data, perform URL encoding first before transmitting. For example: 

    Original URL: https://www.merchant.com/authorizationResult 

    Converted URL: https%3A%2F%2Fwww.merchant.com%2FauthorizationResult