签约

请求签约

端点

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

请求参数说明

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	String(30)	10000701	支付中心分配的商户号
商户合约号	mchContractId	是	String(128)	2177aac8-1c3e-4291-97e0-f63f69b34cb6	商户生成的订单号，请保证唯一性
渠道ID	channelId	是	String(24)	WX_JSAPI，WX_APP, WX_MWEB	见支付渠道参数
币种	currency	是	String(3)	CAD , CNY , USD	三位货币代码,加币:CAD
客户端IP	clientIp	否	String(32)	210.73.10.148	客户端IP地址
设备	device	否	String(50)	可选值 IOS,ANDROID	终端设备号(门店号或收银设备ID)，注意：PC网页或公众号内支付请传"WEB"
签约结果回调URL	notifyUrl	是	String(1000)	https://xxx.com/notify.php	签约结果回调URL,勿包含？
签约人名称	payerName	是	String(32)	张三	签约用户的名称，用于页面展示,不需要对值进行URL编码，参数值不支持UTF8非3字节编码的字符
设备类型	terminalType	否	String(3)	可选值 WEB, APP, WAP	支付者的设备类型
附加参数	extra	是	String(512)		微信小程序，WX_APP
签约结束跳转URL	returnUrl	否	String(1000)		签约结束跳转URL，勿包含`?` ，需要于签约协议中domain相同
子账号	jobNo	是	String(50)		商户登录名
签名	sign	是	String(32)	C380BEC2BF3519F3AD6	签名值，详见签名算法

参数示例

"params={
  "mchId": "10000000",
  "mchContractId": "2177aac8-1c3e-4291-97e0-f63f69b34cb6",
  "payerName": "张三",
  "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区分微信小程序/H5/公众号

不传extra视为H5/公众号

附加参数extra说明

小程序支付(WX_JSAPI)

字段名	变量名	必填	类型	示例值	描述
附加参数	extra	是	JSON	{"openId":"o2RvowBf7sOVJf8kJksUEMceaDqo", "type":"minipay","appId":"xxxxxxxxx"}	openid,type,appId为必填。

微信App支付(WX_APP)

字段名	变量名	必填	类型	示例值	描述
附加参数	extra	是	JSON	{"type":"apppay","appId":"xxxxxxxxx"}	type,appId为必填。

返回结果

WX_JSAPI(微信小程序)|WX_APP

使用 sessionId 作为SDK发起授权的参数值

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

WX_JSAPI H5/公众号

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

返回的URL是一个链接而非二维码

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

签约状态回调

回调方式

POST https://商户回调URL

回调参数

字段名	变量名	必填	类型	示例值	描述
Iotpay合约号	iotpayContractId	是	String	10000701	支付中心分配的商户号
商户合约号	mchContractId	是	String	2177aac8-1c3e-4291-97e0-f63f69b34cb6	商户生成的订单号，请保证唯一性
签约状态	status	是	String	只有2视为已签约	签约状态: 1:等待签约， 2:签约成功 9: 已解约
签约时间	signedAt	是	String	1755558434000	签约时间，毫秒时间戳
取消时间	cancelledAt	是	String	0	取消时间，毫秒时间戳
合约ID	contractId	否	String	202508190766771823708667160266	合约ID
openId	openId	否	String	osirq1BQeEV3-	用户的openId
签名	sign	是	String	B6A8F46537B4B5C888A9	签名值，详见签名算法

代扣解约

端点

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

请求参数说明

字段名	变量名	必填	类型	示例值	描述
商户ID	mchId	是	String(30)	10000701	支付中心分配的商户号
商户合约号	mchContractId	是	String(128)	2177aac8-1c3e-4291-97e0-f63f69b34cb6	商户生成的订单号，请保证唯一性
子账号	jobNo	是	String(50)		商户登录名
币种	currency	是	String(3)	CAD , CNY	三位货币代码,加币:CAD
签名	sign	是	String(32)	C380BEC2BF3519F3AD6	签名值，详见签名算法

返回结果

该接口为同步接口

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

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