Query Order API
This API is only used for WeChat Pay, Alipay, and UnionPay.
API Request
Endpoint
POST https://apiv3.iotpaycloud.com/contract/query_order
Method
POST
Headers
Content-Type: application/x-www-form-urlencoded
! Note
After receiving the access credentials (Merchant ID, Login Name, Merchant Key),
you can test according to the demo Query Order.
This may help while reading the documentation.
Request Parameters
| Field Name | Variable | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Merchant ID | mchId | Yes | String(30) | 1000000010 | Merchant number assigned by the payment center |
| Payment Order ID | payOrderId | Yes* | String(30) | P20160427210604000490 | Order number generated by the payment center |
| Merchant Order No | mchOrderNo | Yes* | String(30) | 20160427210604000490 | Order number generated by the merchant |
| Signature | sign | Yes | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value, see Signature Algorithm |
Note
Only one of payOrderId or mchOrderNo needs to be included in the request parameters.
Response
| Field Name | Variable | Type | Example Value | Description |
|---|---|---|---|---|
| Return Code | retCode | String(16) | SUCCESS | SUCCESS/FAIL - This field indicates communication status, not transaction status. Check resCode to determine transaction result. |
| Return Message | retMsg | String(128) | Signature Fail | Return message. If not empty, indicates error reason such as signature failure or parameter validation error. |
The following fields are returned when retCode = SUCCESS
| Field Name | Variable | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Business Result | resCode | Yes | String(16) | SUCCESS | SUCCESS/FAIL |
| Error Code | errCode | No | String(32) | SYSTEMERROR | Error code |
| Error Message | errCodeDes | No | String(128) | System Error | Error description |
The following fields are returned when both retCode and resCode = SUCCESS
| Field Name | Variable | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Merchant ID | mchId | Yes | String(30) | 20001222 | Merchant number assigned by the payment center |
| Merchant Order No | mchOrderNo | Yes | String(30) | 20160427210604000490 | Order number generated by the merchant |
| Channel ID | channelId | Yes | String(24) | WX_JSAPI | See Payment Channel Parameters |
| Currency | currency | Yes | String(3) | CAD | Three-letter currency code, e.g., CAD |
| Payment Amount | amount | Yes | int | 100 | Payment amount in cents |
| Client IP | clientIp | No | String(32) | 210.73.10.148 | Client IP address |
| Device | device | No | String(64) | WEB | Terminal device number (store number or POS ID). For PC or WeChat Official Account, use "WEB". |
| Notify URL | notifyUrl | Yes | String(200) | http://xxx.com/notify.php | Payment result callback URL |
| Subject | subject | Yes | String(64) | Test Product | Product subject |
| Description | body | Yes | String(256) | Test Product Description | Product description |
| Extra Param 1 | param1 | No | String(64) | Returned as-is during callback | |
| Extra Param 2 | param2 | No | String(64) | Returned as-is during callback | |
| Extra Parameters | extra | Yes | String(512) | {"openId": "o2RvowBf7sOVJf8kJksUEMceaDqo"} | Additional parameters for specific channels, see below. |
| Payment Success Time | paySuccTime | No | Long | 1505049094262 | Payment success timestamp |
| Channel Order No | channelOrderNo | No | String | wx20170910211043fb206e92260071822007 | Third-party payment order number |
| Order Status | status | Yes | int | 2 or 3 | 2 or 3 means success |
| Auto Debit | autodebit | String(1) | 1 | Auto debit status: 1-signed, 0-not signed | |
| Merchant Contract ID | mchContractId | String(128) | b53554e6-e | Merchant-generated unique contract ID | |
| Iotpay Contract ID | iotpayContractId | String(128) | CWJ202508190117 | Contract ID assigned by the payment center |
Order Status List
| Status Code | Description |
|---|---|
| 0 | Created but not paid |
| 1 | User on payment screen (e.g., entering password) |
| 2 | Payment successful |
| 3 | Payment successful and merchant notified |
| 4 | Cancelled by system |
| 9 | Cancelled by user |
Note
When polling for order status, only status codes 2 or 3 indicate success.
If the status code is greater than 3, the order will never succeed, and polling can be stopped.
Error Codes
For more error codes, see here.
Query Contract API
API Request
Endpoint
POST https://apiv3.iotpaycloud.com/contract/query_contract
Method
POST
Headers
Content-Type: application/x-www-form-urlencoded
Request Parameters
| Field Name | Variable | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Merchant ID | mchId | Yes | String(30) | 1000000010 | Merchant number assigned by the payment center |
| Merchant Contract ID | mchContractId | Yes* | String(128) | b53554e6-edd5-472b-b534-fe137fbbb382 | Merchant-generated unique contract ID |
| Iotpay Contract ID | iotpayContractId | Yes* | String(128) | CWJ20250819011704375030054146 | Contract ID assigned by the payment center |
| Signature | sign | Yes | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Signature value, see Signature Algorithm |
Note
Only one of mchContractId or iotpayContractId needs to be included in the request parameters.
Response
| Field Name | Variable | Type | Example Value | Description |
|---|---|---|---|---|
| Return Code | retCode | String(16) | SUCCESS | SUCCESS/FAIL - This field indicates communication status, not transaction status. Check resCode to determine transaction result. |
| Return Message | retMsg | String(128) | Signature Fail | Return message. If not empty, indicates error reason such as signature failure or parameter validation error. |
The following fields are returned when retCode = SUCCESS
| Field Name | Variable | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Business Result | resCode | Yes | String(16) | SUCCESS | SUCCESS/FAIL |
| Error Code | errCode | No | String(32) | SYSTEMERROR | Error code |
| Error Message | errCodeDes | No | String(128) | System Error | Error description |
The following fields are returned when both retCode and resCode = SUCCESS
| Field Name | Variable | Required | Type | Example Value | Description |
|---|---|---|---|---|---|
| Merchant Contract ID | mchContractId | Yes | String(128) | 8034c925-bd31-470d-8e0f-9c0138634277 | Merchant-generated unique contract ID |
| Iotpay Contract ID | iotpayContractId | Yes | String(128) | CWJ20250819230751595515113500 | Contract ID assigned by the payment center |
| Contract Status | status | Yes | int | 1 | Contract status: 1: Pending, 2: Signed, 9: Terminated |
| Signed At | signedAt | Yes | Long | 0 | Signing timestamp in milliseconds |
| Cancelled At | cancelledAt | Yes | Long | 0 | Cancellation timestamp in milliseconds |
| Status Description | statusDescription | Yes | String | Processing | Contract status description: Signed, Processing, Terminated |
changelog
| Date | Description |
|---|---|
| 2024-08-26 | modify Variablesigned_at and cancelled_at to signedAtandcancelledAt |