Redirected Integration
Let customers pay using a secure payment link that’s hosted by IOT Pay.
How It Works
Endpoint
https://ccapi.iotpaycloud.com/v3/cc_purchase
Method
POST
Header
Content-Type: application/json;charset=UTF-8
Redirect Purchase Guide
! Tip
After you receive access credentials (merchant id, login name, merchant key). You can step through the demo Redirect Purchase which may help you when going through the documentation.
1. Request to Endpoint with format below
Request
| 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 |
| loginName | y | String(12) | jack123 | merchant's login name |
| subject | n | String(64) | ||
| body | n | String(250) | ||
| channel | y | String | PF_CC | PF_CC or UPI_EX |
| notifyUrl | y | String(200) | get notify when success | |
| returnUrl | y | String(200) | https://example.com | redirect to this url after payment |
| sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Sign algorithm |
2. Redirect to `redirectUrl` in response below to IOTPay payment page
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 embedded SDK integration only |
Sample redirect url:
https://ccapi.iotpaycloud.com/cc/purchase?key={{secureId}}
3. After customer submit IOTPay form, payment page will automatically redirect to merchant supplied `returnUrl` with following parameters
Sample return url: https://example.com/?retCode=SUCCESS&status=2
| 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 |
NotifyUrl message(post request in json format)
At the same time, IOTPay will post to the merchant supplied notifyUrl with the following body:
| name | required | type | sample | description |
|---|---|---|---|---|
| payOrderId | y | String | PC20240101005605740403580191 | generated by IOTPay |
| mchId | y | String | 10000701 | assigned by IOTPay |
| mchOrderNo | y | String | 1234567890abc | assigned by merchant |
| originalOrderId | y | String | original pay order id if payType=refund | |
| amount | y | Int | 1500 | in cents |
| currency | y | String | CAD | only 'CAD' supported |
| payType | y | String | pay or refund | |
| refundable | y | Int | 1500 | in cents |
| status | y | Int | 2 | 2 or 3 means success |
| paySuccTime | y | String | 2021-04-07 19:44:51 | time stamp for the moment when the payment succeeded |
| cardNum | y | String | 432567******2266 | card number of the card used for the purchase |
| expiryDate | y | String | 0725 | expiry date of the card used for the purchase |
| invoiceNum | y | String | ||
| authNum | y | String | ||
| transNum | y | String | ||
| channel | y | String | PF_CC | PF_CC or UPI_EX |
| sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Sign algorithm |
4. (Recommended) Merchant queries transaction with returned `payOrderId` and handle response accordingly
For details see Query Transaction
Card Tokenize Guide
IOTPay provides encryption and tokenization services with a secure data vault typically used to store payment card Primary Account Numbers in a PCI-DSS compliant manner. IOTPay generates a unique and random token value to be used by your application instead of a clear or encrypted PAN, potentially reducing your PCI scope considerably.
! Tip
After you receive access credentials (merchant id, login name, merchant key). You can step through the demo Card Tokenize which may help you when going through the documentation.
Endpoint - Add Card
https://ccapi.iotpaycloud.com/v3/cc_addCard
Method
POST
Header
Content-Type: application/json;charset=UTF-8
1. Request to Endpoint with format below
Request
| Name | Required | Type | Sample | Description |
|---|---|---|---|---|
| mchId | y | String(30) | 0000701 | 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 | PF_CC or UPI_EX |
| returnUrl | y | String(200) | redirect to this url after card is added | |
| sign | y | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | Sign algorithm |
Please note
Each cardId can bind only one credit card, if one user need to bind more cards, use different cardId
2. Redirect to `redirectUrl` in response to see IOTPay card form
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 embedded SDK integration only | |
| retData.channel | y | String | PF_CC | PF_CC or UPI_EX |
Sample redirect url: https://ccapi.iotpaycloud.com/cc/addcard?key={{secureId}}
3. After customer submit IOTPay form, payment page will automatically redirect to merchant supplied `returnUrl` with following parameters
Sample return url: https://example.com/?retCode=SUCCESS
| name | Required | type | sample | description |
|---|---|---|---|---|
| retMsg | y | String | cardId already exist | Message that show why the request had failed |
| retCode | y | String | SUCCESS / FAIL |
4. You can now use the cardId for future purchases
If you need to review the card information, you can call the QueryCard endpoint.
To purchase with the tokenized card, please use the PurchaseWithToken endpoint.