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

      Alipay global heartbeat interface

      Use this heartbeat interface to monitor network status, device status, and so on.


      #Request

      #Service address


      #Request head

      ParameterDescription

      version

      String(8) Required

      The API version 

      Default:1.0.1

      isvId

      String(32) Required

      A unique account ID assigned by Alipay to identify an ISV that makes API calls

      Example:alipay0001

      reqTime

      Date time(/) Required

      The time when the request is created. If the request is created at the ISV server, this parameter is the request creation time at the ISV side. If the request is created at the terminal, this parameter is the request creation time at the terminal side. The date time with timezone. Accurate to millisecond. see RFC 3339 Section 5.6 for details. 

      Example:2001-07-04T12:08:56.253+05:30

      digest

      String(64)

      Required

      Alipay will assign ISV an account and salt. This is the value after SHA256 hash for the request body and salt. See Digest generation for details.


      #Request body

      ParameterDescription

      heartBeat

      list<HeartBeatInfo>

      Required

      The heartbeat parameter in list format. See HeartBeatInfo for details.

      Example:123456


      #HeartBeatInfo

      ParameterDescription

      secondaryMerchantId

      String(32)

      Required

      A unique ID assigned by the partner to identify a secondary merchant

      Example:123456

      storeId

      String(32) 

      Required

      A unique ID assigned by the partner to identify a store

      Example:123456

      partnerId

      String(64) 

      Required

      A unique ID assigned by Alipay to identify a partner

      Example:208xxxxxxxxxx357

      productCode

      enum<ProductCode>(64) Required

      The payment product code, with a value of OVERSEAS_MBARCODE_PAY

      Default:OVERSEAS_MBARCODE_PAY

      sceneCode

      Enum<SceneCode>(64)

      Required

      The business scene code. See sceneCode for details.

      Example:PAYMENT_QRCODE

      equipmentType

      Enum<EquipmentType>(32) 

      The equipment type. See equipmentType for details.

      Example:ECR

      terminalId

      String(64)

      Required

      The unique terminal ID of the merchant. If the transaction is requested by an ECR, use the ECR ID. If no equipment ID is available, use the MAC address.

      Example:10xx023

      networkType

      enum<NetworkType>(8) 

      The network type. See networkType for details.

      Example:4G

      action

      String(64) 

      Optional

      Whether the terminal is turned on or turned off. See action for details.

      Example:SIGNON

      terminalReqTime

      Date time(/) 

      Required

      The time when the request is created on terminal. Format: yyyy-MM-ddTHH:mm:ss.SSS±timezone.

      Example:2001-07-04T12:08:56.253+05:30

      available

      boolean

      Required

      Whether heartbeat in terminal is avaliable.

      Example:true

      extendInfo

      String(2048)

      Extended information. The key-value formatted parameter reserved for future use.

      Example:{"SHOP_ID":"BJ_ZZ_001"}


      #Response

      #Response head

      ParameterDescription

      isvId

      String(32) Required

      A unique account ID assigned by Alipay to identify an ISV that makes API calls

      Example:385xxxxxxxxx0001

      respTime

      Date time(/) Required

      Response time. The date time with timezone, see RFC 3339 Section 5.6 for details. 

      Example:2001-07-04T12:08:56+05:30


      #

      #Response body

      ParameterDescription

      resultInfo

      ResultInfo(/) Required

      Result info. See resultInfo for details. 

      Example:{ "resultStatus": "S", "resultCodeId": "00000000", "resultCode":"SUCCESS", "resultMsg": "result message" }


      #resultInfo

      ParameterDescription

      resultStatus

      String(2) Required

      The request status. Possible values are:

      • S: Success
      • F: Failure
      • U: Unknown

      Example:S

      resultCodeId

      String(8) Required

      An 8-digit code that is used to identify a result. When resultStatus is S, the value of this parameter must be 00000000. When resultStatus is F or U, the value of this parameter can be other result ID specified by the interface. 

      Example:00000000

      resultCode

      String(64) Required

      The result code

      Example:SUCCESS

      resultMsg

      String(256)

      When resultCode is S, this parameter can be empty. When resultCodeis F or U, the error description is required.

      Example:success


      #Digest generation

      Alipay will assign an account and the salt to ISV. The following sample describes how an ISV can generate digests.

      copy
      import java.math.BigInteger;
      import java.security.MessageDigest;
      import java.security.NoSuchAlgorithmException;
      
      public class JavaSHA256Hash {
          public static void main(String[] args) {
              String body = "{\n"
                      + "        \"heartBeat\": [{\n"
                      + "        \"partnerId\": \"208xxxxxxxxxx353\",\n"
                      + "        \"secondaryMerchantId\": \"123456\",\n"
                      + "        \"storeId\": \"112\",\n"
                      + "        \"productCode\": \"OVERSEAS_MBARCODE_PAY\",\n"
                      + "        \"sceneCode\": \"PAYMENT_QRCODE\",\n"
                      + "        \"equipmentType\": \"ECR\",\n"
                      + "        \"terminalId\": \"10xx023\",\n"
                      + "        \"networkType\": \"4G\",\n"
                      + "        \"action\":\"SIGNON\",//Optional SIGNON, SIGNOFF, ECHO\n"
                      + "        \"terminalReqTime\": \"2001-07-04T12:08:56.256+05:30\",\n"
                      + "        \"available\": ture,\n"
                      + "        \"extendInfo\": \"{\\\"SHOP_ID\\\":\\\"BJ_ZZ_001\\\"}\"\n"
                      + "      }]\n"
                      + "        }";
              //the salt of the isv account 'alipay001'
              String salt = "$2a$10$MlpPfCtlEVip3uoBiKucYOrFwb.LapBO0vUU8UtGoWLZkZTerjGUu";
              System.out.println("SHA256 digest is: " + getSHA256Str(body + salt));
          }
      
          public static String getSHA256Str(String str) {
              MessageDigest messageDigest;
              String encdeStr = "";
              try {
                  messageDigest = MessageDigest.getInstance("SHA-256");
                  byte[] hash = messageDigest.digest(str.getBytes("UTF-8"));
                  encdeStr = Hex.encodeHexString(hash);
              } catch (NoSuchAlgorithmException e) {
                  logger.error(e.getMessage());
                  throw new RuntimeException(e.getMessage());
              } catch (UnsupportedEncodingException e) {
                  logger.error(e.getMessage());
                  throw new RuntimeException(e.getMessage());
              }
              return encdeStr;
          }
      }


      #sceneCode

      Name

      Type

      Description

      PAYMENT_QRCODE

      String

      Barcode Payment

      TRANSACTION_QRCODE

      String

      Transaction QR Code Payment

      SHOP_QRCODE

      String

      Merchant QR Code Payment


      #equipmentType

      Name

      Type

      Description

      ECR

      String

      Electronic cash register

      STORE

      String

      Store

      VM

      String

      Vending machine

      POS

      String

      POS machine of a bank, or other cashier devices with Linux system, such as an INSPIRY smart box

      APP

      String

      Smart devices, phones, mPOSs with Android/IOS systems

      IOT

      String

      IoT products

      OTHER

      String

      Other devices


      #networkType

      Name

      Type

      Description

      2G

      String

      2G network

      3G

      String

      3G network

      4G

      String

      4G network

      5G

      String

      5G network

      WIFI

      String

      Wi-Fi network

      LAN

      String

      Local area network


      #action

      Name

      Type

      Description

      SIGNON

      String

      The terminal is turned on.

      SIGNOFF

      String

      The terminal is turned off.

      ECHO

      String

      The terminal is being used.


      #Result code

      #Basic result code

      resultCodeId

      resultCode

      resultStatus

      Remarks

      00000000

      SUCCESS

      S

      Success

      00000019

      PROCESS_FAIL

      F

      General business failure

      00000901

      UNKNOWN_EXCEPTION

      U

      API failed because of unknown reasons.

      00000004

      PARAM_ILLEGAL

      F

      The parameter is incorrect.

      00000007

      INVALID_SIGNATURE

      F

      The signature is invalid.

      00000016

      OAUTH_FAILED

      F

      The oAuth authentication failed.


      #Sample request

      copy
      {
          "request": {
              "head": {
                  "version": "1.0.1",
                  "isvId": "alipay001", 
                  "digest": "049abc1c1cb3101c2baf59ed1a620fb4574b4f01abb5a857a30da4bfa516fead",
                  "reqTime": "2001-07-04T12:08:56.253+05:30"
              },
              "body": {
              "heartBeat": [{
              "partnerId": "208xxxxxxxxxx353",
              "secondaryMerchantId": "123456",
              "storeId": "112",
              "productCode": "OVERSEAS_MBARCODE_PAY",
              "sceneCode": "PAYMENT_QRCODE",
              "equipmentType": "ECR",
              "terminalId": "10xx023",
              "networkType": "4G",
              "action":"SIGNON",//Optional SIGNON, SIGNOFF, ECHO
              "terminalReqTime": "2001-07-04T12:08:56.256+05:30",
              "available": ture,
              "extendInfo": "{\"SHOP_ID\":\"BJ_ZZ_001\"}"
            }]
              }
          }
      }


      #Sample response

      copy
      {
          "response":{
              "head":{
                   "isvId":"alipay001",
                   "respTime":"2001-07-04T12:08:56+05:30",
      
              },
              "body":{
                  "resultInfo":{
                      "resultStatus":"S",
                      "resultCodeId":"00000000",
                      "resultCode":"SUCCESS",
                      "resultMsg":"success"
                  }
              }
          }
      }