Commerce Connect - API Document
STEPS FOR INTEGRATION
When you integrate with Commerce Connect, the customer will be redirected from your merchant website to the Commerce Connect payment page. After completion of the transaction, Commerce Connect will direct the customer back to the merchant website.
Commerce Connect is a single integration which covers the following scenarios:
- HOSTED PAGE INTEGRATION
- MERCHANT PAYMENT MODE INTEGRATION
- MERCHANT PAYMENT MODE BANK OR WALLET INTEGRATION
- MERCHANT PAYMENT MODE CARD INTEGRATION
- MERCHANT_LINK_PAYMENT_MODE_INTEGRATION
- FirstConnectAPI - https://test.fdconnect.com/FirstPayL2Services/
- MERCHANT_URL- Merchant application hosted Url
- resultURL - MERCHANT_URL/PATH_TO_REDIRECTION_OF_SUCCESSFUL_PAYMENT
- ClientTransactionId/clientTransactionId -Random id generated by merchant system
- merchantid - Unique id given to merchant by FDConnect used generating token id , getHmacvalue
- keyvalue, ivvalue - provided while contract signing for encryption
- hostedids - provided while contract signing used for generating token id
- tokendata - This changes according to Merchant Payment Types. There are four different format ,details of data listed
Parameters
Integration Type Name | Integration Type Description | Additional Parameters in getToken API |
---|---|---|
Complete payment experience at Commerce Connect |
|
|
Payment mode selection at Merchant end |
|
|
Bank/Wallet selection at Merchant end but Card capture at Commerce Connect |
|
|
Bank/Wallet and Card details capturing at Merchant end |
|
|
Link Pay integration |
|
|
- When you submit your transaction request to Commerce Connect, you need to submit a merchant transaction ID as part of the request. This ID can be used by you as a universal reference number for all transaction requests submitted by you.
- Merchant transaction ID acts as a "merchant reference number". We strongly recommend that you maintain uniqueness of this ID, to avoid confusion and conflicts while retrieving transaction details subsequently.
- When your customer clicks the "Pay" button on the Commerce Connect payment page, a unique transaction ID is assigned to the transaction.
Format of Token Datas
Make sure you are ready with following json data before making api calls based on your Merchant Payment Types
Hosted Page Integration
1. Request Parameters for Transaction Request
Parameter Name | Description | Optional/ Mandatory | Sample value |
---|---|---|---|
merchantId | This is the unique id assigned to the merchant at the time of on boarding in Commerce Connect system. | @Mandatory | M123456789 |
key | First Pay would assign a unique key to the merchant. This will part of sharing the integration kit with the merchant. | @Mandatory | |
iv | IV value is associated with the key shared with the merchant. | @Mandatory | |
apiURL | API URL | @Mandatory | |
merchantTxnId | Merchant needs to pass this value for every transaction request and this can be referred for future interaction. It must be unique for every transaction. | @Mandatory | TR1234 |
merchantId | This is the unique id assigned to the merchant at the time of on boarding in Commerce Connect system. | @Mandatory | M123456789 |
resultURL | This is the URL in which transaction response has to be posted back with some set of parameters once the transaction is complete. | @Mandatory | http://firstdata/ result.jsp |
transactionType | This has to be “sale” in this case. | @Mandatory | sale |
paymentMethodType | This value will be passed only if the payment selection is done at merchants end. | Conditional | creditcard/debit card/netbanking /wallet/upi |
amount | This is the unique id assigned to the merchant at the time of on boarding in Commerce Connect system. This is the payment amount. | @Mandatory | 100.00 |
currencyCode | This is the 3 digit currency code as defined in the master DB. | @Mandatory | INR |
hostedId | This will be passed by the merchant if the hosted IDs for the saved card are managed by the merchant for future transactions. | @Optional | KRS1220ESFFTR849 |
customerId | This has to be the customer id if the merchant wants to pass. | @Optional | CA12345 |
firstName | First Name of customer | @Optional | Abc |
lastName | Last Name of customer | @Optional | Xyz |
middleName | Middle Name | @Optional | Tbc |
suffix | Suffix to be added along with the name | @Optional | Mr/Mrs/Miss |
emailId | Customer email address. | Optional | test@gmail.com |
mobileNo | Customer phone number | Optional | Optional |
billStreet1 | billStreet1 | Optional | Aaaa |
billStreet2 | Customer billing address2 | Optional | Bbbb |
billCity | Customer billing city | Optional | Mumbai |
billState | Customer billing state | Optional | Maharashtra |
billCountry | Customer billing country | Optional | India |
billZipcode | Customer billing zip code | Optional | 400001 |
shipStreet1 | Customer billing address1 | Optional | Aaaa |
shipStree2 | Customer billing address2 | Optional | Bbbb |
shipCity | Customer billing city | Optional | Mumbai |
shipState | Customer billing state | Optional | Maharashtra |
shipCountry | Customer billing country | Optional | India |
shipZipcode | Customer billing zip code | Optional | 400001 |
productData | This needs to be passed if single transaction is initiated for multiple products with different price. The sum of price of all the products will be equal to the total transaction amount of the request. | Optional | |
airlineData | This field is for the merchants who captures airline booking transactions. | Optional | |
integrationType | This filed indicates integration type. | Conditional | Refer General. 2. Integration types |
cardData | This field is required if merchant captures the card detail in its own page and pass as part of transaction request. | Conditional | Card no, expiry month, expiry year, |
bankData | This field is required if merchant wants to capture the bank selection at its end. | Conditional | bankId, bankName |
walletData | This field is required if merchant wants to capture the wallet selection at its end. | Conditional | walletId, walletName |
upiData | This field is required if merchant wants to capture the UPI details (VPA) at its end. | Conditional | abc@icick |
configId | In case of Link pay this is mandatory. Page Id shared by Fiserv. | Conditional | |
sessionTokenExpir eDate | In case of Link pay this is mandatory. Link expiry date (dd-mm-yyyy). | Conditional | |
udf1 | Optional | ||
udf2 | User defined field | Optional | |
udf3 | User defined field | Optional | |
udf4 | User defined field | Optional | |
udf5 | User defined field | Optional | |
udf6 | User defined field | Optional | |
udf7 | User defined field | Optional | |
udf8 | User defined field | Optional | |
udf9 | User defined field | Optional | |
udf10 | User defined field | Optional |
Parameter Name | Description | Sample value |
---|---|---|
sessionToken | This is the unique id assigned to the transaction. | RDDI27SEPEHZFDR3 |
errorCode | Error code | 400 BAD_REQUEST |
errorMessage | Error description | FPDR4013:Merchant_ txn_id cannot be blank. |
udf1 | User defined field | |
udf2 | User defined field | |
udf3 | User defined field | |
udf4 | User defined field | |
udf5 | User defined field | |
udf6 | User defined field | |
udf7 | User defined field | |
udf8 | User defined field | |
udf9 | User defined field | |
udf10 | User defined field |
Sample code: Hosted Page Integration
{
"resultURL": MERCHANT_URL+"/merchantSuccessPage.jsp",
"transactionDetails": {
"clientTransactionId": "clientTransactionId",
"transactionType": "sale",
"amount": amount,
"currencyCode": "INR"
},
"customerDetails": {
"customerId": "ABC1234",
"hostedIds": [
"KRS1220ESFFTR8490"
],
"name": {
"firstName": "ABC",
"lastName": "XYZ",
"middleName": "DEF",
"suffix": "ADX"
},
"mobileNo": "1234567890",
"emailId": "abc@gmail.com",
"billingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai Nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": "400000"
},
"shippingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": "400000"
}
},
"productData": {
"productId": "P123",
"productDescription": "Water Bottle",
"quantity": 1,
"price": "100",
"txnAmount": "120",
"shippingFee": "20",
"discountPrice": "0"
},
"paymentMethodType":"CREDITCARD",
"integrationType":"HOSTED_PAGE_INTEGRATION "
};
Merchant Payment Mode Integration
Sample code: Merchant Payment Mode Integration
{
"resultURL": MERCHANT_URL+"/merchantSuccessPage.jsp",
"transactionDetails": {
"clientTransactionId": "clientTransactionId",
"transactionType": "sale",
"amount": amount,
"currencyCode": "INR"
},
"customerDetails": {
"customerId": "ABC1234",
"hostedIds": [
"KRS1220ESFFTR8490"
],
"name": {
"firstName": "ABC",
"lastName": "XYZ",
"middleName": "DEF",
"suffix": "ADX"
},
"mobileNo": "1234567890",
"emailId": "abc@gmail.com",
"billingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai Nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": "400000"
},
"shippingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": "400000"
}
},
"productData": {
"productId": "P123",
"productDescription": "Water Bottle",
"quantity": 1,
"price": "100",
"txnAmount": "120",
"shippingFee": "20",
"discountPrice": "0"
},
"paymentMethodType":"CREDITCARD",
"integrationType":"MERCHANT_PAYMENT_MODE_INTEGRATION "
};
Merchant Payment Mode Bank Wallet Integration
Sample code: Merchant Payment Mode Bank Wallet Integration
{
"resultURL": MERCHANT_URL+"/merchantSuccessPage.jsp",
"transactionDetails": {
"clientTransactionId": "clientTransactionId",
"transactionType": "sale",
"amount": amount,
"currencyCode": "INR"
},
"customerDetails": {
"customerId": "ABC1234",
"hostedIds": [
"KRS1220ESFFTR8490"
],
"name": {
"firstName": "ABC",
"lastName": "XYZ",
"middleName": "DEF",
"suffix": "ADX"
},
"mobileNo": "1234567890",
"emailId": "abc@gmail.com",
"billingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai Nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": "400000"
},
"shippingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": "400000"
}
},
"productData": {
"productId": "P123",
"productDescription": "Water Bottle",
"quantity": 1,
"price": "100",
"txnAmount": "120",
"shippingFee": "20",
"discountPrice": "0"
},
"paymentMethodType":"WALLET",
"walletData" : {
"firstPayWalletCode": "FRECHG",
"firstPayWalletName": "Freecharge"
},
"integrationType":"MERCHANT_PAYMENT_MODE_BANKORWALLET_INTEGRATION"
};
Merchant Payment Mode Card Integration
Sample code: Merchant Payment Mode Card Integration
{
"resultURL": MERCHANT_URL+"/merchantSuccessPage.jsp",
"transactionDetails": {
"clientTransactionId": "clientTransactionId",
"transactionType": "sale",
"amount": amount,
"currencyCode": "INR"
},
"customerDetails": {
"customerId": "ABC1234",
"hostedIds": [
"KRS1220ESFFTR8490"
],
"name": {
"firstName": "ABC",
"lastName": "XYZ",
"middleName": "DEF",
"suffix": "ADX"
},
"mobileNo": "1234567890",
"emailId": "abc@gmail.com",
"billingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai Nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": "400000"
},
"shippingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": "400000"
}
},
"productData": {
"productId": "P123",
"productDescription": "Water Bottle",
"quantity": 1,
"price": "100",
"txnAmount": "120",
"shippingFee": "20",
"discountPrice": "0"
},
"paymentMethodType":"CREDITCARD",
"cardData" : {
"cardNumber" : "4035874000424977",
"expMonth" : "12",
"expYear" : "24",
"cVV" : "123",
"nameOnCard" : "Vishal Utekar",
"vaultCard" : false
},
"paymentMethodType":"CREDITCARD",
"integrationType":"MERCHANT_PAYMENT_MODE_CARD_INTEGRATION"
};
Sample code: MERCHANT_LINK_PAYMENT_MODE_INTEGRATION
Result will be in following format
{
sessionTokenId: 'XYXYXYXYXYXYXYXY',
linkURL: 'http://tinyurl.com/uxyxyx'
}
{
"resultURL": MERCHANT_URL+"/merchantSuccessPage.jsp",
"transactionDetails": {
"clientTransactionId": "clientTransactionId",
"transactionType": "sale",
"amount": amount,
"currencyCode": "INR"
},
"customerDetails": {
"customerId": "ABC1234",
"hostedIds": [
"KRS1220ESFFTR8490"
],
"name": {
"firstName": "ABC",
"lastName": "XYZ",
"middleName": "DEF",
"suffix": "ADX"
},
"mobileNo": "1234567890",
"emailId": "abc@gmail.com",
"billingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai Nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": "400000"
},
"shippingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": "400000"
}
},
"productData": {
"productId": "P123",
"productDescription": "Water Bottle",
"quantity": 1,
"price": "100",
"txnAmount": "120",
"shippingFee": "20",
"discountPrice": "0"
},
"paymentMethodType":"CREDITCARD",
"linkPaymentData":{
"sessionTokenExpireDate":"26-02-2020",
"configId":"PageId2019080820099"
},
"integrationType":"MERCHANT_LINK_PAYMENT_MODE_INTEGRATION"
};
SDK integration sample code :
• Add npm package to your nodejs project via npm install PATH_TO_SDK_LOCAL.
• Sample code
Javascript sample code
var express = require('express');
var router = express.Router();
var FDConnectSDK = require("fd-connect-sdk");
router.get('/', function(req, res, next) {
let MERCHANT_URL = "your url goes here" ;
let clientTransactionId = "323463636234HGR12dsfdssdfsfsfrew";
let amount =1;
let tokenData = {
"resultURL": MERCHANT_URL+"/merchantSuccessPage.jsp",
"keyValue" : "CNy+HimxmI4PmrJWrpLarBfbo6jIY/CHcezg2VQ8u5o=",
"ivValue":"9T4hd3Nx0b0sMgYuyWLCTg==",
"transactionDetails": {
"merchantID" : "470000000332260",
"clientTransactionId": clientTransactionId,
"transactionType": 'sale',
"amount": amount,
"currencyCode": 'INR'
},
"customerDetails": {
"customerId": "ABC1234",
"hostedIds": [
"KRS1220ESFFTR8490"
],
"name": {
"firstName": "ABC",
"lastName": "XYZ",
"middleName": "DEF",
"suffix": "ADX"
},
"mobileNo": 1234567890,
"emailId": "abc@gmail.com",
"billingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai Nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": 400000
},
"shippingAddress": {
"street1": "Ghodbandar Rode",
"stree2": "Sai nagar",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipcode": 400000
}
},
"productData": {
"productId": "P123",
"productDescription": "Water Bottle",
"quantity": 1,
"price": 100,
"txnAmount": 120,
"shippingFee": 20,
"discountPrice": 0
}
};
let fdConnectSDK = new FDConnectSDK(tokenData); // you should pass valid data types else error will be thrown
let sessionID = fdConnectSDK.getSessionId().then((response) => {
if(response.errorCode){
res.send(`SessionID , ${response.errorMessage}`)
}else {
res.send(`SessionID , ${response.sessionTokenId}`)
}
}).catch((error) => {
res.send(`Error , ${error}`)
});
});
module.exports = router;
Now you have sessionTokenId and configId which helps you to redirect to https://test.fdconnect.com/Pay/?sessionToken=XXXX&configId=YYYY so user redirected to payment where he can enter payment details and pay you .After successful payment , page will be redirected to resultURL you provided.
TRANSACTION REFUND API
Request Type | Refund API Call(Server2Server call) |
---|---|
Description | This API used do the refund transaction. |
Event/Trigger of Request Type | This is Server2Server call. Merchant can initiate whenever he required. |
List of Parameters in Request & Response |
1. Request Parameters for Refund Transaction
Parameter Name | Description | Optional/ Mandatory | Sample value |
---|---|---|---|
merchantId | This is the unique id assigned to the merchant at the time of on boarding in Commerce Connect system. | Mandatory | M123456789 |
key | First Pay would assign a unique key to the merchant. This will part of sharing the integration kit with the merchant. | Mandatory | |
iv | IV value is associated with the key shared with the merchant. | Mandatory | |
merchantTxnId | Merchant needs to pass this value for every transaction request and this can be referred for future interaction. It must be unique for every transaction. | Optional | |
apiURL | This is the url in which transaction request has to be posted and receives response. | Mandatory | https://test.fdconnect.com/FirstPayL2Se rvices/refundTxnDetail |
fdcTxnId | This transaction id is returned by Commerce Connect to merchant after successful/failure of the transaction. The same need to pass to get the transaction status. | Mandatory | |
refundAmount | Amount to refund | Mandatory |
2. Response Parameters for Refund Transaction
Parameter Name | Description | Sample value |
---|---|---|
merchantId | This is the unique id assigned to the merchant at the time of on boarding in Commerce Connect system | M123456789 |
fdcTxId | This transaction id is returned by Commerce Connect to merchant after successful/failure of the transaction. The same need to pass to get the transaction status. | |
fdcRefundTxnId | This refund transaction id is returned by Commerce Connect to merchant after successful/failure of the transaction. The same need to pass to get the transaction status. | |
txnStatus | Transaction Status description | |
txnStatusCode | Transaction Status code | 399 |
amount | Refund amount | |
txDate | Transaction date | |
currencyCode | Transaction currency code | |
Balance | Balance amount after refund | |
cardBrand | Card brand | @mdo |
bankCode | Bank Code | |
errorCode | Error code | |
errorMessage | Error description |
Sample Code
TRANSACTION INQUIRY API
Request Type | Transaction Inquiry API Call(Server2Server call) |
---|---|
Description | This API used for transaction inquiry. In response it will return SALE and REFUND transactions based on Commerce Connect transaction Id. |
Event/Trigger Request Type | This is Server2Server call. Merchant can initiate whenever he required. |
List of Parameters in Request & Response |
1. Request Parameters for Transaction Inquiry
Parameter Name | Description | Optional/Mandatory | Sample value |
---|---|---|---|
merchantId | This is the unique id assigned to the merchant at the time of on boarding in Commerce Connect system. | Mandatory | M123456789 |
key | First Pay would assign a unique key to the merchant. This will part of sharing the integration kit with the merchant. | @Mandatory | FD0001 |
iv | IV value is associated with the key shared with the merchant. | @Mandatory | Srffhjtcv1345nk |
merchantTxnId | Merchant needs to pass this value for every transaction request and this can be referred for future interaction. It must be unique for every transaction. | @Mandatory | TR1234 |
apiURL | This is the URL in which transaction request has to be posted and recieves response. | @Mandatory | https://test.fdconnect.com/FirstPayL2Services/getTxnInquiryDetail |
2. Response Parameters for Transaction Inquiry
Parameter Name | Description | Sample value |
---|---|---|
fdcRefundTxnId | This transaction id is returned by Commerce Connect to merchant after successful/failure refund transaction. The same need to pass to get the transaction status. | M123456789 |
fdcTxnId | This transaction id is returned by Commerce Connect to merchant after successful/failure of the transaction. The same need to pass to get the transaction status. | |
merchantId | This is the unique id assigned to the merchant at the time of on boarding in Commerce Connect system. | |
merchantId | This is the unique id assigned to the merchant at the time of on boarding in Commerce Connect system. | |
merchantTxnId | Merchant needs to pass this value for every transaction request and this can be referred for future interaction. It must be unique for every transaction. | |
baseAmount | Transaction amount | |
txnStatus | Status of the transaction | |
txnDescription | Transaction description | |
txnDescription | Transaction description | |
txnType | Transaction type like sale/refund | |
channel | Transaction channel | |
currency | Transaction Currency Code | |
txnDate | Transaction | |
balanceAmount | Available amount for refund |
Sample Code
STANDING INSTRUCTION TRANSACTION API
Request Type | Standing Instruction subsequent API Call(Server2Server call) |
---|---|
Description | This API used do the SI subsequent transactions. |
Event/Trigger of Request Type | This is Server2Server call. Merchant can initiate whenever he required. |
List of Parameters in Request & Response |
1. Request Parameters for Standing Instruction Transaction
Parameter Name | Description | Optional/ Mandatory | Sample value |
---|---|---|---|
merchantId | This is the unique id assigned to the merchant at the time of on boarding in Commerce Connect system. | Mandatory | M123456789 |
key | First Pay would assign a unique key to the merchant. This will part of sharing the integration kit with the merchant. | Mandatory | |
iv | IV value is associated with the key shared with the merchant | Mandatory | |
merchantTxnId | Merchant needs to pass this value for every transaction request and this can be referred for future interaction. It must be unique for every transaction. | Mandatory | https://test.fdconnect.com/FirstPayL2Services/refundTxnDetail |
fdcTxnId | This transaction id is returned by Commerce Connect to merchant after successful/failure of the transaction. The same need to pass to get the transaction status. | Mandatory | |
txnAmount | Transaction Amount | Mandatory | |
hostedId | |||
currencyCode | |||
customerId |
2. Response Parameters for Standing Instruction Transaction
Parameter Name | Description | Sample value |
---|---|---|
merchantId | This is the unique id assigned to the merchant at the time of on boarding in Commerce Connect system. | |
resultUrl | This is the url in which transaction response is done. | |
fdcTxnId | This transaction id is returned by Commerce Connect to merchant after successful/failure of the transaction. The same need to pass to get the transaction status. | |
transactionType | Transaction Type like Sale | |
baseCurrency | Base Currency | |
transactionCurrency | Transaction Currency | |
baseAmount | Base Amount | |
transactionAmount | Transaction Amount | |
balanceAmount | Amount available for withdraw | |
paymentMethod | Payment Method | |
convFee | Convenience fee applied on base amount | |
taxFee | Otto | |
transactionStatus | Transaction Status | |
transactionStatusDescription | ||
transactionDateTime | Transaction Date and Time | |
udf1 | User defined field | |
udf2 | User defined field | |
udf3 | User defined field | |
udf4 | User defined field | |
udf5 | User defined field | |
udf6 | User defined field | |
udf7 | User defined field | |
udf8 | User defined field | |
udf9 | User defined field | |
udf10 | User defined field | |
errorCode | Error code | |
errorMessage | Error description |
Download
Commerce Connect Integration Pack | |
---|---|
nodeJSKit | Integration Pack Please Sign In to download |