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

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 Barcodeopen in new window Which may help you when going through the documentation.

Parameters

NameRequiredTypeSampleDescription
mchIdyString(30)20001222merchant id assigned by IOTPay
mchOrderNoyString(30)20160427210604000490order id assigned by merchant
need to be unique
jobNoyString(50)merchant login name
currencyyString(3)CADonly CAD and USD supported
channelIdyStringWX_MICROPAYWX_MICROPAY, ALIPAY_MICROPAY, or UPI_MICROPAY
amountyint100payment amount in cents,eg. $28.65 is 2865
devicenString(64)V1-B18The type of the scanning device
deviceIdnString(64)V102219391901The ID of the scanning device
notifyUrlyString(200)http://xxx.com/notify.phpneed to pass this value,but not used for now
subjectyString(64)product1product title
bodyyString(255)this product is goodproduct description
codeTypeyString(64)"barcode"Fill in "barcode" here
identityCodeyString(64)352645673847987656Personal payment code number
obtained by scanning
remarksnString(200)remarks
clientIpyString(32)210.73.10.148client ip
signyString(32)C380BEC2BFD727A4B6845133519F3AD6signature

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 NameRequiredTypeSample ValueDescription
retCodeYesStringSUCCESSSUCCESS/FAIL,either retCode or resCode is FAIL, the transaction failed
resCodeYesStringSUCCESSSUCCESS/FAIL,either retCode or resCode is FAIL, the transaction failed
retMsgNoStringSignature FailedThe returned information is the cause of the error if not blank.
Signature failure or parameter format verification error
payOrderNoJSONorder detailif resCode and retCode are SUCCESS, payOrder will be returned

The following fields are returned in payOrder:

Variable NameRequiredTypeSample ValueDescription
payOrderIdYesString'AM20210727205735526962718926'unique pay order id assigned by IOT Pay
mchOrderNoYesString'1627419455'unique pay order id assigned by merchant
statusYesInt22 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

StatusDescription
0created but not paid
1user is paying, e.g. user is typing password
2paid
3paid and notified the merchant(if notifyUrl used)
4cancelled by system
9cancelled 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.

Last Updated: