POS Semi-Integration

IOT Pay supports POS(Point Of Sale) to integrate with Credit Card payment terminals without worrying about Payment Card Industry Data Security Standard (PCI DSS)open in new window. Please contact IOT Pay to get detailed information.

Unified Create Order Interface

To keep things simple, you can still use our unified create order API with the channel: CC_PAX

API Request

Endpoint

https://api.iotpaycloud.com/v1/create_order

Method

POST

Content-Type: application/x-www-form-urlencoded

Parameters

NameRequiredTypeSampleDescription
mchIdyString(30)10000701merchant id assigned by IOTPay
mchOrderNoyString(30)20160427210604000490order id assigned by merchant
need to be unique
channelIdyString(24)CC_PAXsee more channel id
currencyyString(3)CAD3 letter representation for currency,eg:CAD
amountyint100payment amount in cents,eg. $28.65 is 2865
clientIpyString(32)210.73.10.148client ip
devicenString(64)POS9876device info
notifyUrlyString(200)http://localhostuse 'http://localhost' when channel='CC_PAX'
subjectyString(64)test productproduct title
bodyyString(255)this product is for funproduct description
extrayString(512)'CC_API'any string you want, not used now, but must have a value
jobNoyString(50)merchant login name
remarksnString(200)remarks
signyString(32)C380BEC2BFD727A4B6845133519F3AD6signature

Request Sample

{
  "amount": "1",
  "body": "IOTPay",
  "channelId": "CC_PAX",
  "clientIp": "192.168.50.186",
  "currency": "CAD",
  "device": "V1-B25",
  "extra": "{\"pos_flag\":\"yes\",\"productId\":\"10000576_null\"}",
  "jobNo": "testpax",
  "mchId": "10000576",
  "mchOrderNo": "1632349674730",
  "notifyUrl": "http://localhost",
  "source": "pos_2.1.54",
  "subject": "IOTPay",
  "tip": "0",
  "sign": "AE51912B1FB627A1820BAF34DC89EF10"
}

Return Result

NameRequiredTypeSampleDescription
retCodeyStringSUCCESSSUCCESS/FAIL
resCodeyStringSUCCESSSUCCESS/FAIL
retMsgnString'signature fail'only available when error occurs
signyStringC380BEC2BFD727A4B6845133519F3AD6signature
payOrderyJsonall information about this order

Result Sample

{
  "resCode": "SUCCESS",
  "retCode": "SUCCESS",
  "retParams": "",
  "payOrderId": "CP20210922192314685200722249",
  "mchOrderNo": "1632338577033",
  "retDetail": "",
  "payOrder": {
    "userName": "testpax",
    "storeId": "ixm329sgr",
    "payOrderId": "CP20210922192314685200722249",
    "mchId": "10000576",
    "mchOrderNo": "1632338577033",
    "transId": "",
    "originalOrderId": "",
    "channelId": "CC_PAX",
    "currency": "CAD",
    "amount": 1,
    "tip": 0,
    "rate": 0,
    "payType": "pay",
    "refundable": 1,
    "clientIp": "192.168.50.186",
    "deviceId": "V1-B25",
    "deviceType": "",
    "notifyUrl": "http://localhost",
    "subject": "IOTPay",
    "body": "IOTPay",
    "param1": "",
    "param2": "",
    "extra": "{\"cardType\":\" \",\"cardNum\":\"\",\"expireDate\":\"    \",\"emvLabel\":\"\",\"emvAID\":\"\",\"emvTVR\":\"\",\"emvTSI\":\"\",\"emvTC\":\"\",\"termNum\":\"25957\",\"bankTermNum\":\"40880013\",\"termInvoiceNum\":\"167339\",\"seqNum\":\"000000000000\",\"authNum\":\"\",\"batchNum\":\"0000\",\"trxMethod\":\"\",\"accountType\":\"\",\"receiptDisp\":\"Transaction Not Completed 05\",\"cashbackAmount\":\"\",\"timeStamp\":\"20210922-15231494\",\"surchargeAmount\":\"\",\"langCode\":\"E\",\"trxDate\":\"\",\"trxTime\":\"\",\"cvmResults\":\"\",\"trxCode\":\"00\"}",
    "channelOrderNo": "",
    "status": 9,
    "remarks": "",
    "rateValue": 0,
    "trxAmount": 0,
    "costAmount": 0,
    "currencyAmount": 0,
    "paySuccTime": "",
    "createDate": 1632338594000,
    "updateDate": 1632338599000
  },
  "sign": "EA86BEEBE37C8C8F8A8E88C080D5E241"
}

Get order status from the response

Create Order is a synchronous API so the client side will wait for the response to get the order status.

if resCode == 'SUCCESS' and retCode == 'SUCCESS':
    if payOrder['status'] in (2,3):
        #order is paid successfully
    else
        #error occurs, get error message from extra['receiptDisp']
else:
    # error occurs before sending request to the bank

What if the client timed out?

In the extreme cases, you client get timed out when waiting for the response, it is a good practice to init a Query Order request every 2 seconds, last one minute at least. When you get status in (2,3) from response, you can still deem the transaction successfully and print the receipt, and stop the loop of order query.

Useful card transaction data returned in 'extra' field

For example:

"extra":"{\"cardType\":\"M\",\"cardNum\":\"XXXXXXXXXXXX1166\",\"expireDate\":\"1022\",\"emvLabel\":\"MASTERCARD\",\"emvAID\":\"A0000000041010\",\"emvTVR\":\"0000008000\",\"emvTSI\":\"0000\",\"emvTC\":\"ARQC: 3D36ACBD44BE512B\",\"termNum\":\"25957\",\"bankTermNum\":\"40880013\",\"termInvoiceNum\":\"724172\",\"seqNum\":\"000001000061\",\"authNum\":\"01046Z\",\"batchNum\":\"0008\",\"trxMethod\":\"T\",\"accountType\":\"\",\"receiptDisp\":\"000 Approved 00 Thank You\",\"cashbackAmount\":\"\",\"timeStamp\":\"20210120-19402057\",\"surchargeAmount\":\"\",\"langCode\":\"E\",\"trxDate\":\"01202021\",\"trxTime\":\"164033\",\"cvmResults\":\"1F0302\",\"trxCode\":\"00\"}"

Receipt Requirements

For semi-integration with credit card terminal, there is a strict specification on the format and content on the receipt. Please contact IOT Pay for the specification and samples.

Last Updated: