# Credit Card API V3

  • 仅支持加元交易.

  • 有两种应用流程:
    简单购买流程
    重复购买流程

# 生成签名和签名验证

Sign algorithm

# Request和response参数格式

均为JSON格式。 The response body is also in JSON format. It should not be treated as fixed or as a schema, new fields may be added as the API evolves, and the order of fields might change. Your applications must therefore be resilient to the reordering of fields within a JSON object.

# 发送请求范例

$arr = array(
    'mchOrderNo' => 'm12345',   //order id assigned by merchant
    'mchUserId' => 'jacky.chen@yahoo.com'   //user id assigned by merchant
    'mchId' => 'your merchant id',
  	'currency' => 'CAD',
    'amount' => 100,   // in cents
    'loginName' => 'jack', //your login name
    'notifyUrl' => 'http://yourdomain.com/notifyme.php',
    'returnUrl' => 'http://yourdomain.com/returnhere.php',
    'subject' => "ipad pro",
    'body' => '64G,wifi,white',
    'channel' => 'PF_CC'
);
$Utility = new Utility();
$sort_array = $Utility->arg_sort($arr);   //sort the parameters
$arr['sign'] = $Utility->build_mysign($sort_array, $merchantKey, "MD5");   //generate sign and put it into the array
$param = json_encode($arr);    //generate json string to send
$resBody = $Utility->request($url, $param);//Submit to the gateway

$res = json_decode($resBody, true);
if ($res['retCode'] == 'SUCCESS') {
    header('Location: ' . $res['redirectUrl']);//Redirect to payment page
} else {
    echo $res['retMsg'];
}

# 简单购买流程

用户每次购买都需要输入信用卡信息.

# Sequence

1, 调用 cc_purchase 并且跳转到 redirectUrl 让用户输入信用卡信息;
2, 购买后, 跳转到returnUrl;
3, 交易成功后, IOTPay 会发送消息到 notifyUrl;

# Request URL for simple purchase

Endpoint: https://ccapi.iotpaycloud.com/v3/cc_purchase

Reqeust method:

  • POST
  • Content-Type: application/json;charset=UTF-8

# Parameters

name required type sample description
mchId y String(30) 10000701 assigned by IOTPay
mchOrderNo y String(30) 1234567890abc assigned by merchant
mchUserId y String(30) 007 assigned by merchant
amount y Int 1500 in cents
currency y String(3) CAD for now only CAD supported
loginName y String(12) jack123 merchant's login name
subject n String(64)
body n String(250)
channel y String PF_CC fixed value: PF_CC
notifyUrl y String(200) get notify when success
returnUrl y String(200) redirect to this url after payment
sign y String(32) C380BEC2BFD727A4B6845133519F3AD6 Sign algorithm

# Response

name required type sample description
retCode y String SUCCESS or FAIL
retMsg y String
retData.redirectUrl y String if retCode=SUCCESS, merchant redirect to this url
retData.secureId y String For SDK integration only

# NotifyUrl message(post request in json format)

name required type sample description
payOrderId y String SUCCESS or FAIL
mchId y String
mchOrderNo y String
originalOrderId y String original pay order id if payType=refund
amount y Int 100 in cents
currency y String CAD
payType y String pay or refund
refundable y Int 100 in cents
status y Int 2 2 or 3 means success
invoiceNum y String
paySuccTime y String 2021-04-07 19:44:51
cardNum y String 432567******2266
cardType y String V or M
expiryDate y String
authNum y String
transNum y String
channel y String PF_CC fixed value: PF_CC
sign y String(32) C380BEC2BFD727A4B6845133519F3AD6 Sign algorithm

# ReturnUrl parameters

name required type sample description
retCode y String SUCCESS or FAIL
retMsg n String
status y Int 2 2 or 3 both mean the transaction is successful

# 重复购买流程

用户输入一次信用卡信息完成绑卡, 后续购买无需再次输入卡号信息.

# Sequence

1, Call cc_addcard and then redirect to retData.redirectUrl to let user input credit card info;
2, After addcard, will redirect to returnUrl with the following parameters:
If success: retCode=SUCCESS
If fail: retCode=FAIL&retMsg=xxxx
3, (optional) Call cc_querycard to get card info;
4, If cc_addcard is successful, call cc_purchasewithtoken to do a real purchase

# Request URL for cc_addcard

Endpoint: https://ccapi.iotpaycloud.com/v3/cc_addcard

Reqeust method:

  • POST
  • Content-Type: application/json;charset=UTF-8

# Parameters

name required type sample description
mchId y String(30) 10000701 assigned by IOTPay
cardId y String(30) 604567999 assigned by merchant,must be unique
loginName y String(12) jack123 merchant's login name
channel y String PF_CC fixed value: PF_CC
returnUrl y String(200) redirect to this url after payment
sign y String(32) C380BEC2BFD727A4B6845133519F3AD6 Sign algorithm

each cardId can bind only one credit card, if one user need to bind more cards, use different cardId

# Response

name required type sample description
retCode y String SUCCESS or FAIL
retMsg y String
retData.redirectUrl y String if retCode=SUCCESS, merchant redirect to this url
retData.secureId y String used for sdk integration

# ReturnUrl parameters

name required type sample description
retCode y String SUCCESS or FAIL
retMsg n String

# Request URL for cc_directaddcard

Endpoint: https://ccapi.iotpaycloud.com/v3/cc_directaddcard

Reqeust method:

  • POST
  • Content-Type: application/json;charset=UTF-8

As an IOTPAY client or partner using this method of integration, your solution must demonstrate compliance to the Payment Card Industry Data Security Standard (PCI DSS) .

# Parameters

name required type sample description
mchId y String(30) 10000701 assigned by IOTPay
cardId y String(30) 604567999 assigned by merchant
cardNum y String 4223456789564532 card number
expiryDate n String 0725
holder y String card holder's name
cvv y String 786
loginName y String(12) jack123 merchant's login name
channel y String PF_CC fixed value: PF_CC
sign y String(32) C380BEC2BFD727A4B6845133519F3AD6 Sign algorithm

# Response

name required type sample description
retCode y String SUCCESS or FAIL
retMsg y String
retData y JSON if retCode=SUCCESS, card info returned

# retData contains card infomation:

name required type sample description
cardId y String
cardNum y String
expiryDate n String
holder y String
cvv y String

# Request URL for cc_querycard

Endpoint: https://ccapi.iotpaycloud.com/v3/cc_querycard

Reqeust method:

  • POST
  • Content-Type: application/json;charset=UTF-8

# Parameters

name required type sample description
mchId y String(30) 10000701 assigned by IOTPay
cardId y String(30) 604567999 assigned by merchant
sign y String(32) C380BEC2BFD727A4B6845133519F3AD6 Sign algorithm

# Response

name required type sample description
retCode y String SUCCESS or FAIL
retMsg y String
retData y JSON if retCode=SUCCESS, card info returned

# retData contains card infomation:

name required type sample description
cardId y String
cardNum y String
expiryDate y String
holder y String
cvv y String

# Request URL for purchasewithtoken

Endpoint: https://ccapi.iotpaycloud.com/v3/cc_purchasewithtoken

Reqeust method:

  • POST
  • Content-Type: application/json;charset=UTF-8

# Parameters

name required type sample description
mchId y String(30) 10000701 assigned by IOTPay
mchOrderNo y String(30) 1234567890abc assigned by merchant
mchUserId y String(30) 007 assigned by merchant
cardId y String(30) 604567999 assigned by merchant
amount y Int 1500 in cents
currency y String(3) CAD for now only CAD supported
loginName y String(12) jack123 merchant's login name
subject n String(64)
body n String(250)
clientIp n String(50) 192.77.33.56 consumer's ip address, for better transaction trace
sign y String(32) C380BEC2BFD727A4B6845133519F3AD6 Sign algorithm

# Response

name required type sample description
retCode y String SUCCESS or FAIL
retMsg y String
retData y JSON if retCode=SUCCESS, order detailed info returned

# retData contains order infomation:

name required type sample description
payOrderId y String SUCCESS or FAIL
mchId y String
mchOrderNo n String
originalOrderId y String original pay order id if payType=refund
amount y Int 100 in cents
currency y String CAD
payType y String pay or refund
refundable y Int 100 in cents
status y Int 2 2 or 3 means success
invoiceNum y String
paySuccTime y String 2021-04-07 19:44:51
cardNum y String 432567******2266
cardType y String V or M
expiryDate y String
authNum y String
transNum y String
channel y String PF_CC fixed value:PF_CC

# 数字钱包支付

Endpoint: https://ccapi.iotpaycloud.com/v3/cc_purchasewithwallet

Reqeust method:

  • POST
  • Content-Type: application/json;charset=UTF-8

# This API is for Apple Pay and Google Pay, contact us before integrating this API.

# Parameters

name required type sample description
mchId y String(30) 10000701 assigned by IOTPay
mchOrderNo y String(30) 1234567890abc assigned by merchant
amount y Int 1500 in cents
currency y String(3) CAD for now only CAD supported
walletType n String(250) “ApplePay” for ApplePay, “GooglePay” for Google Pay
walletData n String(250) The OEM Wallet data is generated by the mobile device authorized wallet
loginName y String(12) jack123 merchant's login name
subject n String(64)
body n String(250)
sign y String(32) C380BEC2BFD727A4B6845133519F3AD6 Sign algorithm

walletData must be base64encoded. For ApplePay, you must send the Apple payment token as received by the passkit. For Google Pay, you must send the payment token (paymentData.paymentMethodData.tokenizationData.token) as received by Google Pay API.

# Response

name required type sample description
retCode y String SUCCESS or FAIL
retMsg y String
retData y JSON if retCode=SUCCESS, order detailed info returned

# retData contains order infomation:

name required type sample description
payOrderId y String SUCCESS or FAIL
mchId y String
mchOrderNo n String
originalOrderId y String original pay order id if payType=refund
amount y Int 100 in cents
currency y String CAD
payType y String pay or refund
refundable y Int 100 in cents
status y Int 2 2 or 3 means success
invoiceNum y String
paySuccTime y String 2021-04-07 19:44:51
cardNum y String 432567******2266
cardType y String V or M
expiryDate y String
authNum y String
transNum y String
channel y String PF_CC fixed value:PF_CC

# 退款

Endpoint: https://ccapi.iotpaycloud.com/v3/cc_refund

Reqeust method:

  • POST
  • Content-Type: application/json;charset=UTF-8

# Parameters

name required type sample description
mchId y String(30) 10000701 assigned by IOTPay
mchRefundNo y String(30) R1234567890abc assigned by merchant
loginName y String(12) jack_chen assigned by merchant,equals to jobNo
refundAmount y Int 100 in cents
payOrderId y String(30)
sign y String(32) C380BEC2BFD727A4B6845133519F3AD6 Sign algorithm

# Response

name required type sample description
retCode y String SUCCESS or FAIL
retMsg y String
retData y JSON if retCode=SUCCESS, order detailed info returned

# 取消订单

Endpoint: https://ccapi.iotpaycloud.com/v3/cc_void

Reqeust method:

  • POST
  • Content-Type: application/json;charset=UTF-8

# Parameters

name required type sample description
mchId y String(30) 10000701 assigned by IOTPay
mchRefundNo y String(30) R1234567890abc assigned by merchant
loginName y String(12) jack_chen assigned by merchant,equals to jobNo
payOrderId y String(30)
sign y String(32) C380BEC2BFD727A4B6845133519F3AD6 Sign algorithm

# Response

name required type sample description
retCode y String SUCCESS or FAIL
retMsg y String
retData y JSON if retCode=SUCCESS, order detailed info returned

# 查询订单

Endpoint: https://ccapi.iotpaycloud.com/v3/cc_query

Reqeust method:

  • POST
  • Content-Type: application/json;charset=UTF-8

# Parameters

name required type sample description
mchId y String(30) 10000701 assigned by IOTPay
mchOrderNo y String(30) 1234567890abc assigned by merchant
payOrderId y String(30) 1000001
sign y String(32) C380BEC2BFD727A4B6845133519F3AD6 Sign algorithm

use either payOrderId or mchOrderNo, use one of them

# Response

name required type sample description
retCode y String SUCCESS or FAIL
retMsg y String
retData y JSON if retCode=SUCCESS, order detailed info returned

# SDKs and 文档

For iOS integration: iOS sdk
For Android integration: Android sdk
PHP and JS integration: Php sdk

# 示例和源代码

Simple purchase: demo Recurring purchase: demo source code download

上次更新: 7/27/2021, 3:02:32 PM