Contract Signing

Request Contract

Endpoint

POST https://apiv3.iotpaycloud.com/contract/

Request Parameters

Field Name	Variable Name	Required	Type	Example Value	Description
Merchant ID	mchId	Yes	String(30)	10000701	Merchant number assigned by the payment center
Merchant Contract ID	mchContractId	Yes	String(128)	2177aac8-1c3e-4291-97e0-f63f69b34cb6	Merchant-generated order number, must be unique
Channel ID	channelId	Yes	String(24)	WX_JSAPI, WX_APP, WX_MWEB	See Payment Channel Parameters
Currency	currency	Yes	String(3)	CAD, CNY , USD	Three-letter currency code, CAD for Canadian Dollar
Client IP	clientIp	No	String(32)	210.73.10.148	Client IP address
Device	device	No	String(50)	Optional values IOS, ANDROID	Terminal device ID (store number or POS device ID), for PC Web or Official Account payments use "WEB"
Notify URL	notifyUrl	Yes	String(1000)	https://xxx.com/notify.php	Callback URL for contract signing result, do not include `?`
Payer Name	payerName	Yes	String(32)	Zhang San	Name of the signing user, used for display on the page. No URL encoding required; UTF-8 non-3-byte characters not supported
Terminal Type	terminalType	No	String(3)	Optional values WEB, APP, WAP	Device type of the payer
Extra Parameters	extra	Yes	String(512)		Required for WeChat Mini Program and WX_APP
Return URL	returnUrl	No	String(1000)		URL to redirect after signing. Must not contain `?` and domain should match contract agreement
Sub Account	jobNo	Yes	String(50)		Merchant login name
Signature	sign	Yes	String(32)	C380BEC2BF3519F3AD6	Signature value, see Signature Algorithm

Parameter Example

"params={
  "mchId": "10000000",
  "mchContractId": "2177aac8-1c3e-4291-97e0-f63f69b34cb6",
  "payerName": "Zhang San",
  "sign": "F64C43C1487C7C0DA93DA93DD2961FA2",
  "returnUrl": "http://ngrok.4jicao.com/goods/returnUrl",
  "clientIp": "127.0.0.1",
  "extra": "{\"openId\":\"o2RvowBf7sOVJf8kJksUEMceaDqo\", \"type\":\"minipay\",\"appId\":\"xxxxxxxxx\"}",
  "notifyUrl": "http://ngrok.4jicao.com/goods/payNotify",
  "currency": "CAD",
  "device": "WEB",
  "channelId": "WX_JSAPI"
}"

WX_JSAPI Distinguish Mini Program / H5 / Official Account

If extra is not provided, it is treated as H5 or Official Account.

Extra Parameter Explanation

Mini Program Payment (WX_JSAPI)

Field Name	Variable Name	Required	Type	Example Value	Description
Extra Parameter	extra	Yes	JSON	{"openId":"o2RvowBf7sOVJf8kJksUEMceaDqo", "type":"minipay","appId":"xxxxxxxxx"}	`openId`, `type`, `appId` are required

WeChat App Payment (WX_APP)

Field Name	Variable Name	Required	Type	Example Value	Description
Extra Parameter	extra	Yes	JSON	{"type":"apppay","appId":"xxxxxxxxx"}	`type`, `appId` are required

Response

WX_JSAPI (Mini Program) | WX_APP

Use sessionId as the parameter for SDK authorization.

{
  "resCode": "SUCCESS",
  "retCode": "SUCCESS",
  "retParams": "20250820078349254214",
  "retDetail": {
    "sessionId": "20250820078349254214"
  }
}

WX_JSAPI H5 / Official Account

{
  "resCode": "SUCCESS",
  "retCode": "SUCCESS",
  "retParams": "https://api.mch.weixin.qq.com/global/papay/contracts/login?os_session_id=20250820071335058284#wechat_pay",
  "retDetail": {
    "authUrl": "https://api.mch.weixin.qq.com/global/papay/contracts/login?os_session_id=20250820071335058284#wechat_pay"
  }
}

WX_MWEB

Returned URL is a link, not a QR code.

{
  "resCode": "SUCCESS",
  "retCode": "SUCCESS",
  "retParams": "https://osapp.pay.weixin.qq.com/global/papay/contracts/sessions/show_code?os_session_id=20250820072523252067",
  "retDetail": {
    "qrcodeUrl": "https://osapp.pay.weixin.qq.com/global/papay/contracts/sessions/show_code?os_session_id=20250820072523252067"
  }
}

Contract Status Callback

Callback Method

POST https://merchant-callback-url

Callback Parameters

Field Name	Variable Name	Required	Type	Example Value	Description
Iotpay Contract ID	iotpayContractId	Yes	String	10000701	Merchant number assigned by the payment center
Merchant Contract ID	mchContractId	Yes	String	2177aac8-1c3e-4291-97e0-f63f69b34cb6	Merchant-generated order number, must be unique
Contract Status	status	Yes	String	Only 2 is considered signed	Status: 1: waiting, 2: signed, 9: revoked
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

Revoke Contract

Endpoint

POST https://apiv3.iotpaycloud.com/contract/revoke_token

Request Parameters

Field Name	Variable Name	Required	Type	Example Value	Description
Merchant ID	mchId	Yes	String(30)	10000701	Merchant number assigned by the payment center
Merchant Contract ID	mchContractId	Yes	String(128)	2177aac8-1c3e-4291-97e0-f63f69b34cb6	Merchant-generated order number, must be unique
Sub Account	jobNo	Yes	String(50)		Merchant login name
Currency	currency	Yes	String(3)	CAD, CNY	Three-letter currency code, CAD for Canadian Dollar
Signature	sign	Yes	String(32)	C380BEC2BF3519F3AD6	Signature, see Signature Algorithm

Response

This is a synchronous interface.

{
  "resCode": "SUCCESS",
  "retCode": "SUCCESS",
  "retParams": "",
  "retDetail": "SUCCESS"
}

{
  "resCode": "FAIL",
  "retCode": "FAIL",
  "retDetail": "",
  "retMsg": "contract is not signed yet "
}