Feed Integration

Feed Integration Document

Introduction

iPOSpays is an omni-commerce payment gateway designed to empower Independent Sales Organizations (ISOs) and Independent Software Vendors (ISVs) by offering a wide range of payment channels, methods, devices, and verticals. Our platform provides ISOs and ISVs with the flexibility to cater to their merchants’ diverse needs, enhancing their ability to manage transactions efficiently and effectively.

Now, iPOSpays is providing one more enhancement called ‘Feed,’ which includes live tracking with POS, CloudPOS, Tap to Pay on iPhone, Tap to Pay on Android, etc.

Use Cases

For Independent Sales Organizations (ISOs)

If you have your own Customer Relationship Management (CRM) system, you can develop custom dashboards and reports for real-time monitoring and analysis of transactions.
Feed gives you more flexibility to manage transactions and settlements for your merchants.

For Independent Software Vendors (ISVs)

Integrate Feed into your software solutions to provide your clients with advanced features for tracking and reporting payments.
Offer real-time data validation and reporting, making your software more valuable.
Tailor Feed integration to each client’s specific needs, creating unique solutions that improve their experience.

For Merchants (Multi-Store)

If you have your own CRM, you can integrate Feed to view and manage all transactions from all your stores in your own CRM.
Manage your transactions and settlements with more flexibility to fit your business needs.

Prerequisites

Need to register with the iPOSpays portal with URL and authentication details.
Need to publish the endpoint where the Feed API will trigger the events.
Based on events, data needs to be validated by integrators.

Authentication Process

We have provided three types of authentication in Feed services:

Default - Deprecated
Basic Authentication
HMAC

Default: Deprecated

If the integrator is enabled by default, we will send the payload without any authentication. We will only require the event trigger URL as mandatory.

Basic Authentication

If the integrator is enabled with Basic Authentication, they need to provide the username (APIKey) and password (SecretKey) in the portal along with the Event Trigger URL. We will send the payload and authorization in base64 format.

Header	Data
Authentication	Basic (Base64 String)

HMAC

If the integrator is enabled with HMAC then we will provide the two options whether he can provide his own HMAC key and share with iPOSPays team or we will provide the Key generate button it will be used to generate the HMAC key that needs to be copied by the integrator.

Logic used for the HMAC Generation:

String param_data = param_value1|param_value2|param_value3|………|;

String final_data = secret_key|param_data;

String secureHash = generate_secure_hash_using_SHA512_and_secret_key;

Below is the Sample Code provided with Languages :

Transaction & Settlement

Transaction

Map<String, Object> fields = new TreeMap<>();
      fields.put("id", getOrDefault(feedFinalTxnPosting.getId()));
      fields.put("version", getOrDefault(feedFinalTxnPosting.getVersion()));
      fields.put("createdDt", getOrDefault(feedFinalTxnPosting.getCreatedDt()));
      fields.put("eventType", getOrDefault(feedFinalTxnPosting.getEventType()));
      fields.put("subEventType", getOrDefault(feedFinalTxnPosting.getSubEventType()));
      fields.put("requestType", getOrDefault(feedFinalTxnPosting.getRequestType()));
      fields.put("data", convertTxnDetailsToString(feedFinalTxnPosting.getData()));
 
 
      // Concatenate fields with | as delimiter
      String concatenatedString = fields.values().stream().map(value -> getOrDefault(value)).collect(Collectors.joining("|"));
 
 
      try {
          System.out.println("Before MAC Generation Value= " + concatenatedString);
          Mac sha256Hmac = Mac.getInstance(HMAC_SHA512_ALGORITHM);
          SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), HMAC_SHA512_ALGORITHM);
          sha256Hmac.init(secretKeySpec);
 
 
          byte[] hashBytes = sha256Hmac.doFinal(concatenatedString.getBytes(StandardCharsets.UTF_8));
          StringBuilder hexString = new StringBuilder();
          for (byte b : hashBytes) {
              String hex = Integer.toHexString(0xff & b);
              if (hex.length() == 1) {
                  hexString.append('0');
              }
              hexString.append(hex);
          }
          return hexString.toString();
      } catch (Exception e) {
          throw new RuntimeException("Error while generating HMAC-SHA256", e);
      }
 
public static String getOrDefault(Object value) {
      return value != null ? value.toString() : "";
  }

Settlement

Map<String, String> fields = new TreeMap<>();
      fields.put("id", feedFinalTxnPosting.getId() != null ? feedFinalTxnPosting.getId().toString() : "");
      fields.put("tpn", feedFinalTxnPosting.getTpn());
      fields.put("version", feedFinalTxnPosting.getVersion());
      fields.put("createdDt", feedFinalTxnPosting.getVersionCreatedDt());
      fields.put("eventType", feedFinalTxnPosting.getEventType());
      fields.put("subEventType", feedFinalTxnPosting.getSubEventType());
      fields.put("requestType", feedFinalTxnPosting.getRequestType());
      fields.put("batchNumber", feedFinalTxnPosting.getBatchNumber());
      fields.put("settlementDate", feedFinalTxnPosting.getSettlementDate());
      fields.put("settlementCount", String.valueOf(feedFinalTxnPosting.getSettlementCount()));
      fields.put("settlementAmount", String.valueOf(feedFinalTxnPosting.getSettlementCount()));
      fields.put("settlementTxnDetails", convertSettlementTxnDetailsToString(feedFinalTxnPosting.getSettlementTxnDetails()));
 
      // Concatenate fields with | as delimiter
      String concatenatedString = fields.values().stream()
              .collect(Collectors.joining("|"));
 
      try {
          Mac sha256Hmac = Mac.getInstance(HMAC_SHA512_ALGORITHM);
          SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), HMAC_SHA512_ALGORITHM);
          sha256Hmac.init(secretKeySpec);
 
          byte[] hashBytes = sha256Hmac.doFinal(concatenatedString.getBytes(StandardCharsets.UTF_8));
          StringBuilder hexString = new StringBuilder();
          for (byte b : hashBytes) {
              String hex = Integer.toHexString(0xff & b);
              if (hex.length() == 1) {
                  hexString.append('0');
              }
              hexString.append(hex);
          }
          return hexString.toString();
      } catch (Exception e) {
          throw new RuntimeException("Error while generating HMAC-SHA256", e);
      }

Transaction Types

BALANCE ENQ
INC AUTH
INC SALE
PREAUTH
REFUND
SALE
TICKET
TIP ADJUST
VOID
VOID PREAUTH
VOID REFUND
VOID SALE
VOID TICKET

Source Types

ECOM
TPOS
ITAP
TOPH

Event Types

Transaction
Settlement

Sub Events

Transaction

INC AUTH
INC SALE
PREAUTH
REFUND
SALE
TICKET
TIP ADJUST
VOID
VOID PREAUTH
VOID REFUND
VOID SALE
VOID TICKET

Settlement Batch

Closed Batch

Transaction Event -

Transaction Process Payload

Authentication with Basic Authentication

{
  "id": "6ea412fc-7181-4eb6-bb43-d07684ceff72",
  "eventType": "Transaction",
  "subEventType": "SALE",
  "requestType": "N",
  "signature": null,
  "version": "1.0",
  "createdDt": "2024-06-04 08:53:39",
  "data": {
    "dba": "Virat",
    "tpn": "342824380352",
    "tpnLabel": "",
    "deviceModel": "Cloud POS",
    "buildNumber": "10597",
    "maskedPan": "424242******4242",
    "rrn": "428209503179",
    "txName": "SALE",
    "transactionId": "41151701526138035220241008151118",
    "externalReferenceId": "0",
    "amount": 1.3,
    "baseAmount": 0.96,
    "totalFee": 0.0,
    "trueCashDiscountFee": 0.04,
    "commercialTaxAmount": 0.0,
    "localTaxAmount": 0.2,
    "stateTaxAmount": 0.1,
    "tipAmount": 0.0,
    "tipAdjAmount": 0.0,
    "posRequestDate": "2024-10-08",
    "posRequestTime": "11:11:18",
    "txTime": "05:41:18",
    "hostResponseDate": "2024-10-08",
    "txDuration": "0.902",
    "invoiceNumber": "000002",
    "hostResponseCode": "00",
    "responseText": "NO MATCH",
    "approvalCode": "TAS176",
    "tpnBatchNumber": "469",
    "cardLabel": "VISA",
    "sourceType": "ECOM",
    "posEntryMode": "100",
    "L2L3uploadflag": "No",
    "commMedia": null,
    "destType": "TSYS - QA",
    "email": "femeyey365@seosnaps.com",
    "phoneNumber": "+19898989898",
    "tagLabel": "Clerk ID,Table ID,Invoice No",
    "tagValue": "1,2,3",
    "chName": "Dhoni",
    "additionalDetails": "",
    "performedBy": "nowona1660@ipnuc.com",
    "cardInfo": "PERSONAL",
    "cardType": "CREDIT",
    "transactionType": "CREDIT",
    "cardCategory": "CLASSIC",
    "TermId": "75091651",
    "Mid": "888000003338",
    "description": "Description",
    "posMode": "COF",
    "minorChannel": "E-Commerce",
    "txDate": "2024-10-08",
    "cardToken": "7CB5968FACE5A7127CB5968FACE5A712390655538A3C6C73"
  },
  "headers": {
    "Authorization": "Basic Y2xudGtleV9SbkVfWGV5Y2lwVUVPd2VwRzF3UldBT1pDUXREQzdzblEwM",
    "Content-Type": "application/json"
  }
}

HMAC Sample Request

{
  "id": "2d4f1c3d-b1eb-4867-a168-a05e74ccd245",
  "eventType": "Transaction",
  "subEventType": "SALE",
  "requestType": "N",
  "signature": "df0047bae2540420e7645c6c323ee18a106008063fce8491b983031419429378558b74ffa16385470d7d36aa8bcc0d2a45a38e3f6d57410df90d9f970a0848c7",
  "version": "1.0",
  "createdDt": "2024-06-04 08:53:39",
  "data": {
    "dba": "Virat",
    "tpn": "342824380352",
    "tpnLabel": "",
    "deviceModel": "Cloud POS",
    "buildNumber": "10597",
    "maskedPan": "424242******4242",
    "rrn": "428209503926",
    "txName": "SALE",
    "transactionId": "35018720494938035220241008152830",
    "externalReferenceId": "0",
    "amount": 2.6,
    "baseAmount": 1.92,
    "totalFee": 0.0,
    "trueCashDiscountFee": 0.08,
    "commercialTaxAmount": 0.0,
    "localTaxAmount": 0.4,
    "stateTaxAmount": 0.2,
    "tipAmount": 0.0,
    "tipAdjAmount": 0.0,
    "posRequestDate": "2024-10-08",
    "posRequestTime": "11:28:30",
    "txTime": "05:58:30",
    "hostResponseDate": "2024-10-08",
    "txDuration": "1.26",
    "invoiceNumber": "000001",
    "hostResponseCode": "00",
    "responseText": "NO MATCH",
    "approvalCode": "TAS575",
    "tpnBatchNumber": "470",
    "cardLabel": "VISA",
    "sourceType": "ECOM",
    "posEntryMode": "100",
    "L2L3uploadflag": "No",
    "commMedia": null,
    "destType": "TSYS - QA",
    "email": "nowoa1660@ipnuc.comn",
    "phoneNumber": "+19898989898",
    "tagLabel": "Clerk ID,Table ID,Invoice No",
    "tagValue": "1,2,3",
    "chName": "Ak Arun",
    "additionalDetails": "",
    "performedBy": "femeyey365@seosnaps.com",
    "cardInfo": "PERSONAL",
    "cardType": "CREDIT",
    "transactionType": "CREDIT",
    "cardCategory": "CLASSIC",
    "TermId": "75091651",
    "Mid": "888000003338",
    "description": "Description",
    "posMode": "COF",
    "minorChannel": "E-Commerce",
    "txDate": "2024-10-08",
    "cardToken": "7CB5968FACE5A7127CB5968FACE5A712390655538A3C6C73"
  },
  "headers": {
    "Content-Type": "application/json"
  }
}

Field	Type	Description
id *	string	Unique id generated for each request
version *	string	Webhooks Integration Version
createdDt *	string	Webhooks Implemented Date in EST (yyyy-MM-dd HH:mm:ss)
eventType *	string	Transaction Event Type
subEventType *	string	Transaction type which was done by the Customer
requestType *	string	Type of Request whether to insert or update the existing record
signature	string	Mandatory only for HMAC enabled Merchants

Data Object

Field	Type	Description
dba	string	Merchant Registered as Doing Business as with Dejavoo
tpnLabel	string	Label name which provided while onboarding
deviceModel	string	Device Name where merchant is performing the transactions this data will received in Second posting which we are Additional Transaction Details as request Type as Update
tpnBatchNumber	string	Unique number will be generated to process the settlement of merchant transactions
externalReferenceId	string	Merchant unique transaction reference id.
hostResponseDate	string	Date time of transaction initiated
amount	double	(USD) Amount to be charged. Amount will sent in decimal format (example 10.01)
baseAmount fee	double	Basic amount In cents is $100.00
description	string	Description of the transaction this data will received in Second posting which we are Additional Transaction Details as request Type as Update
commercialTaxAmount	double	Tax Calculation for the Transaction if merchant Opted [Decimal format (Ex : 10.00)]
localTaxAmount	double	Local Tax Calculation for the Transaction if merchant Opted [Decimal format (Ex : 10.00)]
tipAmount	double	Tip Amount if Customer raised [Decimal format(Ex : 10.00)]
tipAdjAmount	double	TipAdjust calculations [Decimal format(Ex : 10.00)]
posRequestDate	string	Request Received from the POS Terminal Date in EST(yyyy-MM-dd)
posRequestTime	string	Request Received from the POS Terminal Time in EST(yyyy-MM-dd)
transactionDate	string	Transaction Initiated Date in EST(yyyy-MM-dd)
transactionTime	string	Transaction Initiated Time in EST(yyyy-MM-dd)
hostResponseDate	string	Transaction Date and Time in EST(yyyy-MM-dd)
txDuration	string	Transaction Duration for complete process this data will received in Second posting which we are Additional Transaction Details as request Type as Update
invoiceNumber	string	Transaction Number generated by Issuing Bank
hostResponseCode	string	Received from the Issuing Bank
responseText	string	Received from the Issuing Bank
approvalCode	string	Received from the Issuing Bank
buildNumber	string	Transaction Processing Build this data will received in Second posting which we are Additional Transaction Details as request Type as Update
cardLabel	string	Card Scheme
chName	string	Name of Cardholder this data will received in Second posting which we are Additional Transaction Details as request Type as Update
maskedPan	string	First 6 digits and Last 4 digits of card number
posMode	string	Transaction Initiated Process
channel(sourceType)	string	Transaction Initiated Channel
minorChannel	string	Request Received Channel based on Source this data will received in Second posting which we are Additional Transaction Details as request Type as Update
commMedia	string	Request Process Communication Mode this data will received in Second posting which we are Additional Transaction Details as request Type as Update
destType	string	Transaction Acceptor Name(processor)
email	string	Customer Email this data will received in Second posting which we are Additional Transaction Details as request Type as Update
phoneNumber	string	Customer Mobile Number this data will received in Second posting which we are Additional Transaction Details as request Type as Update
tagLabel	string	Additional Information provided in the Edit Parameters in registration process which will shown as additional Details in HPP and GHPP Page
tagValue	string	Additional Information provided in the Edit Parameters in registration process which will shown as additional Details in HPP and GHPP Page
performedBy	string	Customer Name who performed the transaction this data will received in Second posting which we are Additional Transaction Details as request Type as Update
cardInfo	string	Transaction Initiated by CardHolder or Others
cardType	string	Card Type used by the cardholder
transactionMode	string	Mode of the transaction
cardCategory	string	Card category based on the service provider of the Card Holder
additionalDetails	string	Future Use this data will received in Second posting which we are Additional Transaction Details as request Type as Update
termId	string	TerminalId registered by the Processor to Merchant
Mid	string	MerchantId provided by the processor to the Merchant
l2L3uploadflag	string	Whether transaction has performed with L2L3 Packet or not
transactionId	string	iPOSpay response unique transaction id
transactionType	string	Type of transactions to be processed.
tpn	string	TPN Registered with Dejavoo System
rrn	string	Unique Reference Number generated by Bank System
cardToken	string	This is used as Tokenized Card for complete the void and Refund transactions using iposTransact API
totalFee	double	Total Fee Amount, Decimal format(Ex : 10.00)
trueCashDiscountFee	double	Discount fee if customer has using the debit card transactions , Decimal format(Ex : 10.00)
stateTaxAmount	double	State Tax Calculation for the Transaction if merchant Opted , Decimal format(Ex : 10.00)
posEntryMode	string	PosEntryMode

Settlement Event

This event provided the settlement of the merchants with transaction details which got settled on the batch. It will be easy for an integrator to find the transaction with count.

Sample Request Below

Basic Authentication Sample Payload

{
  "id": "f5b15dac-359f-439d-8977-a0226c467dc7",
  "eventType": "Settlement",
  "subEventType": "ClosedBatch",
  "requestType": "HTTPS",
  "signature": null,
  "version": "1.0",
  "versionCreatedDt": "2024-06-04 08:53:39",
  "batchNumber": "469",
  "settlementDate": "2024-10-08",
  "settlementCount": 2,
  "settlementAmount": 2.6,
  "tpn": "342824380352",
  "settlementTxnDetails": [
    {
      "txnDate": "2024-10-08 04:06:18",
      "transactionType": "SALE",
      "transactionId": "38939820834338035220241008133618",
      "txnAmount": 1.3
    },
    {
      "txnDate": "2024-10-08 05:41:18",
      "transactionType": "SALE",
      "transactionId": "41151701526138035220241008151118",
      "txnAmount": 1.3
    }
  ],
  "headers": {
    "Authorization": "Basic Y2xudGtleV9SbkVfWGV5Y2lwVUVPd2VwRzF3UldBT1pDUXREQzdzblEwM",
    "Content-Type": "application/json"
  }
}

HMAC Sample Payload

{
  "id": "46f69dec-fce4-444c-ba7b-64a11b9357a3",
  "eventType": "Settlement",
  "subEventType": "ClosedBatch",
  "requestType": "HTTPS",
  "signature": "464ebd627992eb451b8d8a4075d6869c685e6ce7552535318a607f7ee68cccde0856fc78ae9e84f88778c4f935b4953cc61764e3f4152032d1c0e12dd5280ff0",
  "version": "1.0",
  "versionCreatedDt": "2024-06-04 08:53:39",
  "batchNumber": "470",
  "settlementDate": "2024-10-08",
  "settlementCount": 2,
  "settlementAmount": 3.9,
  "tpn": "342824380352",
  "settlementTxnDetails": [
    {
      "txnDate": "2024-10-08 05:58:30",
      "transactionType": "SALE",
      "transactionId": "35018720494938035220241008152830",
      "txnAmount": 2.6
    },
    {
      "txnDate": "2024-10-08 06:00:28",
      "transactionType": "SALE",
      "transactionId": "64838090846138035220241008153028",
      "txnAmount": 1.3
    }
  ],
  "headers": {
    "Content-Type": "application/json"
  }
}

Field	Type	Description
id *	string	Unique id generated for each request
version *	string	Webhooks Integration Version
createdDt *	string	Version Registered Date in EST (yyyy-MM-dd HH:mm:ss)
eventType *	string	Transaction Event Type
subEventType *	string	Transaction type which was done by the Customer
requestType *	string	Type of Request whether to insert or update the existing record
signature	string	Mandatory only for HMAC enabled Merchants
settlementAmount	double	Total Amount Settled for that TPN in Batch , Decimal format(Ex : 10.00)
batchNumber	string	Settled Batch Number it will unique
settlementDate	string	Settled Batch Date and Time in EST format in EST (yyyy-MM-dd HH:mm:ss)
SettledTxnCount	long	Total Txn’s Settled with Batch
tpn	string	TPN Registered with Dejavoo System

SettlementTxnDetails

Field	Type	Description
txnDate	string	Transaction Initiated Date and Time in EST (yyyy-MM-dd HH:mm:ss)
transactionId	string	iPOSpays response unique transaction id
transactionType	string	Type of transactions to be processed.
txnAmount	double	Transaction Amount , Decimal format(Ex : 10.00)

DvPayLite iPOSpays WooCommerce Extension