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