alipay.intl.merchant.common.monitor

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


#Request head

ParameterDescription

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

ParameterDescription

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

ParameterDescription

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

ParameterDescription

resultInfo

ResultInfo(/) Required

Result info. See resultInfo for details. 

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


#Sub-parameters

#resultInfo

ParameterDescription

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

ParameterDescription

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