Apidocs

Freedom to Design

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>
 
    <!-- Load iPOSpays Google Pay SDK -->
    <script src="https://payment.ipospays.tech/ftd/v1/gpay-ftd.js"></script>
  </head>
  <body>
    <!-- Container where the Google Pay button will be rendered -->
    <div id="ipospays-gpay-btn"></div>
 
    <script>
      /**
       * Transaction information
       * - Defines purchase details like price, currency, and country
       */
      const transactionInfo = {
        countryCode: "US",          // 2-letter country code
        currencyCode: "USD",        // ISO currency code
        totalPriceStatus: "FINAL",  // Can be ESTIMATED or FINAL
        totalPrice: "12.00",        // Amount to be charged
        totalPriceLabel: "Total",   // Label displayed on checkout
      };
 
      /**
       * Merchant settings
       * - merchantId: Your assigned Google Pay Merchant ID
       * - Mode: "TEST" or "PRODUCTION"
       */
      const merchantId = "N/A"; // Replace with your actual Merchant ID in production
      const Mode = "TEST";      // Use TEST for sandbox integration
 
      /**
       * Google Pay button styling
       * - Customize the look & feel of the payment button
       */
      const buttonStyles = {
        buttonColor: "default",   // Options: default, black, white
        buttonType: "buy",        // Options: buy, checkout, plain, order
        buttonRadius: 4,          // Border radius in pixels
        buttonLocale: "en",       // Locale for button text
        buttonHeight: "40px",     // Height of the button
        buttonWidth: "240px",     // Width of the button
      };
 
      /**
       * Additional Google Pay fields
       * - Enable/disable checkout fields based on business needs
       */
      const goolePayFelids = {
        requestBillingAddress: isBillingRequired,    // true = require billing address
        requestPayerEmail: isPayerEmailRequired,     // true = require customer email
        requestPayerPhone: isPayerPhoneRequired,     // true = require customer phone
        requestShipping: isShippingRequired,         // true = require shipping address
      };
 
      /**
       * Callback function
       * - Receives payment token after customer authorizes Google Pay
       * - You must send this token securely to your backend
       */
      function getPaymentInfo(paymentData) {
        console.log("Received Payment Token (Raw):", paymentData);
        // TODO: Send `paymentData` to your server for processing
      }
 
      /**
       * Example: Update cart price dynamically
       * - Assumes `priceCart` is an input field in the page
       * - Keeps checkout price in sync with cart updates
       */
      updatePrice(priceCart.value); 
 
      /**
       * Initialize Google Pay
       * - Renders Google Pay button
       * - Configures transaction info, merchant, mode, style, and fields
       */
      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

Apple Pay

Step 1: Add the Apple Pay SDK

You need to include the iPOSpays Apple Pay SDK script on your page.

<script 
  src="https://payment.ipospays.tech/ftd/v1/ipospays-apple-pay-ftd.js" 
  id="applepayftd">
</script>

📌 This script provides the initializeApplePay() function that will render the Apple Pay button.

Step 2: Add a Button Container

Apple Pay needs a container div where the button will appear.

<div id="ipospays-apple-pay-button"></div>

📌 The Apple Pay button will be automatically injected here by the SDK.

Step 3: Configure Transaction Info

You must provide details about the transaction such as country, currency, and total price.

const transactionInfo = {
  countryCode: "US",         // ISO country code
  currencyCode: "USD",       // ISO currency code
  totalPriceStatus: "FINAL", // FINAL = exact price, ESTIMATED = may change
  totalPrice: "49.99",       // Total amount to charge
};

Step 4: Configure Button Styles

Customize the Apple Pay button appearance.

const buttonStyles = {
  buttonColor: "black",   // black or white
  buttonType: "buy",      // buy, checkout, donate, etc.
  buttonRadius: "8px",    // corner radius
  buttonLocale: "en-US",  // locale for button label
  buttonHeight: "50px",   // height of the button
  buttonWidth: "100%",    // width of the button
};

📌 Example: A black "Buy with Pay" button will be displayed.

Step 5: Configure Apple Pay Fields

Specify what extra customer details you want to collect.

const applePayFields = {
  requestBillingAddress: true,  // ask for billing address
  requestPayerEmail: true,      // ask for email
  requestPayerPhone: true,      // ask for phone
  requestShipping: false,       // ask for shipping info
  requestPayerName: true,       // ask for full name
};

Step 6: Initialize Apple Pay

Call the SDK function with all configurations.

initializeApplePay(
  transactionInfo,
  buttonStyles,
  "YOUR_MERCHANT_ID",              // Replace with your merchant ID
  applePayFields,
  "YOUR_APPLE_MERCHANT_IDENTIFIER" // From Apple Developer account
);

📌 merchantId → Provided by iPOSpays

📌 merchantIdentifier → Created in Apple Developer portal

Step 7: Capture Apple Pay Payment Data

When a customer approves the Apple Pay sheet, the SDK will return a paymentData object. Capture it using:

function getApplePaymentInfo(paymentData) {
  console.log("Apple Pay Payment Data:", paymentData);
 
  // Forward to your transaction handler
  iposTransactApi(paymentData);
}

Step 8: Send Data to Your Backend

The function iposTransactApi() should send the paymentData token to your server, where you finalize the payment.

function iposTransactApi(paymentData) {
  fetch("/your-backend-endpoint", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ applePayToken: paymentData })
  })
    .then(res => res.json())
    .then(result => {
      if (result.success) {
        alert("✅ Payment Successful");
      } else {
        alert("❌ Payment Failed: " + result.message);
      }
    })
    .catch(err => console.error("Error:", err));
}

⚠️ You will customize iposTransactApi() in your integration to send the Apple Pay token to your server.

Step 9: Full Example Code

Here’s everything combined:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Apple Pay Checkout</title>
  <script src="https://ftd.denovosystem.tech/ftd/v1/apple-pay.js" id="applepayftd"></script>
</head>
<body>
  <!-- Apple Pay Button -->
  <div id="ipospays-apple-pay-button"></div>
 
  <script>
    const transactionInfo = {
      countryCode: "US",
      currencyCode: "USD",
      totalPriceStatus: "FINAL",
      totalPrice: "49.99",
    };
 
    const buttonStyles = {
      buttonColor: "black",
      buttonType: "buy",
      buttonRadius: "8px",
      buttonLocale: "en-US",
      buttonHeight: "50px",
      buttonWidth: "100%",
    };
 
    const applePayFields = {
      requestBillingAddress: true,
      requestPayerEmail: true,
      requestPayerPhone: true,
      requestShipping: false,
      requestPayerName: true,
    };
 
    // Initialize Apple Pay
    initializeApplePay(
      transactionInfo,
      buttonStyles,
      "YOUR_MERCHANT_ID",
      applePayFields,
      "YOUR_APPLE_MERCHANT_IDENTIFIER"
    );
 
    // Capture Payment Data
    function getApplePaymentInfo(paymentData) {
      console.log("Apple Pay Data:", paymentData);
      iposTransactApi(paymentData);
    }
 
    // Send to Backend
    function iposTransactApi(paymentData) {
      fetch("/your-backend-endpoint", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ applePayToken: paymentData })
      })
        .then(res => res.json())
        .then(result => console.log("Payment Result:", result))
        .catch(err => console.error("Error:", err));
    }
  </script>
</body>
</html>

Next Steps

Replace YOUR_MERCHANT_ID and YOUR_APPLE_MERCHANT_IDENTIFIER with real values.
Implement the backend API (/your-backend-endpoint) to receive the Apple Pay token and complete payment with iPOSpays.
Test in Sandbox/Test Mode.
After Apple domain verification, go live.

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-ftd-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="ADDRESS2"></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>
 
  <hr>
 
  <h4>Custom Tags</h4>
  <div id="CUSTOM_TAG1"></div>
  <div id="CUSTOM_TAG2"></div>
  <div id="CUSTOM_TAG3"></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 {
        let isAch = await initializeAchForm({ security_key: SECURITY_KEY });
 
        if (isAch) {
          window.getAchPaymentInfo = (achPaymentInfoData) => {
            console.log("Received payment info:", achPaymentInfoData);
            achTransactionMetadata = achPaymentInfoData;
          };
 
          window.getallFieldsData = (allFields) => {
            console.log("Received getallFields info:", allFields);
          };
        }
 
        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)
      "sourceType": "ACH-FTD"
    },
    "preferences": {
      "customerName": "Customer_Name", // Customer Name
      "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 || "",
      addressTwo: customerAchData.ADDRESS2 || "", 
      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",
      "tagLabel": "achTransactionMetadata.tagLabel",
      "tagValue": `${customerAchData.CUSTOM_TAG1},${customerAchData.CUSTOM_TAG2},${ customerAchData.CUSTOM_TAG3}`,
      "custom1": "customerAchData.CUSTOM_TAG1 || """,
      "custom2": "customerAchData.CUSTOM_TAG2 || """,
      "custom3": "customerAchData.CUSTOM_TAG3 || """,
    }
  };
 
  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.

Payment Form	Production Live URL
Card	https://payment.ipospays.com/ftd/v1/freedomtodesign.js (opens in a new tab)
Google Pay	https://payment.ipospays.com/ftd/v1/gpay-ftd.js (opens in a new tab)
Apple Pay	https://payment.ipospays.com/ftd/v1/ipospays-apple-pay-ftd.js (opens in a new tab)
ACH	https://payment.ipospays.com/ftd/v1/ipospays-ftd-ach.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 Hosted Payment Page