# General order api

# general order

Merchants can call general order api to launch payment without diving into how to call third party payment system. IOTPay will call third party system and respond to merchant according to different channel id.

An image

For App integration, Merchant App send payment request to IOTPay API server, IOTPay API return the encrypted data to the merchant app, then merchant app send the encrypted data to Alipay/Wechat pay server via SDK. IOTPay API server will notify merchant backend server when the transaction is successful.

An image

For detail of how to integrate in merchant app, please refer to app integration

# Request URL

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

Reqeust 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)	WX_JSAPI	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 successed
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 ingored
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)	WX_JSAPI,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

# 微信App支付(WX_APP)

| extra | required | JSON | {"type":"apppay","appId":"xxxxxxxxx"} | |

# mini program(WX_JSAPI)

| extra | required | JSON | {"openId":"o2RvowBf7sOVJf8kJksUEMceaDqo", "type":"minipay","appId":"xxxxxxxxx"} | |

# users use wechat to scan merchant qrcode（WX_NATIVE）

| extra | required | JSON | {"productId":"120989823"} | productId is required |

:::Notice parameter "mchOrderNo" will be put into "param1" when notify, so please don't fill param1 when create order。 :::

After payment,merchant backend server still need notifyUrl to judge whether the transaction is successful

# return result

field 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

field 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

field 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

field 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

field name	required	type	sample	description
extra	y	String(json)	{"cardType":"M","cardNum":"XXXXXXXXXXXX1166","expirDate":"1022"}	credit card transaction info

# extra sample data

"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\"}"