Access Instructions

The message service is an active push service launched by the Xport developer platform to improve efficiency, and the push content is currently only open to order-related messages. Based on this push service, the application no longer needs polling API to obtain distribution data, but only needs the open platform to actively push business content to the developer when the business data corresponding to the message changes, and the developer only needs to subscribe to the message in advance and analyze the message content. It should be noted that since the order of messages cannot be guaranteed, some messages need to be synchronized with the OpenAPI query interface. Message access can effectively reduce API call frequency and reduce system pressure.

Location: Open Platform Application Console - Messaging Service

Steps: Developers can configure a callback URL on the open platform to receive message requests

Select the console;

Select the message service;

Enter the callback address and select Verify. If the HTTP 200 status code is returned, the verification is successful.

Select Save.

Message format

messageType: indicates the message type

messageBody: indicates the message body (JSON string, note that messageBody itself is a string that needs to be parsed again)

messagePlatform: Message channel 1：1688 platform

timestamp: Message push time

messageType	messageBody
ORDER_CREATE	`{"messageType":"ORDER_CREATE","messageBody":"{\"orderId\":\"3305075341149134260\",\"orderNo\":\"PO202605200001\",\"orderStatus\":\"WAITING_FOR_PAYMENT\",\"payStatus\":1,\"totalAmount\":10000,\"shippingFee\":500,\"productAmount\":9500,\"refundAmount\":0,\"refundStatus\":null,\"closeReason\":null,\"tbCreateTime\":\"2026-05-20 15:40:00\",\"payTime\":null}","messagePlatform":1,"timestamp":"1779263269913"}`
ORDER_CANCEL	`{"messageType":"ORDER_CANCEL","messageBody":"{\"orderId\":\"3305075341149134260\",\"orderNo\":\"PO202605200001\",\"orderStatus\":\"CANCEL\",\"payStatus\":1,\"totalAmount\":10000,\"shippingFee\":500,\"productAmount\":9500,\"refundAmount\":0,\"refundStatus\":null,\"closeReason\":\"buyer_cancel\",\"tbCreateTime\":\"2026-05-20 15:40:00\",\"payTime\":\"2026-05-20 15:41:00\"}","messagePlatform":1,"timestamp":"1779263269913"}`
ORDER_PAY_SUCCESS	`{"messageType":"ORDER_PAY_SUCCESS","messageBody":"{\"orderId\":\"3305075341149134260\",\"orderNo\":\"PO202605200001\",\"orderStatus\":\"WAITING_FOR_SENT\",\"payStatus\":2,\"totalAmount\":10000,\"shippingFee\":500,\"productAmount\":9500,\"refundAmount\":0,\"refundStatus\":null,\"closeReason\":null,\"tbCreateTime\":\"2026-05-20 15:40:00\",\"payTime\":\"2026-05-20 15:41:00\"}","messagePlatform":1,"timestamp":"1779263269913"}`
ORDER_BUYER_VIEW_ORDER_PRICE_MODIFY	`{"messageType":"ORDER_BUYER_VIEW_ORDER_PRICE_MODIFY","messageBody":"{\"orderId\":\"3305075341149134260\",\"orderNo\":\"PO202605200001\",\"orderStatus\":\"WAITING_FOR_PAYMENT\",\"payStatus\":1,\"totalAmount\":9800,\"shippingFee\":500,\"productAmount\":9300,\"refundAmount\":0,\"refundStatus\":null,\"closeReason\":null,\"tbCreateTime\":\"2026-05-20 15:40:00\",\"payTime\":null}","messagePlatform":1,"timestamp":"1779263269913"}`
ORDER_BUYER_VIEW_ORDER_BUYER_REFUND	{"messageType":"ORDER_BUYER_VIEW_ORDER_BUYER_REFUND","messageBody":"{\"refundId\":\"TQxxxxxxxxxxxx\",\"orderId\":\"3296711100591134260\",\"status\":\"wait_seller_agree\",\"applyPayment\":\"10000\",\"applyCarriage\":\"500\",\"applyReason\":\"不想要了\",\"applyReasonId\":1,\"refundPayment\":\"10000\",\"refundCarriage\":\"500\",\"refundGoods\":false,\"onlyRefund\":true,\"goodsReceived\":true,\"goodsStatus\":2,\"disputeType\":1,\"buyerMemberId\":\"b2b-xxxx\",\"sellerMemberId\":\"b2b-xxxx\",\"gmtApply\":\"2026-05-20T15:40:00\",\"productName\":\"商品名称\",\"orderEntryIdList\":\"123456,789012\"}","messagePlatform":1,"timestamp":"1779263269913"}
ORDER_LOGISTICS_CHANGE	`{"messageType":"ORDER_LOGISTICS_CHANGE","messageBody":"{\"orderId\":3296711100591134260,\"buyerMemberId\":\"b2b-xxxx\",\"sellerMemberId\":\"b2b-xxxx\",\"currentStatus\":\"announce_sendgoods\",\"msgSendTime\":\"2026-05-20 15:40:00\"}","messagePlatform":1,"timestamp":"1779263269913"}`

For Example :

{
  "messageType": "ORDER_CREATE",
  "messageBody": "{\"orderId\":\"3305075341149134260\",\"orderNo\":\"PO202605200001\",\"orderStatus\":\"WAITING_FOR_PAYMENT\",\"payStatus\":1,\"totalAmount\":10000,\"shippingFee\":500,\"productAmount\":9500,\"refundAmount\":0,\"refundStatus\":null,\"closeReason\":null,\"tbCreateTime\":\"2026-05-20 15:40:00\",\"payTime\":null}",
  "messagePlatform": 1,
  "timestamp": "1779954399894"
}

ORDER_CREATE / ORDER_CANCEL / ORDER_PAY_SUCCESS / ORDER_BUYER_VIEW_ORDER_PRICE_MODIFY

These four order-related messages share the same messageBody structure:

Field	Type	Description
orderId	String	1688 order ID
orderNo	String	Xport internal order number
orderStatus	String	Order status, PoolOrderStatusEnum name (WAITING_FOR_PAYMENT, WAITING_FOR_SENT, SENT, CANCEL)
payStatus	Integer	Payment status
totalAmount	Integer	Total amount payable, unit: cent
shippingFee	Integer	Shipping fee, unit: cent
productAmount	Integer	Product total amount, unit: cent
refundAmount	Integer	Refund amount, unit: cent
refundStatus	Integer	Refund status (null when no refund)
closeReason	String	Close reason (only available for cancel messages)
tbCreateTime	String	1688 order creation time
payTime	String	Payment time (null when not yet paid)

ORDER_BUYER_VIEW_ORDER_BUYER_REFUND

Refund message body fields:

Field	Type	Description
refundId	String	Refund ID
orderId	String	1688 order ID
status	String	Refund status (wait_seller_agree, wait_buyer_send_goods, wait_seller_receive_goods, success)
applyPayment	String	Buyer applied refund amount, unit: cent
applyCarriage	String	Applied refund shipping fee, unit: cent
applyReason	String	Refund reason
applyReasonId	Integer	Refund reason ID
refundPayment	String	Actual refund amount, unit: cent
refundCarriage	String	Actual refund shipping fee, unit: cent
refundGoods	Boolean	Whether return goods is required
onlyRefund	Boolean	Whether it is refund only (no return)
goodsReceived	Boolean	Whether buyer has received goods
goodsStatus	Integer	Goods status: 1-not received, 2-received, 3-returned
disputeType	Integer	Dispute type: 1-in-sale refund, 2-after-sale refund
buyerMemberId	String	Buyer member ID
sellerMemberId	String	Seller member ID
gmtApply	String	Refund apply time
productName	String	Product name
orderEntryIdList	String	Order entry ID list (comma separated)

Note: The refund message body may contain additional internal fields. The fields listed above are the primary business fields.

Mechanism description

Callback address

Description: Developers need to provide a message receiving channel, receiving push in the form of HTTPS POST requests.

To use the message service, you need to prepare a callback interface for receiving messages. Perform the following operations:

Use the HTTPS callback address.

After receiving the message, return the HTTP 200 status code to confirm the message signing.

The timeout period is 1000MS.

Retry and compensation

If the message fails, it will be pushed again half an hour later, with a maximum of 5 retries.

If the system is interrupted for more than five times, obtain data again through related query interfaces.

Message signature

Description: Data will be transmitted in plain text. For security reasons, the open platform will perform summary signature processing on the message body, and the signature result will be placed in the Authorization field of the POST request header. The signature algorithm is as follows:

#Request signature parameters

Base = "{messageBody}"

Secret = "{AccessSecret}"

#Signature algorithm

HMAC-SHA256

#Generate signature

Authorization = HEX_ENCODE(HMAC-SHA256(Base, Secret));

Java signature code reference：

Handling Suggestions

General

After receiving the message, verify the signature to prevent external attacks, and do not convert or modify the original message body when signing! Otherwise, signature matching will be inconsistent.

Note: messageBody is a string, need to parse it with JSON.

Because the interface response time is limited (within 1000ms), the message can be stored in the asynchronous queue for service processing.

1. Message Ordering

Network transmission cannot guarantee that messages arrive in the order of business events. We include a timestamp (millisecond-level timestamp at the time of push) in the outer message payload. It is recommended that the consumer maintain a lastTimestamp for each order locally. Upon receiving a message, compare:

If timestamp <= lastTimestamp, treat it as a stale/outdated message and discard it.

If timestamp > lastTimestamp, process the message and update lastTimestamp.

Pseudocode:
if (message.timestamp <= orderLocalState.lastTimestamp) {
    // stale message, skip
    return;
}
// process message
orderLocalState.update(message);
orderLocalState.lastTimestamp = message.timestamp;

2. Order Status Jump

In extreme cases, status transitions may appear to skip intermediate states. For example, the local state is WAITING_FOR_PAYMENT (1), but the received message already shows WAITING_FOR_SENT (4), skipping WAITING_FOR_PAYMENT → WAITING_FOR_PROCURED (3) → WAITING_FOR_SENT.

It is recommended to implement a state machine validation on the consumer side:

If a status jump is detected (the new status is not the expected next state), trigger a compensation query via the OpenAPI to pull the full status chain, rather than throwing an error or discarding the message directly.

After the compensation query completes, reconcile the local state with the authoritative state from the API.

Pseudocode:
if (!isExpectedNextState(localStatus, message.orderStatus)) {
    // status jump detected → compensation query
    fullOrder = openApi.queryOrderDetail(message.orderId);
    orderLocalState.reconcile(fullOrder);
} else {
    orderLocalState.update(message);
}

3. Idempotent Deduplication

Due to the retry mechanism (up to 5 retries on failure), the same message may be delivered more than once. The consumer must ensure idempotent processing:

Use orderId + messageType + timestamp as a composite deduplication key.

Before processing a message, check whether this key has already been consumed (e.g., via Redis SETNX or database unique constraint).

If the key already exists, skip processing and return HTTP 200 directly (acknowledge receipt without re-executing business logic).

Pseudocode:
String deduplicationKey = message.orderId + ":" + message.messageType + ":" + message.timestamp;
if (redis.setnx(deduplicationKey, "1", expireTime=24h)) {
    // first time → process normally
    processMessage(message);
} else {
    // duplicate → skip
    log.info("Duplicate message received, skip: {}", deduplicationKey);
}

Message access manual

Access Instructions#

Subscribe Steps#

Message format#

ORDER_CREATE / ORDER_CANCEL / ORDER_PAY_SUCCESS / ORDER_BUYER_VIEW_ORDER_PRICE_MODIFY#

ORDER_BUYER_VIEW_ORDER_BUYER_REFUND#

Mechanism description#

Callback address#

Retry and compensation#

Message signature#

Handling Suggestions#

General#

1. Message Ordering#

2. Order Status Jump#

3. Idempotent Deduplication#