App integrate IOTPay

Basic process

There are four roles in the whole integration:

1, Merchant App
2, Merchant backend server
3, IOTPay API server
4, Third party(Alipay, WeChatPay, UnionPay) server

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 the third party pay server via SDK. IOTPay API server will notify merchant backend server when the transaction is successful.

An image

Merchant App call merchant backend server API

The API is defined by merchant, can use the following as reference:

Server address: https://merchant_server/pay?channelid=XXX&amount=xxx

Request method: GET

Merchant backend server call create order API of IOTPay, after get the request from merchant app.

For app integration, channel should be:

Channel ID	Channel Name
WX_APP	WeChat Pay
ALIPAY_MOBILE	Alipay
UPI_APP	UnionPay's SecurePay in app

After 2026-March-10, ALIPAY channelId = ALIPAY_MOBILE is not supported SDK integration. Please use diagram below for integration.

An image

API Request from Merchant Backend

Endpoint

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

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 number in merchant system, need to be unique
channelId	y	String(24)	`ALIPAY_MOBILE`	`ALIPAY_MOBILE` OR `WX_APP` OR `UPI_APP`
currency	y	String(3)	CAD	only `CAD` and `USD` supported
amount	y	int	100	payment amounts, in cents, e.g. $28.56 is 2856
clientIp	y	String(32)	210.73.10.148	Client IP
device	n	String(64)	WEB	device identifier
osType	n	String(10)	IOS	ALIPAY_MOBILE and ALIPAY_WAP are required! Possible values: IOS, ANDROID
notifyUrl	y	String(200)	http://xxx.com/notify.php	IOTPay will notify this URL when payment success
returnUrl	n	String(200)	ALIPAY_PC,ALIPAY_WAP,ALIPAY_MOBILE need this	redirect to this url after payment
subject	y	String(64)	product ID or title	product ID or title
body	y	String(255)	product description	the description of the product
param1	n	String(64)	IOTPay will send back the original value
param2	n	String(64)	IOTPay will send back the original value
extra	y	String(512)	`{"type":"apppay","appId":"xxxxxxxxx"}`	WeChat mini program, WX_APP, WX_APP need this
jobNo	y	String(50)		merchant login name
remarks	n	String(200)		remarks
sign	y	String(32)	C380BEC2BFD727A4B6845133519F3AD6	signature

WeChat App(WX_APP)

Note

To obtain your WeChat appId, please register your app at WeChat's Weixin Open Platform. Note that you will have to create an account if it's the first time you are using Weixin Open Platform.

name	required	type	sample	description
extra	y	JSON	`{"type":"apppay","appId":"xxxxxxxxx"}`

Alipay App(ALIPAY_MOBILE) or UPI_APP

name	required	type	sample	description
extra	n	JSON	ignore this parameter

PHP sample code

require_once('Utility.php');

$url = 'http://api.iotpaycloud.com/v1/create_order';
$merchantId  = '1000####';
$merchantKey = '#############################';

$channelId  = $_REQUEST['channelid'];
$orderAmount = $_REQUEST['amount'];

$orderNo = $_SERVER['REQUEST_TIME'];

$Utility = new Utility();
$ip = $Utility->real_ip();
$notifyUrl = 'https://develop.iotpay.ca/demo/order/notify.php';
$subject = 'test';
$body = 'payTest';

$extra = '';
if($channelId =='WX_APP')
{
  $appId  = 'wxxxxxxxxxxxxxx';
  $type = 'apppay';
  $extra = json_encode(array(
    'type' => $type,
    'appId' => $appId,
  ));
}

$arr = array(
    'mchId' => $merchantId,
    'mchOrderNo' => $orderNo,
    'extra' => $extra,
    'channelId' => $channelId,
    'currency' => 'CAD',
    'amount' => intval($orderAmount * 100),
    'clientIp' => $ip,
    'device' => 'WEB',
    'notifyUrl' => $notifyUrl,
    'subject' => $subject,
    'body' => $body,

);

$sortArray = $Utility->arg_sort($arr);

$arr['sign'] = $Utility->build_mysign($sortArray, $merchantKey, "MD5");//Generate signature parameter sign

$param = 'params=' . json_encode($arr);

$resBody = $Utility->request($url, $param);//Submit to the gateway

$res = json_decode($resBody, true);

echo json_encode($res['payParams']);  //client app use payParams to call sdk

WeChat/Alipay/UnionPay SDK and Documents:

Demo source code

download

Changelog

2026-03-10

Add required field osType when channelId=ALIPAY_MOBILE , channelId=ALIPAY_WAP and the value should be ANDROID or IOS
Change response parameter for channelId=ALIPAY_PC, ALIPAY_WAP, ALIPAY_MOBILE

`channelId = ALIPAY_MOBILE`

Request params changed: osType is required and should be ANDROID or IOS

Response changed: The original retParams, retDetail and payParams are format of orderStr which is deprecated. payParams is the scheme url to open Alipay app retDetail is the html form to open Alipay page retParams.tradeNo is the order id of Alipay, which can be used to pay with Alipay's jssdk or Alipay's mini program

Response comparison: original response:

{
  "resCode": "SUCCESS",
  "retCode": "SUCCESS",
  "retParams": "service=\"mobile.securitypay.pay\"&partner=\"2088821558736584\"&out_trade_no=\"AA20260204145835078594034226\"&subject=\"testProduct\"&body=\"This is the description for the test product\"&total_fee=\"0.04\"&currency=\"CAD\"&payment_type=\"1\"&product_code=\"NEW_WAP_OVERSEAS_SELLER\"&seller_id=\"2088821558736584\"&notify_url=\"https://api.iotpaycloud.com/v1/alinotify\"&forex_biz=\"FP\"&it_b_pay=\"60m\"&secondary_merchant_id=\"344480625\"&secondary_merchant_name=\"IOT&PAY TECHNOLOGIES INC.\"&_input_charset=\"utf-8\"&sign=\"1jDCE7mrFu3BvmfMNsDqCGh%2B5gDblNbX8sZgB5Ex3PKi%2By1Vlec3DTaETpYP6jl%2FuRALV2dGcUs7jcwxL0uRQwkJZeXTLK1t22hbG6skr5mIfgiqkWaHdcLd%2BdG1q8x01CmQbYak3VGW8B4RZlzYHsS1lkdL%2BGlp8HdebYfQnFg%3D\"&sign_type=\"RSA\"",
  "payOrderId": "AA20260204145835078594034226",
  "mchOrderNo": "2329ccdd-3dc4-4cda-9db8-9e7830d462ee",
  "retDetail": "service=\"mobile.securitypay.pay\"&partner=\"2088821558736584\"&out_trade_no=\"AA20260204145835078594034226\"&subject=\"testProduct\"&body=\"This is the description for the test product\"&total_fee=\"0.04\"&currency=\"CAD\"&payment_type=\"1\"&product_code=\"NEW_WAP_OVERSEAS_SELLER\"&seller_id=\"2088821558736584\"&notify_url=\"https://api.iotpaycloud.com/v1/alinotify\"&forex_biz=\"FP\"&it_b_pay=\"60m\"&secondary_merchant_id=\"344480625\"&secondary_merchant_name=\"IOT&PAY TECHNOLOGIES INC.\"&_input_charset=\"utf-8\"&sign=\"1jDCE7mrFu3BvmfMNsDqCGh%2B5gDblNbX8sZgB5Ex3PKi%2By1Vlec3DTaETpYP6jl%2FuRALV2dGcUs7jcwxL0uRQwkJZeXTLK1t22hbG6skr5mIfgiqkWaHdcLd%2BdG1q8x01CmQbYak3VGW8B4RZlzYHsS1lkdL%2BGlp8HdebYfQnFg%3D\"&sign_type=\"RSA\"",
  "payParams": "service=\"mobile.securitypay.pay\"&partner=\"2088821558736584\"&out_trade_no=\"AA20260204145835078594034226\"&subject=\"testProduct\"&body=\"This is the description for the test product\"&total_fee=\"0.04\"&currency=\"CAD\"&payment_type=\"1\"&product_code=\"NEW_WAP_OVERSEAS_SELLER\"&seller_id=\"2088821558736584\"&notify_url=\"https://api.iotpaycloud.com/v1/alinotify\"&forex_biz=\"FP\"&it_b_pay=\"60m\"&secondary_merchant_id=\"344480625\"&secondary_merchant_name=\"IOT&PAY TECHNOLOGIES INC.\"&_input_charset=\"utf-8\"&sign=\"1jDCE7mrFu3BvmfMNsDqCGh%2B5gDblNbX8sZgB5Ex3PKi%2By1Vlec3DTaETpYP6jl%2FuRALV2dGcUs7jcwxL0uRQwkJZeXTLK1t22hbG6skr5mIfgiqkWaHdcLd%2BdG1q8x01CmQbYak3VGW8B4RZlzYHsS1lkdL%2BGlp8HdebYfQnFg%3D\"&sign_type=\"RSA\"",
  "sign": "F1D60EDB111026FDC36DC39DD85B5E3C"
}

New response:

{
  "resCode": "SUCCESS",
  "retCode": "SUCCESS",
  "retParams": {
    "url": "https://render.alipay.com/p/c/jzmcoal2/acn-wap-continue.html?url=alipayconnect%3a%2f%2fplatformapi%2facwallet%2falipayconnectcode%3fcode%3dgolcashier66511663-9a8f-4cea-b141-ec214bb9bd4asandbox%26golSandbox%3dtrue%26pspName%3dALIPAY_CN&paymentId=20260204114010800190184000018685170&callback=https%3A%2F%2Fdev.iotpaycloud.com%2Fv1%2Fgalipayrtn%3Fpayorderid%3DAA20260204145804816118393649&amountValue=0.04&amountCurrency=CAD&county=US&merchantId=21841100000580I7&merchantName=IOT%26%2BPAY%20%E4%BD%A0%E5%A5%BD%20TECHNOLOGIES%20INC.&code=golcashier66511663-9a8f-4cea-b141-ec214bb9bd4asandbox&referenceOrderId=b4ac8f53-a93f-4a82-8059-307644ce2166&paymentMethodType=ALIPAY_CN",
    "schemeUrl": "alipayconnect://platformapi/acwallet/alipayconnectcode?code=golcashier66511663-9a8f-4cea-b141-ec214bb9bd4asandbox&golSandbox=true&pspName=ALIPAY_CN",
    "tradeNo": "20260204114010800190184000018685170"
  },
  "payOrderId": "AA20260204145804816118393649",
  "mchOrderNo": "b4ac8f53-a93f-4a82-8059-307644ce2166",
  "retDetail": "https://render.alipay.com/p/c/jzmcoal2/acn-wap-continue.html?url=alipayconnect%3a%2f%2fplatformapi%2facwallet%2falipayconnectcode%3fcode%3dgolcashier66511663-9a8f-4cea-b141-ec214bb9bd4asandbox%26golSandbox%3dtrue%26pspName%3dALIPAY_CN&paymentId=20260204114010800190184000018685170&callback=https%3A%2F%2Fdev.iotpaycloud.com%2Fv1%2Fgalipayrtn%3Fpayorderid%3DAA20260204145804816118393649&amountValue=0.04&amountCurrency=CAD&county=US&merchantId=21841100000580I7&merchantName=IOT%26%2BPAY%20%E4%BD%A0%E5%A5%BD%20TECHNOLOGIES%20INC.&code=golcashier66511663-9a8f-4cea-b141-ec214bb9bd4asandbox&referenceOrderId=b4ac8f53-a93f-4a82-8059-307644ce2166&paymentMethodType=ALIPAY_CN",
  "payParams": "alipayconnect://platformapi/acwallet/alipayconnectcode?code=golcashier66511663-9a8f-4cea-b141-ec214bb9bd4asandbox&golSandbox=true&pspName=ALIPAY_CN",
  "sign": "662F9DA3B1E7AF77A2AE016C60F6F660"
}

Request sample:

curl --location --request POST 'https://api.iotpaycloud.com/v1/create_order' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Accept: */*' \
--header 'Cache-Control: no-cache' \
--header 'Host: api.iotpaycloud.com' \
--header 'Connection: keep-alive' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: acw_tc=2f584a5017709191550335243ec00071ae250a5509c8bf3db46b6407f38bdd' \
--data-urlencode 'params={
    "mchId": "10000576",
    "mchOrderNo": "ef28ca74-f379-4a65-a246-c731d846d87b",
    "jobNo": "abcde",
    "currency": "CAD",
    "channelId": "ALIPAY_MOBILE",
    "amount": 4,
    "returnUrl": "https://iottest.requestcatcher.com",
    "notifyUrl": "https://gptest.requestcatcher.com",
    "subject":"testProduct",
    "body":"This is the description for the test product",
    "clientIp": "192.168.50.127",
    "osType":"ANDROID",
    "sign": "3837C685A81FCEB91C6E182D8294FCFD"
}'