Asynchronous Notify
When the payment finish successfully, IOTPay API server will send message to notifyUrl so merchant can update inner order status and do some processing.
Important
IOTPay strongly recommends that merchants use both the notifyUrl and polling mechanisms to ensure reliable order status retrieval and prevent missed orders due to network or system issues.
Notify Url
Merchant pass notifyUrl to IOTPay API server via create order API. Make sure this notifyUrl can be accessed.
Notify Parameters
| Name | Type | Sample | Description |
|---|---|---|---|
| payOrderId | String(30) | P20160427210604000490 | order id assigned by third party payment system |
| mchId | String(30) | 20001222 | merchant id assigned by IOTPay |
| mchOrderNo | String(30) | 20160427210604000490 | order id assigned by merchant |
| channelId | String(24) | WX_JSAPI | see more channels |
| currency | String(3) | CAD | 3 letter representation for currency,eg:CAD |
| amount | int | 100 | payment amount in cents,eg. $28.65 is 2865 |
| status | int | 2 | payment status, currently only return 2 for success |
| clientIp | String(32) | 210.73.10.148 | client ip |
| device | String(64) | WEB | device id or WEB |
| subject | String(64) | product title | |
| body | String(256) | product description | |
| channelOrderNo | String(64) | wx2016081611532915ae15b00b0167893571 | third party channel order number |
| param1 | String(64) | if channelId = WX_JSAPI，will be "mchOrderId" | |
| param2 | String(64) | return original value | |
| paySuccTime | long | payment success time in ms | |
| backType | int | 1 | notify type，1-frontend，need to support redirect; 2-backend,only notify |
| sign | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | signature |
Return Result
When the merchant backend receives a notification request, it should return the string success. Upon receiving success, the IOTPay API server will stop sending further notifications. If no success response is received, the server will retry the notification up to 3 times.
- First: immediately upon the initial request
- Second: 5 minutes if the merchant backend does not return success
- Third: 15 minutes after the Second request if no successful response is received.
Polling Order Status
For some merchant without backend system, eg. some POS machine, notifyUrl cannot be utilized. Merchant can get order status by polling, refer to the Query Order Status endpoint.