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"
            }
        }
    }
}