General Order API
General Order
Merchants can call General Order API to launch payment without diving into the details of how to integrate third party payment systems. IOTPay will handle third party API calls and respond to merchant according to the different channel.
For in-App integration, Merchant App send payment request to IOTPay API server, then IOTPay API return the encrypted data to the Merchant App. With the encrypted dat, Merchant App can send them to Alipay/WeChat pay server via their corresponding SDK. Finally, IOTPay API server will notify merchant backend server when the transaction is successful.
For detail of how to integrate in merchant app, please refer to app integration
API Request
Endpoint
https://api.iotpaycloud.com/v1/create_order
Method
POST
Header
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) | WX_NATIVE | 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) | WEB | device type(offline shop),use "WEB" when integrated on web |
| notifyUrl | y | String(200) | http://xxx.com/notify.php | get notify when succeeded |
| subject | y | String(64) | test product | product title |
| body | y | String(255) | this product is for fun | product description |
| param1 | n | String(64) | can be ignored | |
| param2 | n | String(64) | will return original value in notify | |
| extra | y | String(512) | WeChat mini program，WX_APP,WX_NATIVE need this | |
| returnUrl | n | String(200) | ALIPAY_PC,ALIPAY_WAP need this | redirect to this url after payment |
| jobNo | y | String(50) | merchant login name | |
| remarks | n | String(200) | remarks | |
| sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | signature |
Parameter Sample
params={"amount":1,"mchId":"10000000","mchOrderNo":"9af01329f1ec4c4694631b077a0e8573","subject":"product title","sign":"F64C43C1487C7C0DA93DA93DD2961FA2","body":"product desc","param1":"","param2":"","clientIp":"127.0.0.1","extra":"{\"openId\":\"osirq1MMdgrCw7ohNNV6JhwvDFO8\"}","notifyUrl":"http://ngrok.4jicao.com/goods/payNotify","currency":"CAD","device":"WEB","channelId":"WX_JSAPI"}
Extra Parameter
WeChat App Pay(WX_APP)
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| extra | required | JSON | {"type":"apppay","appId":"xxxxxxxxx"} |
Mini Program(WX_JSAPI)
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| extra | required | JSON | {"openId":"o2RvowBf7sOVJf8kJksUEMceaDqo", "type":"minipay","appId":"xxxxxxxxx"} |
Users use WeChat to scan Merchant's QR Code（WX_NATIVE）
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| extra | required | JSON | {"productId":"120989823"} | productId is required |
Extra Sample Data
"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\"}"
Notice
Parameter mchOrderNo will be put into param1 when IOT Pay sends notify to the merchant's notifyUrl provided, please don't fill param1 when creating order.
After payment, Merchant's backend server still need notifyUrl to decide whether the transaction is successful
Return Result
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| retCode | y | String | SUCCESS | SUCCESS/FAIL retCode indicate communication status, need to check resCode for transaction |
| retMsg | n | String | signature fail | if not empty, it is error message |
| sign | y | String | C380BEC2BFD727A4B6845133519F3AD6 | signature |
channelId=ALIPAY_PC or ALIPAY_WAP or UPI_SEQ
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| payOrderId | y | String | payment order id | order id assigned by third party payment system |
| payUrl | y | String | merchant need to redirect to this url, just echo payUrl to client or redirect to url in retParams | |
| retParams | y | Array | for ALIPAY_WAP, merchant need to redirect to retParams.alipayUrl,for UPI_SEQ,redirect to retParams.unionpayUrl |
channelId=ALIPAY_QR
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| payOrderId | y | String | payment order id | order id assigned by third party payment system |
| qr_code | y | String | merchant use this value to generate qr code for alipay scan |
channelId=WX_NATIVE
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| payOrderId | y | String | payment order id | order id assigned by third party payment system |
| codeUrl | y | String | merchant use this value to generate qr code for WeChat scan | |
| prepayId | y | String | prepayId is return from WeChat pay |
channelId=CC_PAX
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| extra | y | String(json) | {"cardType":"M","cardNum":"XXXXXXXXXXXX1166","expireDate":"1022"} | credit card transaction info |
Demo and source code
general order demo source code download
merchant scan demo source code download
online signature checker demo