alipay.intl.merchant.common.monitor

2021-02-26 07:48

Use this interface to track transaction status and performance data, and detect problems of the network, machines, payment codes, and so on.

Request

Service address

Environment	URL
Production	https://open-sea.alipay.com/api/alipay/intl/merchant/common/monitor.htm

Request head

Parameter Description

version

String(8) Required

API version

Example:2.0.4

function

String(128) Required

API name

Example:alipay.intl.merchant.common.monitor

clientId

String(32) Required

A unique ID assigned by Alipay to identify a client that makes API calls

Example:385xxxxxxxxx0001

reqTime

Date time(/) Required

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

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

reqMsgId

String(64) Required

Request message ID. A unique ID assigned by the client to identify a request message. This ID identifies a unique system request rather than business request.

Example:123xxxxxxxxxxxxxxx3fda

reserve

String(256) Conditional

Reserved parameter. Key-value formatted parameter for future use. This parameter is required for system integrator. If you are a system integrator, you must provide the isvAccesstoken value.

Example:{"isvAccesstoken":123123123sdfsddsf}

signType

String(64)

Sign type

Example:RSA2

Request body

Parameter Description

merchantId

String(64) Required

The user ID of the partner, assigned by Alipay

Example:211xxxxxxxxxxxxxx2999

sellerId

String(32) Required

The user ID of the secondary merchant, assigned by the partner

Example:123456

storeId

String(32) Required

The store ID assigned by the partner

Example:123456

partnerId

String(64) Required

The unique partner ID assigned by Alipay

Example:208xxxxxxxxxx357

productCode

enum<ProductCode>(64) Required

The payment product code. See ProductCode for details.

Example:OFFLINE_PAY

sceneCode

Enum<SceneCode>(64)

The business scene code. See SceneCode for details.

Example:PAYMENT_QRCODE

sysServiceProviderId

String(16)

The service provider ID

Example:218xxxxxxxxx6645

equipmentType

Enum<EquipmentType>(32) Required

The equipment type. See EquipmentType for details.

Example:ECR

equipmentId

String(64) Required

The unique equipment 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) Required

The network type. See NetworkType for details.

Example:4G

clientNetworkTime

String(8)

The indicator of the client terminal network latency, with a unit in second and accurate to millisecond. For example, the time it costs for the client terminal to send a request to the service end.

Example:3.234

mac

String(64)

The MAC address

Example:01-23-45-67-89-AB

tradePerformInfo

list<TradePerformInfo>(/)

The trade performance data during two heartbeats, including all the transaction ID, total time cost, request time cost and the transaction status, listed chronologically in the JSON format. See TradePerformInfo for details.Note: If the sending of a heartbeat packet fails due to network errors or other reasons, the transaction data is stored locally until the heartbeat packet is sent successfully.This parameter is required when transactions exist.

Example:[{"merchantTransId":"201708011234","merchantTransTime":"5","merchantReqTime":"4","merchantTransStat":"S", "start":"2001-07-04T12:08:56+05:30"},{"merchantTransId":"201708011236","merchantTransTime":"15","merchantReqTime":"4","merchantTransStat":"X", "start":"2001-07-04T12:08:56+05:30"}]

extendInfo

String(2048)

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

Example:{"SHOP_ID":"BJ_ZZ_001","TERMINAL_ID":"1234"}

Response

Response head

Parameter Description

version

String(8) Required

API version

Example:2.0.4

function

String(128) Required

API name

Example:alipay.intl.merchant.common.monitor

clientId

String(32) Required

Client ID. The unique ID assigned by Alipay to identify a client 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

reqMsgId

String(64) Required

Request message ID. The unique ID assigned by client to identify a request message.

Example:123xxxxxxxxxxxxxxx3fda

reserve

String(256)

Reserved parameter. The key-value formatted parameter reserved for future use.

Example:{key/value}

signType

String(8)

Sign type

Example:RSA2

Response body

Parameter Description

resultInfo

ResultInfo(/) Required

Result info. See resultInfo for details.

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

Sub-parameters

resultInfo

Parameter Description

resultStatus

String(2) Required

The request status can be:S: successF: failureU: unknown

Example:S

resultCodeId

String(8) Required

Result ID. An 8-digit code that is used to identify a result. When resultStatus is S, the value must be 00000000. When resultStatus is F or U, the value 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 value can be empty. When resultCodeis F or U, the error description is required.

Example:success

ProductCode

Name	Type	Description
OFFLINE_PAY	String	Offline payment

SceneCode

Name	Type	Description
PAYMENT_QRCODE	String	Cross-border in-store payment
TRANSACTION_QRCODE	String	Cross-border transaction 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 casher 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

TradePerformInfo

Parameter Description

merchantTransId

String(64)

Merchant transaction ID. The unique ID assigned by the merchant to identify a transaction

Example:510xxxxxxxxxxxxx0002

merchantTransTime

String(8) Conditional

Merchant transaction time. Total transaction time costed at the merchant end: from the time that the code is scanned to the time that the payment result is returned by Alipay. The transaction time is in a unit of second and accurate to millisecond.This parameter is required when merchantReqTime is NULL

Example:5.315

merchantReqTime

String(8) Conditional

Merchant request time. Total request time: from the time that the request is sent by the merchant to the time that the merchant receives the response. The request time is in a unit of second and accurate to millisecond.This parameter is required when merchantTransTime is NULL

Example:4.315

merchantTransStat

enum<MerchantTransStat>(1) Required

The merchant transaction status. See MerchantTransStat for details

Example:S

start

Date time(/) Required

The start time of the transaction. Date time with timezone, see RFC 3339 Section 5.6 for details.

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

extendInfo

String(2048)

Extended information. Reserved parameter for extended information, in JSON format

Example:{"T1":"value1","T2":"value2"}

MerchantTransStat

Name	Type	Description
S	String	The transaction succeeded, which is shown directly by a transaction successful result returned for the payment request
I	String	The transaction succeeded, which is not shown by a successful result returned for the payment request but is shown by a query result or by an asynchronous response. This situation usually occurs when a payment password is needed instead of password free payment, a system error occurs, or the payment API times out
F	String	The transaction failed, which is shown directly by a transaction failed result returned for the payment request
P	String	The transaction failed, which is not shown by a transaction failed result returned for the payment request but is caused by cancelling the transaction after querying the transaction several times without getting a succesful transaction result. This situation usually occurs when a payment password is needed instead of password free payment, a system error occurs, or the payment API times out
E	String	The transaction failed, caused by the device (for example, if an error occurred when the device scanning a payment code and initiating a payment request, the transaction failed because an external transaction ID might not be created yet)
X	String	The transaction failed, caused by an error occurred when establishing the connection between the device and the merchant back end (for example, the device has an instable internet connection)
Y	String	The transaction failed, caused by a merchant server problem
Z	String	The transaction failed, caused by a failed and abandoned cancel request

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.
00000008	KEY_NO_FOUND	F	The key is not found.
00000013	NO_INTERFACE_DEF	F	The API is undefined.
00000014	API_IS_INVALID	F	The API is invalid or nonactivated.
00000016	OAUTH_FAILED	F	The oAuth authentication failed.
00000021	ACCESS_DENIED	F	Access denied
00000024	REQUEST_TRAFFIC_EXCEED_LIMIT	F	The request traffic exceeds the limit.
12003001	MERCHANT_NOT_EXIST	F	The merchant doesn't exist.
12003011	MERCHANT_HAS_REGISTER	F	The merchant has already registered.
12014152	CLIENT_FORBIDDEN_ACCESS_API	F	The Client is not authorized to use this API.
12014155	UNKNOWN_CLIENT	F	Unknown client
12014156	INVALID_CLIENT_STATUS	F	Invalid client status

Sample

Sample request

copy

{
    "request": {
        "head": {
            "version": "2.0.4",
            "function": "alipay.intl.merchant.common.monitor",
            "clientId": "385xxxxxxxxx0001",
            "reqTime": "2001-07-04T12:08:56+05:30",
            "reqMsgId": "123xxxxxxxxxxxxxxx3fda",
            "signType": "RSA2"
        },
        "body": {
            "merchantId": "211xxxxxxxxxxxxxx2999",
            "partnerId": "208xxxxxxxxxx353",
            "sellerId": "123456",
            "storeId": "112",
            "productCode": "OFFLINE_PAY",
            "sceneCode": "PAYMENT_QRCODE",
            "sysServiceProviderId": "218xxxxxxxxx6645",
            "equipmentType": "ECR",
            "equipmentId": "10xx023",
            "networkType": "4G",
            "clientNetworkTime": "3.234",
            "mac": "01-23-45-67-89-AB",
            "tradePerformInfo": [
                {
                    "merchantTransId": "510xxxxxxxxxxxxx0002",
                    "merchantTransTime": "5.315",
                    "merchantReqTime": "3.315",
                    "merchantTransStat": "S",
                    "start": "2001-07-04T12:08:36+05:30",
                    "extendInfo": "{\"T1\":\"value1\",\"T2\":\"value2\"}"
                }
            ],
            "extendInfo": "{\"SHOP_ID\":\"BJ_ZZ_001\",\"TERMINAL_ID\":\"1234\"}"
        }
    },
    "signature": "signature string"
}

Sample response

copy

{
    "response":{
        "head":{
            "version":"2.0.4",
            "function":"alipay.intl.merchant.common.monitor",
            "clientId":"385xxxxxxxxx0001",
            "respTime":"2001-07-04T12:08:56+05:30",
            "reqMsgId":"123xxxxxxxxxxxxxxx3fda",
            "reserve":"{}"
        },
        "body":{
            "resultInfo":{
                "resultStatus":"S",
                "resultCodeId":"00000000",
                "resultCode":"SUCCESS",
                "resultMsg":"success"
            }
        }
    },
    "signature":"signature string"
}