V2 Apidocs

Freedom to Design V2

Prerequisites

Sandbox (UAT): be onboarded on the iPOSpays sandbox as a merchant, with a valid TPN.
Production (Live): be onboarded on iPOSpays production as a merchant, with a valid TPN.

No TPN? Contact your ISO or support@dejavoo.io.

Note: FTD only collects and tokenizes card data. It is not a complete payments API. To process transactions, use it with the iPOS Transact API.

Code Snippets iPOS Transact API

Localhost Restriction

Localhost restriction: As per PCI compliance, requests from localhost are not allowed. To enable it for testing, contact ISV Sales or support@dejavoo.io.

Get Started

Step 1 : Log in to your merchant account and go to Settings.

Step 2 : Under Generate Ecom/TOP Merchant Keys, select TPN and click Generate Token.

Step 3 : Under Whitelisted Domain, add the domain of the site where you want to accept payments.

Shared Key Generation

Generate a shared key with this API. Use the returned key as the security_key in the JavaScript file.

curl --location 'https://payment.ipospays.tech/api/v1/shared-key/generate' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "tpn": "TPN123456"
}'

Send either tpn or email (at least one, not both), for example {"email": "merchant@example.com"}.

How it works

The system finds the merchant from the TPN or email.
A new SHARED_KEY is generated and mapped to that merchant.
Use it as the security_key in all requests. It applies to all TPNs and emails of that merchant.

Example response

{
  "status": "SUCCESS",
  "message": "New shared key generated",
  "merchantId": "55df6354-9d1b-430a-944b-97d25d450e6e",
  "sharedKey": "deskey_hGTjHER+j+Pbw3YflDpewBH/Jl7eVDAYP7eTrZVfgU0="
}

Setting Up Your Payment Form

Freedom to Design supports card payments and Google Pay. Use your shared key as the security_key, and do not change the input IDs (ccnumber, ccexpiry, cccvv, payButton).

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <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>
  <script id="ftd"
    src="https://payment.ipospays.tech/ftd/v2/freedomtodesign.js"
    security_key="SHARED_KEY" 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();
      try {
        const data_response = await postData();
        console.log("PaymentToken:", data_response.payment_token_id);
      } catch (error) {
        console.error("Error processing payment:", error);
      }
    }
    document.getElementById("payButton")
      .addEventListener("click", submitCardFunc);
  </script>
</body>
</html>

Using the Payment Token ID

When the customer clicks pay, FTD generates a unique paymentTokenId (e.g. 65564fda-9c7e-46fd-9eca-40caff6e53c6). It is required to complete a transaction through the iPOS Transact API.

It is single-use and expires after 24 hours if unused.
Sending it to the iPOS Transact API in a $0 Pre-Auth request returns a Card Token.
The Card Token is reusable for future transactions: set cardToken to true in the iPOS Transact API request.

iPOS Transact API

Error Codes

POST /api/v1/shared-key/generate

Error Code	Message
SHARED_KEY_ERR_001	Invalid or missing api-key
SHARED_KEY_ERR_002	Invalid email or merchant not found
SHARED_KEY_ERR_002	Invalid TPN or merchant not found
SHARED_KEY_ERR_004	Unable to process shared key request
SHARED_KEY_ERR_005	TPN or email is required
SHARED_KEY_ERR_006	Provide either TPN or email, not both

Tokenization (FTD V2)

Error Code	Field	Message
FTD_V2_001	INVALID_PAYLOAD	Payload is invalid.
FTD_V2_002	INVALID_TOKENIZATION_KEY	Merchant is not active or tokenization key is invalid. Please verify your credentials
FTD_V2_003	INVALID_DOMAIN	No whitelisted domains found for this merchant. Please contact Support Team
FTD_V2_004	INVALID_DOMAIN	Origin header is required and must match a registered domain.
FTD_V2_005	INVALID_DOMAIN	Requested origin is not whitelisted. Please register the domain or contact Support Team
FTD_V2_006	RATE_LIMIT	Too many tokenization requests. Please try again later.
FTD_V2_007	INVALID_ENCRYPTED_PAYLOAD	RSA token decryption failed. Please ensure the token is correctly encrypted and try again
FTD_V2_008	INVALID_ENCRYPTED_PAYLOAD	RSA token decryption failed. Please ensure the token is correctly encrypted and try again
FTD_V2_009	INVALID_ENCRYPTED_PAYLOAD	RSA token decryption failed. Please ensure the token is correctly encrypted and try again
FTD_V2_010	PaymentTokenRefId	PaymentTokenRefId Is Already Existed
FTD_V2_011	INVALID_CARD_NUMBER	Card Number is not valid, Please try with a valid Card Number
FTD_V2_012	INVALID_CARD_NUMBER	Card Number is not valid, Please try with a valid Card Number
FTD_V2_013	CARD_EXPIRED	Card is expired or Card expiry is not valid
FTD_V2_014	INVALID_CVV	Card Cvv is not valid, Please try with valid Cvv
FTD_V2_015	SERVER_ERROR	Card data processing failed. Please try again later.
FTD_V2_016	SERVER_ERROR	Card data processing failed. Please try again later.
FTD_V2_018	PAYMENT_TOKEN_REFID	PaymentTokenRefId is empty or null
FTD_V2_019	REQUEST_EXPIRED	Request has expired. Please submit a new tokenization request.

API Docs Hosted Payment Page