Alipay global heartbeat interface

2021-02-26 06:59

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

Request

Service address

Environment	URL
Production	https://iopenmonitor.alipay.com/monitor/api/heartbeat/isv

Request head

Parameter Description

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

Parameter Description

heartBeat

list<HeartBeatInfo>

Required

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

Example:123456

HeartBeatInfo

Parameter Description

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

Parameter Description

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

Parameter Description

resultInfo

ResultInfo(/) Required

Result info. See resultInfo for details.

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

resultInfo

Parameter Description

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