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
  • Basic Authentication
  • HMAC

Default:

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.

HeaderData
AuthenticationBasic (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 :

  1. BALANCE ENQ
  2. INC AUTH
  3. INC SALE
  4. PREAUTH
  5. REFUND
  6. SALE
  7. TICKET
  8. TIP ADJUST
  9. VOID
  10. VOID PREAUTH
  11. VOID REFUND
  12. VOID SALE
  13. VOID TICKET
  • Source Types :
  1. ECOM
  2. TPOS
  3. ITAP
  4. TOPH
  • Event Types :
  1. Transaction
  2. Settlement

Sub Events :

  • Transaction :
  1. INC AUTH
  2. INC SALE
  3. PREAUTH
  4. REFUND
  5. SALE
  6. TICKET
  7. TIP ADJUST
  8. VOID
  9. VOID PREAUTH
  10. VOID REFUND
  11. VOID SALE
  12. VOID TICKET

Settlement Batch

Closed Batch

  • Transaction Process Payload :
{
  "id": "bc71777f-3f7b-4197-9d72-7724f9e9aaea",
  "version": "1.0",
  "createdDt": "2024-06-04 08:53:39",
  "eventType": "Transaction",
  "subEventType": "Sale/Void/Refund/Reversal/PreAuth/Ticket/IncrementalAuth/PartialRefund",
  "requestType": "N",
  "signature": "",
  "data": {
    "dba": "Sritha Dev",
    "tpn": "381723650380",
    "tpnLabel": "",
    "deviceModel": "P3",
    "buildNumber": "0",
    "maskedPan": "424242******4242",
    "rrn": "420413501305",
    "txName": "SALE",
    "transactionId": "53155708937265038020240701112825",
    "externalReferenceId": "0",
    "amount": 6.24,
    "baseAmount": 6,
    "totalFee": 0.24,
    "trueCashDiscountFee": 0,
    "commercialTaxAmount": 0,
    "localTaxAmount": 0,
    "stateTaxAmount": 0,
    "tipAmount": 0,
    "tipAdjAmount": 0,
    "posRequestDate": "2024-07-23",
    "posRequestTime": "03:44:58",
    "txDate": "2024-07-23 03:44:58",
    "txTime": "03:44:58",
    "hostResponseDate": "2024-07-23",
    "txDuration": "12.15",
    "invoiceNumber": "000002",
    "hostResponseCode": "00",
    "responseText": "APPROVAL TAS637 ",
    "approvalCode": "TAS637",
    "tpnBatchNumber": "977",
    "cardLabel": "VISA",
    "sourceType": "ECOM",
    "posEntryMode": "010",
    "commMedia": null,
    "destType": "TSYS - QA",
    "email": "xeseje4608@tupanda.com",
    "phoneNumber": "+19898989898",
    "tagLabel": null,
    "tagValue": null,
    "chName": "Dhoni",
    "additionalDetails": "",
    "performedBy": "femeyey365@seosnaps.com",
    "transactionType": "CREDIT",
    "description": null,
    "posMode": "MANUAL",
    "minorChannel": "CUSTOMER-PAYMENT",
    "cardInfo": "PERSONAL",
    "cardType": "CREDIT",
    "cardCategory": "CLASSIC",
    "termId": "75091651",
    "mid": "888000003338",
    "l2L3uploadflag": "No"
  }
}
ObjectsDescription
Id (M) * Unique id generated for each request
Version (M) * Webhooks Integration Version
createdDt (M) * Webhooks Implemented Date in EST (yyyy-MM-dd HH:mm:ss)
eventType (M) * Transaction Event Type
subEventType (M) * Transaction type which was done by the Customer
requestType (M) * Type of Request whether to insert or update the existing record
signature (O) * Mandatory only for HMAC enabled Merchants
  • Data Object
ObjectsDescription
DBA(dba) Merchant Registered as Doing Business as with Dejavoo
tpnLabel Label name which provided while onboarding
deviceModel 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
batchNumber(tpnBatchNumber) Unique number will be generated to process the settlement of merchant transactions
externalReferenceId Merchant unique transaction reference id.
hostResponseDate Date time of transaction initiated
amount (USD) Amount to be charged. Amount will sent in decimal format (example 10.01)
baseAmount fee Basic amount In cents is $100.00
DISC(description) Description of the transaction this data will received in Second posting which we are Additional Transaction Details as request Type as Update
commercialTaxAmount Tax Calculation for the Transaction if merchant Opted [Decimal format (Ex : 10.00)]
localTaxAmount Local Tax Calculation for the Transaction if merchant Opted [Decimal format (Ex : 10.00)]
tipAmount Tip Amount if Customer raised [Decimal format(Ex : 10.00)]
tipAdjAmount TipAdjust calculations [Decimal format(Ex : 10.00)]
posRequestDate Request Received from the POS Terminal Date in EST(yyyy-MM-dd)
posRequestTime Request Received from the POS Terminal Time in EST(yyyy-MM-dd)
transactionDate Transaction Initiated Date in EST(yyyy-MM-dd)
transactionTime Transaction Initiated Time in EST(yyyy-MM-dd)
hostResponseDate Transaction Date and Time in EST(yyyy-MM-dd)
transactionDuration(txDuration) Transaction Duration for complete process this data will received in Second posting which we are Additional Transaction Details as request Type as Update
invoiceNumber Transaction Number generated by Issuing Bank
hostResponseCode Received from the Issuing Bank
responseText Received from the Issuing Bank
approvalCode Received from the Issuing Bank
buildNumber Transaction Processing Build this data will received in Second posting which we are Additional Transaction Details as request Type as Update
cardLabel Card Scheme
cardHolderName Name of Cardholder this data will received in Second posting which we are Additional Transaction Details as request Type as Update
maskedPan First 6 digits and Last 4 digits of card number
posMode Transaction Initiated Process
channel Transaction Initiated Channel
minorChannel Request Received Channel based on Source this data will received in Second posting which we are Additional Transaction Details as request Type as Update
communicationMedia Request Process Communication Mode this data will received in Second posting which we are Additional Transaction Details as request Type as Update
processor Transaction Acceptor Name
email Customer Email this data will received in Second posting which we are Additional Transaction Details as request Type as Update
phoneNumber Customer Mobile Number this data will received in Second posting which we are Additional Transaction Details as request Type as Update
tagLabel Future Use
tagValue Future Use
performedBy 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 Transaction Initiated by CardHolder or Others
cardType Card Type used by the cardholder
transactionMode Mode of the transaction
cardCategory Card category based on the service provider of the Card Holder
additionalDetails Future Use this data will received in Second posting which we are Additional Transaction Details as request Type as Update
termId TerminalId registered by the Processor to Merchant
Mid MerchantId provided by the processor to the Merchant
processorl2l3 Whether transaction has performed with L2L3 Packet or not
transactionId iPOSpay response unique transaction id
transactionType Type of transactions to be processed.
rrn Unique Reference Number generated by Bank System
tpn TPN Registered with Dejavoo System

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

 
{
  "id": "bc71777f-3f7b-4197-9d72-7724f9e9aaea",
  “tpn”: “381723650380”,
  "version": "1.0",
  "createdDt": "2024-06-04 08:53:39",
  "eventType": "Settlement",
  "subEventType": "ClosedBatch""requestType": "N",
  "batchNumber": "318",
  "settlementDate": "2024-07-23 02:29:05",
  "settlementCount": 4,
  "settlementAmount": 1924,
  "signature": "",
  "settlementTxnDetails": [
    {
      "txnDate": "2024-07-23 02:14:37",
      "transactionType": "SALE",
      "transactionId": "30214792249665038020240626134028",
      "txnAmount": 468
    },
    {
      "txnDate": "2024-07-23 02:14:58",
      "transactionType": "SALE",
      "transactionId": "41188040447465038020240628134407",
      "txnAmount": 520
    },
    {
      "txnDate": "2024-07-23 02:14:58",
      "transactionType": "SALE",
      "transactionId": "42517587404465038020240624201856",
      "txnAmount": 468
    },
    {
      "txnDate": "2024-07-23 02:14:58",
      "transactionType": "SALE",
      "transactionId": "76813512589365038020240624192350",
      "txnAmount": 468
    }
  ]
}
ObjectsDescription
Id (M) Unique id generated for each request
Version (M) Webhooks Integration Version
createdDt (M) Version Registered Date in EST (yyyy-MM-dd HH:mm:ss)
eventType (M) Transaction Event Type
subEventType (M) Transaction type which was done by the Customer
requestType (M) Type of Request whether to insert or update the existing record
signature (O) Mandatory only for HMAC enabled Merchants
settlementAmount Total Amount Settled for that TPN in Batch , Decimal format(Ex : 10.00)
batchNumber Settled Batch Number it will unique
settlementDate Settled Batch Date and Time in EST format in EST (yyyy-MM-dd HH:mm:ss)
SettledTxnCount Total Txn’s Settled with Batch
tpn TPN Registered with Dejavoo System
  • SettlementTxnDetails:
ObjectsDescription
txnDate Transaction Initiated Date and Time in EST (yyyy-MM-dd HH:mm:ss)
transactionId iPOSpays response unique transaction id
transactionType Type of transactions to be processed.
txnAmount Transaction Amount , Decimal format(Ex : 10.00)
Swipe Reader SDKiPOSpays WooCommerce Extension