Callback

Contract Status Callback

Callback Method

POST https://MerchantCallbackURL

Both signing and cancellation(from user) will trigger a callback

Callback Example

{
  "iotpayContractId": "CWJ202508182305444",
  "mchContractId": "b208c6dd-4f4e-4745-b17c-8d8a348f7064",
  "status": "2",
  "signedAt": "1755558434000",
  "cancelledAt": "0",
  "contractId": "2025081907667718",
  "openId": "osirq1BQeEVY",
  "sign": "B6A8F46537B4B5C888A95"
}

Callback Parameters

Field Name	Variable	Required	Type	Example Value	Description
Iotpay Contract ID	iotpayContractId	Yes	String	10000701	Merchant ID assigned by Payment Center
Merchant Contract ID	mchContractId	Yes	String	2177aac8-1c3e-4291-97e0-f63f69b34cb6	Merchant-generated contract ID, must be unique
Contract Status	status	Yes	String	Only “2” is considered signed	Contract status: 1: Pending, 2: Signed, 9: Terminated
Signed Time	signedAt	Yes	String	1755558434000	Signing timestamp in milliseconds
Cancelled Time	cancelledAt	Yes	String	0	Cancellation timestamp in milliseconds
Contract ID	contractId	No	String	202508190766771823708667160266	Contract ID
OpenID	openId	No	String	osirq1BQeEV3-	User’s OpenID
Signature	sign	Yes	String	B6A8F46537B4B5C888A9	Signature, see Signature Algorithm

Payment Callback

The following fields are returned only when both `retCode` and `resCode` are `SUCCESS`

Field Name	Variable	Type	Example Value	Description
Payment Order ID	payOrderId	String(30)	P20160427210604000490	Order ID generated by Payment Center
Merchant ID	mchId	String(30)	20001222	Merchant ID assigned by Payment Center
Merchant Order ID	mchOrderNo	String(30)	20160427210604000490	Merchant-generated order ID
Channel ID	channelId	String(24)	WX_JSAPI	See Payment Channel Parameters
Currency	currency	String(3)	CAD	3-letter currency code, e.g., CAD
Payment Amount	amount	int	100	Payment amount in cents
Status	status	int	2	Payment status, 2 or 3 indicates success
Client IP	clientIp	String(32)	210.73.10.148	Client IP address
Device	device	String(64)	WEB	Terminal device ID, for PC web or WeChat Official Account payments, use "WEB"
Product Subject	subject	String(64)	Test Product	Product subject
Product Description	body	String(256)	Product description test	Product description
Channel Order ID	channelOrderNo	String(64)	wx2016081611532915ae15b00b0167893571	Third-party payment channel order ID
Extra Param 1	param1	String(64)	Returned as-is (for WeChat Official Account, replaced with "mchOrderId")
Extra Param 2	param2	String(64)	Returned as-is
Payment Success Time	paySuccTime	long	Millisecond precision
Notification Type	backType	int	1	Notification type: 1-Frontend, 2-Backend
Signature	sign	String(32)	C380BEC2BFD727A4B6845133519F3AD6	Signature, see Signature Algorithm
Auto-debit	autodebit	String(1)	1	Whether signed contract exists: 1-Signed, 0-Not signed
Merchant Contract ID	mchContractId	String(128)	b53554e6-edd5-472b-b534-fe137fbbb382	Merchant-generated contract ID, must be unique
Iotpay Contract ID	iotpayContractId	String(128)	CWJ20250819011704375030054146	Contract ID assigned by Payment Center
Currency Amount	currencyAmount	String(10)	77	Currency amount in cents, returned only when `currency` differs from contract currency

After processing, the business system must return string success to Payment Center to indicate success. Returning anything other than success means failure, and the Payment Center will retry up to 4 times.

Active Order Status Polling

For merchants without backend (e.g., POS software integration) who cannot provide notifyUrl, active polling can be used to check if the order was successful.
See the Order Query API

Double Insurance for Order Status

It is strongly recommended that merchants use both notifyUrl and polling (every 30 minutes) to ensure accurate order status retrieval.