Merchant Scan Barcode
This document pertains to offline merchants such as restaurants, supermarkets, and retailers. These merchants utilize a scanning system to process payments, where they scan the customer's barcode or QR code from platforms like Alipay, WeChat, or UnionPay to initiate the payment process.
Note
Merchants with existing POS systems can develop a custom application to leverage this endpoint's functionality, assuming their POS features barcode scanning.
Alternatively, contact us at info@iotpay.ca or call us directly at +1 (604) 283-3268 to inquire about pre-programmed POS machines specifically designed for seamless integration with our services.
How it works
API Request
Endpoint
https://api.iotpaycloud.com/v1/create_order
Method
POST
Header
Content-Type: application/x-www-form-urlencoded
! Tip
After you receive access credentials (merchant id, login name, merchant key). You can step through the demo Merchant Scan Barcode Which may help you when going through the documentation.
Parameters
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| mchId | y | String(30) | 20001222 | merchant id assigned by IOTPay |
| mchOrderNo | y | String(30) | 20160427210604000490 | order id assigned by merchant need to be unique |
| jobNo | y | String(50) | merchant login name | |
| currency | y | String(3) | CAD | 3 letter representation for currency,eg:CAD |
| channelId | y | String | WX_MICROPAY | WX_MICROPAY, ALIPAY_MICROPAY, or UPI_MICROPAY |
| amount | y | int | 100 | payment amount in cents,eg. $28.65 is 2865 |
| device | n | String(64) | V1-B18 | The type of the scanning device |
| deviceId | n | String(64) | V102219391901 | The ID of the scanning device |
| notifyUrl | y | String(200) | http://xxx.com/notify.php | need to pass this value,but not used for now |
| subject | y | String(64) | product1 | product title |
| body | y | String(255) | this product is good | product description |
| codeType | y | String(64) | "barcode" | Fill in "barcode" here |
| identityCode | y | String(64) | 352645673847987656 | Personal payment code number obtained by scanning |
| remarks | n | String(200) | remarks | |
| clientIp | y | String(32) | 210.73.10.148 | client ip |
| sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | signature |
Note
Due to backwards compatibility requirements, we require the parameters to be wrapped like the following:
params={"mchId":"10000576","mchOrderNo":1557771065,"extra":"{\"productId\":\"100005761557771065\",\"pos_flag\":\"yes\"}","channelId":"WX_MICROPAY","currency":"CAD","amount":1,"clientIp":"207.216.193.72","notifyUrl":"http:\/\/localhost\/testTool\/test\/notify.php","subject":"test","body":"payTest","device":"V1-B18","deviceId":"V102174C02773","codeType":"barcode","identityCode":"352645673847987656""sign":"DF1B222C8A482231E485DAA3D1A8F685"}
Response
| Variable Name | Required | Type | Sample Value | Description |
|---|---|---|---|---|
| retCode | Yes | String | SUCCESS | SUCCESS/FAIL,either retCode or resCode is FAIL, the transaction failed |
| resCode | Yes | String | SUCCESS | SUCCESS/FAIL,either retCode or resCode is FAIL, the transaction failed |
| retMsg | No | String | Signature Failed | The returned information is the cause of the error if not blank. Signature failure or parameter format verification error |
| payOrder | No | JSON | order detail | if resCode and retCode are SUCCESS, payOrder will be returned |
The following fields are returned in payOrder:
| Variable Name | Required | Type | Sample Value | Description |
|---|---|---|---|---|
| payOrderId | Yes | String | 'AM20210727205735526962718926' | unique pay order id assigned by IOT Pay |
| mchOrderNo | Yes | String | '1627419455' | unique pay order id assigned by merchant |
| status | Yes | Int | 2 | 2 or 3 means transaction success |
Polling Order Status
WARNING
Even if retCode and resCode are both SUCCESS, it does NOT mean user has finished the payment successfully.
You will need to check the status value, if the status = 2 or 3, it means the transaction is successful.
Alternatively, you can use order query to poll the order status.
We recommend to query status every 2 seconds, up to the maximum retry limit of 30 times. If the order does not succeed within one minute, you can deem the transaction failed.
Order Status
| Status | Description |
|---|---|
| 0 | created but not paid |
| 1 | user is paying, e.g. user is typing password |
| 2 | paid |
| 3 | paid and notified the merchant(if notifyUrl used) |
| 4 | cancelled by system |
| 9 | cancelled by user |
Note
When polling order status, only 2 or 3 is success, if status > 3, the order won't be success again, the polling can be stopped.