Payment
Place an Order
Endpoint
POST https://apiv3.iotpaycloud.com/contract/create_order
Parameters
| Field Name | Variable Name | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Merchant ID | mchId | Yes | String(30) | 10000701 | Merchant ID assigned by the payment center |
| Merchant Order No | mchOrderNo | Yes | String(30) | 20160427210604000490 | Order number generated by merchant, must be unique |
| Merchant Contract No | mchContractId | Yes | String(128) | 2177aac8-1c3e-4291-97e0-f63f69b34cb6 | Contract number generated by merchant, 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, e.g. CAD |
| Payment Amount | amount | Yes | int | 100 | Payment amount in cents |
| Client IP | clientIp | No | String(32) | ||
| Device | device | No | String(50) | Optional values: IOS, ANDROID | Terminal device ID (store ID or cashier ID), for PC web or WeChat official account payment please pass "WEB" |
| Notify URL | notifyUrl | Yes | String(1000) | https://xxx.com/notify.php | Payment result notification URL, must not contain ? |
| Product Description | body | Yes | String(255) | xxpay test product | Product description |
| Extra Parameter | extra | Yes | String(512) | Required for WeChat Mini Program, WX_APP, WX_MWEB | |
| Return URL | returnUrl | No | String(1000) | Required for WX_JSAPI, ALIPAY_PC, ALIPAY_WAP | Redirect URL after payment, must not contain ? |
| Sub Account | jobNo | Yes | String(50) | Merchant login name | |
| Remarks | remarks | No | String(200) | Merchant remarks | |
| Signature | sign | Yes | String(32) | C380BEC2BF3519F3AD6 | Signature value, see Signature Algorithm |
WX_JSAPI Differentiation (Mini Program / H5 / Official Account)
If extra is not provided, it is considered H5/Official Account.
Extra Parameter Description
Mini Program Payment (WX_JSAPI)
| Field Name | Variable Name | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Extra Param | extra | Yes | JSON | {"type":"minipay","appId":"xxxxxxxxx"} | type and appId are required |
WeChat App Payment (WX_APP)
| Field Name | Variable Name | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Extra Param | extra | Yes | JSON | {"type":"apppay","appId":"xxxxxxxxx"} | type and appId are required |
Return Result
| Field Name | Variable Name | Type | Example Value | Description |
|---|---|---|---|---|
| Return Code | retCode | String(16) | SUCCESS | SUCCESS/FAIL, indicates communication status, transaction status determined by resCode |
| Return Msg | retMsg | String(128) | Signature Fail | Error message if not empty, e.g. Signature fail, parameter format error |
The following fields are returned when retCode is SUCCESS
| Field Name | Variable Name | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Business Result | resCode | Yes | String(16) | SUCCESS | SUCCESS/FAIL |
| Error Code | errCode | No | String(32) | SYSTEMERROR | Error code |
| Error Msg | errCodeDes | No | String(128) | System Error | Error message |
The following fields are returned when both retCode and resCode are SUCCESS
| Field Name | Variable Name | Type | Example Value | Description |
|---|---|---|---|---|
| Pay Order ID | payOrderId | String(30) | P20160427210604000490 | Order ID generated by the payment center |
| Merchant ID | mchId | String(30) | 20001222 | Merchant ID assigned by the payment center |
| Merchant Order No | mchOrderNo | String(30) | 20160427210604000490 | Order number generated by merchant |
| Channel ID | channelId | String(24) | WX_JSAPI | See Payment Channel Parameters |
| Currency | currency | String(3) | CAD | Three-letter currency code |
| Amount | amount | int | 100 | Payment amount in cents |
| Status | status | int | 2 | Payment status, 2 or 3 means 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 official account payment please pass "WEB" |
| Subject | subject | String(64) | Test Product | Product subject |
| Body | body | String(256) | Test Product Description | Product description |
| Channel Order No | channelOrderNo | String(64) | wx2016081611532915ae15b00b0167893571 | Order ID from third-party payment channel |
| Param1 | param1 | String(64) | Returned as is (for WeChat Official Account payments, replaced with "mchOrderId") | |
| Param2 | param2 | String(64) | Returned as is | |
| Payment Time | paySuccTime | long | In milliseconds | Payment success timestamp |
| Notify Type | backType | int | 1 | Notification type, 1-frontend, 2-backend |
| Signature | sign | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value, see Signature Algorithm |
| Autodebit | autodebit | String(1) | 1 | Autodebit, 1-signed, 0-not signed |
| Merchant Contract ID | mchContractId | String(128) | b53554e6-edd5-472b-b534-fe137fbbb382 | Contract ID generated by merchant, must be unique |
| Iotpay Contract ID | iotpayContractId | String(128) | CWJ20250819011704375030054146 | Contract ID assigned by payment center |
| Currency Amount | currencyAmount | String(10) | 77 | Amount in cents. Returned only when currency differs from settlement currency |
Payment Callback
Callback Method
POST https://merchant-notify-url
The following fields are returned when both retCode and resCode are SUCCESS
(same table as above)
Return Result
After processing, the merchant system must return string success to indicate success. If return is not success, it indicates failure. The payment center will retry notification up to 4 times.
Active Order Status Query
For merchants without backend (e.g., POS software integration) who cannot provide notifyUrl, order status can be checked actively via polling.
See order query API here
Double Insurance for Order Status
It is strongly recommended that merchants use both notifyUrl and polling (every 30 minutes) to ensure order status can be obtained.