Apidocs

FreedomtoDesign.Js

Prerequisites

For Sandbox (UAT) Users should be onboarded on iPOSpays sandbox(UAT) environment as a merchant and have a valid TPN.

For Production (Live) Users should be onboarded on iPOSpays production environment as a merchant and have a valid TPN.

If you do not have a TPN, contact your ISO or support@dejavoo.io.

This system focuses on data collection and tokenization. It's not a complete payments API. To process transactions, you'll need to use this in conjunction with the iPOS Transact API.

For Production Code Snippets iPOS Transact API

Get Started

Step 1 : Login to your merchant account and go to settings.

Step 2 : Under Generate Ecom/TOP Merchant Keys section select TPN and Generate Token

Step 3 : Under Whitelisted Domain add the domain of your site in which you want to accept payments.

Watch This Video for a Visual Walkthrough of the Steps

Now you have everything to setup your payment form.

Setting Up Your Payment Form

Freedom to design supports card payments and Google Pay.

Card

Follow the steps below to accept card payments

Open your website's index.html file in a text editor.
Copy and paste the following code into your text editor and run the program
Use the generated token inside “security_key.”

index.html

<!DOCTYPE html>
<html lang="en">
 
<head>
  <!-- Required meta tags -->
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="referrer" content="strict-origin-when-cross-origin" />
  <title>iPosPays Payment Form</title>
 
 
  <!-- Add defer to prevent blocking HTML rendering -->
  <script id="ftd" src="https://payment.ipospays.tech/ftd/v1/freedomtodesign.js" security_key="auth_token" defer></script>
</head>
 
<body>
  <form>
      <input id="ccnumber" />
      <input id="ccexpiry" />
      <input id="cccvv" />
      <input type="submit" id="payButton" />
  </form>
 
 
  <script>
      async function submitCardFunc(event) {
          event.preventDefault(); // Prevent default form submission
          try {
            const data_response = await postData();
            console.log("PaymentToken:", data_response.payment_token_id);
          } catch (error) {
            console.error("Error processing payment:", error);
          }
        }
  
  
        var payButton = document.getElementById("payButton");
        payButton.addEventListener("click", submitCardFunc);
  </script>
</body>
 
</html>

Using the Payment Token ID

Once the user clicks the payment button, a unique payment token ID (e.g., 65564fda-9c7e-46fd-9eca-40caff6e53c6) is generated. This token ID is required for initiating transactions via the iPOS Transact API.

iPOSTrasact API

This payment token can only be used once and will expire after 24 hours if it is not used at all.

GooglePay

Follow the steps below to accept Google Pay transactions

Open your website's index.html file in a text editor.
Copy and paste the following code into your text editor and run the program

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Google Pay Integration</title>
    <script src="https://payment.denovosystem.tech/ftd/v1/gpay.js"></script>
  </head>
  <body>
    <div id="ipospays-gpay-btn"></div>
 
 
    <script>
      const transactionInfo = {
        countryCode: "US",
        currencyCode: "USD",
        totalPriceStatus: "FINAL",
        totalPrice: "12.00",
        totalPriceLabel: "Total",
      };
 
 
      const merchantId = "N/A";
      const Mode = "TEST";
      const buttonStyles = {
        buttonColor: "default",
        buttonType: "buy",
        buttonRadius: 4,
        buttonLocale: "en",
        buttonHeight: "40px",
        buttonWidth: "240px",
      };
 
 
      const goolePayFelids = {
      	requestBillingAddress: isBillingRequired, // true or false
           	requestPayerEmail: isPayerEmailRequired, // true or false
           	requestPayerPhone: isPayerPhoneRequired, // true or false
      	requestShipping: isShippingRequired, // true or false
      };
 
 
 
 
      function getPaymentInfo(paymentData) {
        console.log("Received Payment Token (Raw):", paymentData);
      }
 
 
      updatePrice(priceCart.value); // Ensure priceCart is an input field
 
 
      initializeGooglePay(transactionInfo, merchantId, Mode, buttonStyles, goolePayFelids);
    </script>
  </body>
</html>

Using the PaymentData

Once the user clicks the payment button, a unique paymentData is generated. This paymentData is required for initiating transactions via the iPOS Transact API.

iPOSTrasact API

ACH

Use the following steps to integrate FreedomToDesign with ACH payments using the iposTransact API.

This JavaScript file is used to render mandatory fields based on the TPN configured with ACH service. Based on the required ACH tags, you can build logic to present the appropriate fields to the user. Once filled, this data is sent using the iposTransact API via the achData tag.

Prerequisites

Before integrating, ensure you have:

An HTML page where you want to display the ACH payment form
Your ecomm auth token (also referred to as security_key)
Basic knowledge of HTML and JavaScript

Step 1: Add the Script to Your Page

Include the FreedomToDesign JavaScript library on your page. This script renders the ACH form and provides metadata via callback.

Place the following <script> tag before the closing </body> tag of your HTML:

<script defer src="https://payment.ipospays.tech/ftd/v1/ipospays-ach.js" id="ftdach" security_key="auth_token"></script>

Replace auth_token with your actual ecomm auth token.

Step 2: Insert Form Field Containers

Add the following <div> elements to your HTML page. These act as placeholders for dynamically rendered form fields.

<form id="achPaymentForm">
  <h3>ACH Payment Details</h3>
  <div id="FIRST_NAME"></div>
  <div id="LAST_NAME"></div>
  <div id="PHONE_NUMBER"></div>
  <div id="EMAIL"></div>
  <div id="ADDRESS1"></div>
  <div id="CITY"></div>
  <div id="STATE"></div>
  <div id="ZIP"></div>
  <div id="DL_NUMBER"></div>
  <div id="DL_STATE"></div>
 
  <hr>
  <h4>Account Information</h4>
  <div id="ACCOUNT_NUMBER"></div>
  <div id="ROUTING_NUMBER"></div>
  <div id="ACCOUNT_TYPE"></div>
 
  <hr>
  <h4>Identity Verification</h4>
  <div id="IDENTITY"></div>
  <div id="SSN"></div>
  <div id="DOB"></div>
 
  <button type="submit" id="submitAchButton">Process ACH Payment</button>
</form>

The IDENTITY field will trigger conditional visibility for SSN and DOB fields. This logic is handled by the Integrators.

Step 3: Initialize Form and Handle Metadata Callback

You must define window.getAchPaymentInfo before initializing the form to receive terminal-level data (terminalId, entryClass, usersId) required for processing the transaction.

<script>
  const SECURITY_KEY = "YOUR_ECOMM_AUTH_TOKEN_HERE";
  let achTransactionMetadata = {};
 
  window.getAchPaymentInfo = function (data) {
    console.log("Received ACH Payment Info:", data);
    achTransactionMetadata = data;
  };
 
  async function initializePage() {
    if (typeof initializeAchForm === 'function') {
      try {
        await initializeAchForm({ security_key: SECURITY_KEY });
        console.log("ACH form initialized.");
      } catch (error) {
        console.error("Initialization failed:", error);
      }
    } else {
      console.error("initializeAchForm not available.");
    }
  }
 
  document.getElementById('submitAchButton').addEventListener('click', async (e) => {
    e.preventDefault();
 
    if (!achTransactionMetadata.terminalId || !achTransactionMetadata.entryClass || !achTransactionMetadata.usersId || !achTransactionMetadata.identity) {
      alert("Form not fully loaded. Please wait.");
      return;
    }
 
    // Example placeholder: Get customer data (implementation depends on FreedomToDesign library)
    // const customerAchData = getCustomerAchDataFromForm();
 
    alert("Form submitted! Check console for received metadata.");
  });
</script>

Step 4: Submit Data to iposTransact API from Backend

Once you have customer-entered data and metadata from the callback, submit the transaction using your backend service.

Backend API Call Example (Node.js)

async function processAchTransactionOnBackend(customerAchData, achTransactionMetadata) {
  {
    "merchantAuthentication": {
        "merchantId": "567024937072",// TPN provided by Dejavoo
        "transactionReferenceId": "7639491755250417905532" //Unique TransactionRefId for each Transaction
    },
    "transactionRequest": {
        "transactionType": 10,//ACH - Sale transaction 
        "amount": "1000",// Example: 1000 = $10.00 (amount is in cents, divided by 100)
        "achProcessor" : 1,//PAYA-1        //Processor Value whether its PAYA or others
    },
    "preferences": {
        "eReceipt": true,
        "customerEmail": "Customer_Email",// Customer Email Id
        "customerMobile": "+1234567891", // Customer Mobile Number
        "requestAchToken": true // true- Then it will share the achToken in Response if transaction is Approved. False - We will not share the achToken
    },
"achData": {
    	firstName: customerAchData.FIRST_NAME || "", 
lastName: customerAchData.LAST_NAME || "", 
addressOne: customerAchData.ADDRESS1 || "", 
state: customerAchData.STATE || "", 
dlNumber: customerAchData.DL_NUMBER || "", 
dlState: customerAchData.DL_STATE || "", 
accountNumber: customerAchData.ACCOUNT_NUMBER || "", 
accountType: customerAchData.ACCOUNT_TYPE || "", 
routingNumber: customerAchData.ROUTING_NUMBER || "", 
ssn: customerAchData.SSN || "", 
dobYear: customerAchData.DOB || "", 
city: customerAchData.CITY || "", 
zipCode: customerAchData.ZIP || "", 
identity: achTransactionMetadata.identity, 
terminalId: achTransactionMetadata.terminalId,
entryClass: achTransactionMetadata.entryClass, 
usersId: achTransactionMetadata.usersId, 
tipAmount: "0",
  }
};
 
 
  const response = await fetch("YOUR_IPOS_TRANSACT_API_ENDPOINT", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
 
  const result = await response.json();
  if (response.ok) {
    console.log("ACH Transaction successful:", result);
  } else {
    console.error("ACH Transaction failed:", result);
  }
}

iPOStransact API

Try the ACH Form Simulator

Use the simulator below to preview the rendered form and reference sample code.

iPOStransact API Simulator

For Production URL

In the src attribute of the script tag replace the sandbox url with the production url.

Production Live URL:	https://payment.ipospays.com/ftd/v1/freedomtodesign.js (opens in a new tab)

Error Codes and Their Meaning

For a complete list of error codes and their explanations, please visit our Error Codes Reference Page.

Error Codes & Messages

Freedom to Design Clear Card Encryption