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.


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 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




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.


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)CAD3 letter representation for currency,eg:CAD
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) 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
clientIpyString(32) ip


Due to backwards compatibility requirements, we require the parameters to be wrapped like the following:



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


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

0created but not paid
1user is paying, e.g. user is typing password
3paid and notified the merchant(if notifyUrl used)
4cancelled by system
9cancelled by user


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: