# POS Semi-Integration

IOT Pay supports POS(Point Of Sale) to integrate with Credit Card payment terminals without worrying about PCI compliance. 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

# Endpoint

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

Request method:

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

# Parameters

name required type sample description
mchId y String(30) 10000701 merchant id assigned by IOTPay
mchOrderNo y String(30) 20160427210604000490 order id assigned by merchant
need to be unique
channelId y String(24) CC_PAX see more channel id
currency y String(3) CAD 3 letter representation for currency,eg:CAD
amount y int 100 payment amount in cents,eg. $28.65 is 2865
clientIp y String(32) 210.73.10.148 client ip
device n String(64) POS9876 device info
notifyUrl y String(200) http://localhost use 'http://localhost' when channel='CC_PAX'
subject y String(64) test product product title
body y String(255) this product is for fun product description
extra y String(512) 'CC_API' any string you want, not used now, but must have a value
jobNo y String(50) merchant login name
remarks n String(200) remarks
sign y String(32) C380BEC2BFD727A4B6845133519F3AD6 signature

# 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

field name required type sample description
retCode y String SUCCESS SUCCESS/FAIL
resCode y String SUCCESS SUCCESS/FAIL
retMsg n String 'signature fail' only available when error occurs
sign y String C380BEC2BFD727A4B6845133519F3AD6 signature
payOrder y Json all 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\":\"\",\"expirDate\":\"    \",\"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\",\"expirDate\":\"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: 9/22/2021, 4:36:19 PM