Apidocs

Merchant

This section includes APIs for:

Merchant onboarding
Store onboarding
TPN onboarding
Managing merchant-level configurations (e.g., whitelisting)

Onboarding With Templates

What are Templates?

Templates allow you to preconfigure parameters tailored to specific merchant verticals, making the onboarding process faster and more consistent.

For example, when onboarding restaurant merchants, you can configure parameters specific to restaurants (e.g., tax settings, payment options, etc.) and save them as a reusable template.

These templates can be applied to other similar merchants in the future, streamlining onboarding for similar use cases.

Creating Templates

Templates must be created in the portal.

Once created, they can be assigned to merchants during onboarding using the Merchant Onboarding API.

Indicator	Description
*	Mandatory
#	Pre-defined values shared in these documents

API Details

API Request URL

Objects	URLs
Sandbox URL	https://externalapi.ipospays.tech/v1/onboardmerchant (opens in a new tab)
Production URL	https://externalapi.ipospays.com/v1/onboardmerchant (opens in a new tab)

API Reference

onboardmerchant ( API )

Field	Description
merchantData	Mandatory object: This object contains the following information: - Merchant DBA - Email ID - First name - Last name - Address - Zip code - Phone number - EBT info (optional)
storeData	Mandatory object: This object contains the following information: - Store DBA - Email ID - First name - Last name - Address - Zip code - Phone number - Merchant category code, etc.
tpnData	Mandatory object: This object contains the following information: - Device manufacturer - Device model - Routing type - Application sign - BIN number - Assigned template - Processor information

The onboardmerchant API request contains 3 primary objects:

Request Parameters

Header Authorization – Request Parameters

Objects	Description
Authorization	API KEY `<your-api-key-value>`
Content-Type	application/json

Body – Request Parameters

merchantData ( Obj )

Parameter	Type	Description
dba *	String	Merchant DBA name Format: Alphanumeric, special chars Allowed special chars Length: min – 2, max – 35 characters Example value: Starbucks
firstName *	string	Merchant First Name Format: Alphabets Length: min – 2, max – 50 characters Example value: Michel
lastName (Optional)	string	Merchant Last Name Format: Alphabets Length: min – 1, max – 12 characters Example value: Jackson
email *	string	Merchant Email Id Format: E-mail id Length: min – 6, max – 255 characters Example value: example@testmail.com
addressLine1 *	string	Merchant address line 1 Format: Alphanumeric, special chars Allowed special chars Length: min – 2, max – 35 characters
addressLine2 (Optional)	string	Merchant address line 2 Format: Alphanumeric, special chars Allowed special chars Length: min – 2, max – 35 characters
zipCode *	Numbers	Merchant Zip Code Format: xxxxx Length: 5 digits required Note: City & State info will be stored based on given Zip-code value
phoneNumber *	Numbers	Merchant Contact Phone Number Format: xxxxxxxxxx Length: min – 10, max – 12
ebt (Optional)	string	EBT value (is optional) Format: Alphanumeric Length: 7 chars required
isoAgentReference (Optional)	string	ISO Agent Reference Format: Alphanumeric Length: min – 1, max – 15 characters
isoMerchant (Optional)	string	Merchant Reference Format: Alphanumeric Length: min – 1, max – 6 characters
merchantLogoUrl	string	Merchant Logo image url Format: http / https url
ISDcode *	string	ISD code number Format: +xxx Length: min – 2, max – 4 Allowed special chars: +

storeData ( Obj )

Parameter	Type	Description
mccCode# *	Numeric	Merchant category code Format: xxxx Length: 4 digits required
firstName *	string	Store manager / owner first name Format: Alphabets Length: min – 2, max – 50 characters Example value: Michel
lastName (Optional)	string	Store manager / owner last name Format: Alphabets Length: min – 1, max – 12 characters Example value: Jackson
dba *	String	Store DBA name Format: Alphanumeric, special chars Allowed special chars Length: min – 2, max – 35 characters Example value: Starbucks
addressLine1 *	string	Store address info line 1 Format: Alphanumeric, special chars Allowed special chars Length: min – 2, max – 35 characters
addressLine2 (Optional)	string	Store address info line 2 Format: Alphanumeric, special chars Allowed special chars Length: min – 2, max – 35 characters
zipCode *	Numbers	Store located Zip-code Format: xxxxx Length: 5 digits required Note: City & State info will be stored based on given Zip-code value
email *	string	Store Email Id Format: e-mail id Length: min – 6, max – 255 characters Example value: example@testmail.com
phoneNumber *	Numbers	Store Phone number Format: xxxxxxxxxx Length: min – 10, max – 12
ISDcode *	string	ISD code number Format: +xxx Length: min – 2, max – 4 Allowed special chars: +

tpnData ( Obj )

Parameter	Type	Description
deviceManufacturer *	String	Device manufacturer information Format: Alphabets Values: Cloud POS, Android Phone, WizardPOS, Kozen Note: pre-defined inputs as per doc
deviceModel# *	String	Device model information Values: P1, P3, P5, Q2, QD2, QD3, QD4, QD5, QD6, Cloud POS, Tap on phone Note: pre-defined inputs as per doc
tpnApplicationSign# *	string	Application signature information Format: Alphabets Values: CRDT Note: pre-defined inputs as per doc
tpnAssignTemplate (Optional)	string	Assign template information Format: Alphanumeric Length: min – 5, max – 30 characters
tpnRoutingType# *	string	Routing type information Format: Alphabets Values: SIMPLE Default value: SIMPLE
defaultLabel (Optional)	string	Default label value Format: Alphanumeric Length: 18 chars required

Device Model and Manufacturer Conditions

The device model and manufacturer are conditional. For example, the P1 model is available only under the Kozen manufacturer. Refer to the table below for supported device models and their respective manufacturers.

Device Manufacturer	Device Model
Kozen *	P1, P3, P5, P8, P12
Wizer POS *	Q2, QD2, QD3, QD4, QD5, QD6
Cloud POS *	Cloud POS
Android Phone *	Tap on Phone
Apple *	Apple Pay

Processor Details

Each processor has a unique set of required and optional fields. Below is a breakdown of the input structure for each processor.

Processor: TSYS

Field	Type	Description
tpnProcessor *	Object	Note: object name as specified in doc
processorName *	string	Processor name Format: Alphabets Values: TSYS Note: pre-defined inputs as per doc
profileId *	string	Profile Id value – with fee or without fee Values: 01 – with fee, 02 – without fee Note: pre-defined inputs as per doc
Mid *	Numbers	Mid input value Length: 12 digits required
Agent *	Numbers	Agent input value Length: 6 digits required
Chain *	Numbers	Chain input value Length: 6 digits required
Store *	Numbers	Store input value Length: 4 digits required
TermNo *	Numbers	Term Number input value Length: 4 digits required
TermId *	string	Term Id input value Format: Alphanumeric Length: 8 chars required
ABA_No	Numbers	ABA_No input value Length: 9 digits required
Agent_FIID	Alphanumeric	Type: String (SETT.Agent) Format: Alphanumeric Length: 4 chars required
dsGroup	string	dsGroup input value Format: Alphanumeric Length: min:1, max:30 chars required
tpnBin *	Numbers	TPN Bin input value Length: 6 digits required

Processor: PNWX (Paynetworx)

Field	Type	Description
tpnProcessor *	Object	Note: object name as specified in doc
processorName *	String	Format: Alphabets Values: PNWX Note: pre-defined inputs as per doc
profileId *	string	Values: 01 – with fee, 02 – without fee Note: pre-defined inputs as per doc
AccessTokenUser *	string	Format: Alphanumeric Length: min – 25, max – 50 characters
AccessTokenPassword *	string	Format: Alphanumeric Length: min – 25, max – 50 characters

Processor: CKNX (Cardknox)

Field	Type	Description
tpnProcessor *	Object	Note: object name as specified in doc
processorName *	String	Format: Alphabets Values: CKNX Note: pre-defined inputs as per doc
profileId *	string	Values: 01 – with fee, 02 – without fee Note: pre-defined inputs as per doc
apiKey *	string	Length: max – 45 characters

Processor: ZCRD (Z Credit)

Field	Type	Description
tpnProcessor *	Object	Note: object name as specified in doc
processorName *	String	Format: Alphabets Values: ZCRD Note: pre-defined inputs as per doc
profileId *	string	Profile id value with fee or without fee Values: 01 – with fee, 02 – without fee Note: pre-defined inputs as per doc
TerminalNumber *	Numbers	Terminal number input value Length: max – 16
Password *	String	Password input value Length: max – 16
Track2 *	String	Track2 input value Format: Alphanumeric Length: max – 18

Processor: FDRC (Fiserv North)

Field	Type	Description
tpnProcessor *	Object	Note: object name as specified in doc
processorName *	String	Format: Alphabets Values: FDRC Note: pre-defined inputs as per doc
tpnBin *	Numbers	TPN Bin input value Length: 6 digits required
Mid *	String	Mid input value Length: max – 15 characters Format - Alphanumeric
TermId *	String	Term Id input value Length: max – 15 characters Format - Alphanumeric
GroupId *	String	Group Id input value Length: max – 15 characters Format - Alphanumeric
EcommURL	String	This field contains a URL value

Processor: WPAY (WorldPay)

Field	Type	Description
TermId *	Numbers	Term Id input value Length: max – 3 characters Format - Numeric
Mid *	Numbers	Mid input value Length: max – 13 characters Format - Numeric
BankId *	Numbers	Bank Id input value Length: max – 4 characters Format - Numeric

Processor: ELVN (Elavon)

Field	Type	Description
TermId *	Numbers	Term Id input value Length: max – 16 characters Format - Numeric
Mid *	Numbers	Mid input value Length: min 10 to max 12 chars Format - Numeric
BankNo *	Numbers	Bank Number input value Length: max – 6 characters Format - Numeric

Processor : FDOH (Fiserv Omaha)

Field	Type	Description
TermId *	Numbers	Term Id input value Length: max – 16 characters Format - Numeric
Mid *	Numbers	Mid input value Length: min 10 to max 12 chars Format - Numeric
GroupId *	Numbers	Group Id input value Length: max – 15 characters Format - Alphanumeric

Response Parameters

Variable Name	Description
message *	Contains information about Success / Failure of request
data	Contains information about the response data based on the request on success
errors	Contains information about the errors based on the request input on failure

Onboarding / Creation of Merchant, Store, and TPN

This section provides a detailed overview of the API process for onboarding merchants, stores, and TPNs. It covers the request methods, required parameters, and expected responses for different onboarding scenarios. You'll find structured guidelines on API request formatting, including headers, request body parameters, and sample JSON request and response structures for both successful and failed attempts

Request Method

Object	Description
Method	POST

Header Authorization Info

Object	Description
Authorization	api-key `<your-api-key-value>`
Content-Type	application/json

Pre-defined Input Field – Values and Description

Processor Name details ( Field & Descriptions )

Field	Description
TSYS	TSYS processor
PNWX	PNWX processor
CKNX	CKNX processor
ZCRD	ZCRD processor
FDRC	FDRC processor
WPAY	WPAY processor
ELVN	ELVN processor
FDOH	FDOH processor

Device Manufacturer details ( Field & Descriptions )

Device Model	Manufacturer
Q2	WizarPOS
QD2	WizarPOS
QD3	WizarPOS
QD4	WizarPOS
QD5	WizarPOS
QD6	WizarPOS
P1	Kozen
P3	Kozen
P5	Kozen
P8	Kozen
P12	Kozen
Cloud POS	Cloud POS
Tap On Phone	Android Phone
Apple Pay	Apple

Routing Type details ( Field & Descriptions )

Application Signature details ( Field & Descriptions )

Field	Description
SIMPLE	SIMPLE type
CRDT	Credit Debit

EBT placement rules:

If you add ebt under merchantData → applies to all stores.
If you add ebt under storeData → applies to that specific store only.
If you include ebt in both places → the system will use the storeData value.

Header

{
    Authorization: API-Key value
    content-type: application/json
}

Body

{
    "merchantData": 
    {
        "dba": "Merchant DBA name",
        "email": "Merchant e-mail Id",
        "firstName": "Merchant first name",
        "lastName": "Merchant last name - optional",
        "addressLine1": "Merchant address line 1",
        "addressLine2": "Merchant address line 2 - optional",
        "zipCode": "Merchant zip code",
        "ISDcode": "Country ISD code",
        "phoneNumber": "Merchant phone number",
        "ebt": "EBT info",   // If provided here under 'merchantData', this EBT information will apply to all stores. If provided under 'storeData', it will apply only to that specific store. If included in both, the system will prioritize 'storeData'.
        "isoAgentReference": "ISO agent reference info",
        "isoMerchant": "ISO Merchant reference info",
        "merchantLogoUrl": "Merchant Logo Url"
    },
 
    "storeData": 
    {
        "dba": "Store DBA name",
        "email": "Store e-mail Id",
        "mccCode": "Pre-defined merchant category code",
        "firstName": "Store manager first name",
        "lastName": "Store manager last name - optional",
        "addressLine1": "Store address line 1",
        "addressLine2": "Store address line 2 - optional",
        "zipCode": "Store zip code",
        "ISDcode": "Country ISD code",
        "phoneNumber": "Store phone number",
        "ebt": "EBT info",   //If provided under 'storeData', it will apply only to that specific store.
    },
 
    "tpnData": 
    {
        "deviceManufacturer": "Device manufacturer – refer to documentation",
        "deviceModel": "Device Model Id – refer to documentation",
        "tpnApplicationSign": "TPN application sign – refer to documentation",
        "tpnRoutingType": "TPN routing type",
        "tpnBin": "BIN Number",
        "defaultLabel": "Default label details",
        "tpnAssignTemplate": "Assign template",
        "tpnProcessor": {	// Refer to documentation for valid processor names and their profiles
                "processorName": "Processor name",
                "profile": [ 
                // Array of values – refer to documentation for profile request details 
                           ]    
                        }
    }
}

Processor-Specific Data Formats

The reference for processor request information in the tpnData object is provided below.

For TSYS Processor

"tpnProcessor":
{
    "processorName": "TSYS",
    "profile":
    [
        {
        "profileId": "01", 
        "Mid": "Mid number info",
        "Agent": "Agent number info",
        "Chain": "Chain number info",
        "Store": "Store number info",
        "TermNo": "Term Number info",
        "TermId": "TermId number info",
        "ABA_No": "ABA Number details",
        "Agent_FIID": "Agent FIID info",
        "dsGroup": "ds group info"			
        },
        {
        "profileId": "02", 
        "Mid": "Mid number info",
        "Agent": "Agent number info",
        "Chain": "Chain number info",
        "Store": "Store number info",
        "TermNo": "Term Number info",
        "TermId": "TermId number info",
        "ABA_No": "ABA Number details",
        "Agent_FIID": "Agent FIID info",
        "dsGroup": "ds group info"						
        }                            
    ]
}

For PNWX Processor

"tpnProcessor":
{
    "processorName": "PNWX",
    "profile":
    [
        {
        "profileId": "01", 
        "AccessTokenUser":"Access token user",
        "AccessTokenPassword":"Access token password"
        },
        {
        "profileId": "02", 
        "AccessTokenUser":"98984949484985",
        "AccessTokenPassword":"98e98e9e88888"
        }
    ]
}

For CKNX Processor

"tpnProcessor":
{
    "processorName": "CKNX",
    "profile":
    [
        {
        "profileId": "01", 
        "apiKey": "apikey"
        },
        {
        "profileId": "02", 
        "apiKey": "apikey"
        }                            
    ]
}

For ZCRD Processor

"tpnProcessor":
{
    "processorName": "ZCRD",
    "profile":
    [
        {
        "profileId": "01", 
        "TerminalNumber": "Terminal Number",
        "Password": "password info",
        "Track2": "Track2 info"
        },
        {
        "profileId": "02",
        "TerminalNumber": "Terminal Number",
        "Password": "password info",
        "Track2": "Track2 info"
        }                            
    ]
}

For FDRC Processor

"tpnProcessor":
{
    "processorName": "FDRC",
    "profile":
    [
        {
        "profileId": "01", 
        "Mid": "Mid number info",
        "TermId": "TermId number info",
        "GroupId": "Group Number info"
        },
        {
        "profileId": "02", 
        "Mid": "Mid number info",
        "TermId": "TermId number info",
        "GroupId": "Group Number info"
        }                            
    ]
}

For WPAY Processor

"tpnProcessor":
{
    "processorName": "WPAY",
    "profile":
    [
        {
        "profileId": "01", 
           "TermId": "TermId number info", 
           "Mid": "Mid number info",
           "BankId": "BankId number info"
        },
        {
        "profileId": "02", 
            "TermId": "TermId number info",
            "Mid": "Mid number info",
            "BankId": "BankId number info"
        }                            
    ]
}

For FDOH Processor

"tpnProcessor":
{
    "processorName": "FDOH",
    "profile":
    [
        {
        "profileId": "01", 
           "TermId": "TermId number info", 
           "Mid": "Mid number info",
           "GroupId": "GroupId number info"
        },
        {
        "profileId": "02", 
            "TermId": "TermId number info",
            "Mid": "Mid number info",
            "GroupId": "GroupId number info"
        }                            
    ]
}

Sample JSON Response – Merchant-Store-TPN Creation

On Success - HTTP Response Status: 200

{
    "message": "Merchant onboard successfully",
    "data": 
    {
    "merchantId": "Merchant Id",
    "storeId": "Store Id",
    "tpn": " TPN Number"
    "tpnId" :
    }
}

On Failure - HTTP Response Status: 400

{
    "message": "Merchant onboard failure",
    "errors": [
        {
            "code": "error_code",
            "message": "error_message",
            "param": "error_on_input_field",
        },
        {
            "code": "already_exists",
            "message": "Given merchant dba name input is already exists",
            "param": "merchantData.dba",
        },
	  ... 
              ]
}

On Authorization Failure - HTTP Response Status: 401

{
    "message": "Access denied, invalid authorization token!",
    "errors": []
}

Sample JSON Request – Store-TPN Creation

Header

{
    Authorization: api-key <your-api-key-value>
    content-type: application/json
}

Body

{
    "merchantData": {
        "merchantId": "API responded Merchant Id"
    },
    "storeData": {
        "dba": "Store DBA name",
        "email": "Store e-mail ID",
        "mccCode": "Pre-defined merchant category code",
        "firstName": "Store manager first name",
        "lastName": "Store manager last name - optional",
        "addressLine1": "Store address line 1",
        "addressLine2": "Store address line 2 - optional",
        "zipCode": "Store ZIP code",
        "ISDcode": "Country ISD code",
        "phoneNumber": "Store phone number",
        "ebt": "EBT info" 
        // If provided under 'merchantData', this EBT information will apply to all stores.
        // If provided under 'storeData', it will apply only to the specific store.
        // If included in both, the system will prioritize 'storeData'.
    },
    "tpnData": {
        "deviceManufacturer": "Device manufacturer – refer to documentation",
        "deviceModel": "Device Model ID – refer to documentation",
        "tpnApplicationSign": "TPN application sign – refer to documentation",
        "tpnRoutingType": "TPN routing type",
        "tpnBin": "BIN number",
        "defaultLabel": "Default label details",
        "tpnAssignTemplate": "Assign template",
        "tpnProcessor": {
            // Refer to the documentation for processor names and corresponding profiles
            "processorName": "Processor name",
            "profile": [
                // Array values – refer to the documentation for profile request details
            ]
        }
    }
}

Sample JSON Response – Store-TPN Creation

On Success - HTTP Response Status: 200

{
    "message": "Store onboard successfully",
    "data": {
        "merchantId": "Merchant Id",
        "storeId": "Store Id",
        "tpn": " TPN Number"
            }
}

On Failure - HTTP Response Status: 400

{
    "message": "Store onboard failure",
    "errors": [
        {
            "code": "error_code",
            "message": "error_message",
            "param": "error_on_input_field"
        },
        {
            "code": "already_exists",
            "message": "Given store dba name input is already exists",
            "param": "storeData.dba"
        },
	  ... 
             ]
}

On Authorization Failure - HTTP Response Status: 401

{
    "message": "Access denied, invalid authorization token!",
    "errors": []
}

Sample JSON Request – TPN Creation

Header

{
    "Authorization": "api-key <your-api-key-value>",  // Replace with your actual API key
    "Content-Type": "application/json"                // Specifies that the request body is in JSON format
}

Body

{
    "merchantData": {
        "merchantId":"API responded Merchant Id"
    },
    "storeData": {
        "storeId":"API responded Store Id"
    },
    "tpnData": {
        "deviceManufacturer": "Device manufacturer – refer document",
        "deviceModel": "Device Model Id – refer document",
        "tpnApplicationSign": "TPN application sign – refer document",
        "tpnRoutingType": "TPN routing type",
        "tpnBin": "BIN Number",
        "defaultLabel": "default label details",
        "tpnAssignTemplate": "Assign template",
        "tpnProcessor": {	// refer below document for each processor name with profiles
        	"processorName": "processor name",
            	“profile”: [ 
// array values, refer below doc for profile request info 
]
        }
    }
}

Sample JSON Response – TPN Creation

On Success - HTTP Response Status: 200

{
    "message": "TPN onboard success",
    "data": {
        "merchantId": "Merchant Id",
        "storeId": "Store Id",
        "tpn": " TPN Number"
    }
}

On Failure - HTTP Response Status: 400

{
    "message": "TPN onboard failure",
    "errors": [
        {
            "code": "error_code",
            "message": "error_message",
            "param": "error_on_input_field"
        },
        {
            "code": "mandatory_field",
            "message": "Device model input is mandatory",
            "param": "tpnData.deviceModel"            
        },
	  ... 
    ]
}

On Authorization Failure - HTTP Response Status: 401

{
    "message": "Access denied, invalid authorization token!",
    "errors": []
}

Response Parameters – JSON sample

HTTP Response Status: 401 (Unauthorized Access)

{
	message: "Unauthorized Access / Forbidden",
    }

HTTP Response Status: 200 (OK)

{
    "message": "Merchant created successfully",
    "data": {
        // Contains the response data returned after successful merchant creation
    }
}

HTTP Response Status: 400 (Bad Request)

{
    "code": "error-code",       // Unique identifier representing the error type
    "message": "error-message", // Human-readable description of the error
    "param": "error-on-field"   // Field or parameter that caused the error
}

Edit Merchant

This API allows you to enable, disable, or configure merchant-level features.

Currently supported:

Domain Whitelisting — Restricts access to specific, approved domains to enhance security and prevent unauthorized usage.

Authentication

To use this API, you must first generate an authentication token using your API Key and Secret Key.

Retrieve the token from the Auth-Token endpoint
Include the token in the Authorization header for all requests

Domain Whitelisting

This feature allows you to control which domains are permitted to interact with merchant services by explicitly defining allowed origin URLs.

Enable / Configure Domain Whitelisting

{
  "merchantId": "merchId-12-chars",
  "whitelistDomains": {
    "originUrls": [
      "https://example.com",
      "https://store.example.com"
    ]
  }
}

To disable domain whitelisting, send an empty list of domains:

Disable Domain Whitelisting

{
  "merchantId": "merchId-12-chars",
  "whitelistDomains": {
    "originUrls": []
  }
}

Header Parameters

Parameter	Type	Description
Authorization	string	Token used to authenticate the API request and grant access to protected merchant resources

Body Parameters

Parameter	Type	Required	Description
merchantId *	string	Yes	Unique identifier of the merchant for whom the feature is being configured
whitelistDomains *	object	Yes	Configuration object for domain whitelisting

whitelistDomains Object

Parameter	Type	Required	Description
originUrls *	array	Yes	List of allowed domain URLs. Only these domains will be permitted access

Response

Success (200) - Returned when the configuration is successfully applied.

Parameter	Type	Description
message	string	Provides additional context about the success status
statusCode	number	HTTP status code indicating success
request_id	string	Unique identifier for the API request (useful for debugging and tracking)
timestamp	string	Time when the response was generated (ISO 8601 format)

Validation Error (422) - Returned when the request payload contains invalid or missing data.

Parameter	Type	Description
message	string	Provides details about the validation error
status_code	number	HTTP status code indicating validation failure
request_id	string	Unique identifier for the API request
timestamp	string	Time when the response was generated (ISO 8601 format)

Merchant Not Found (404) - Returned when the specified merchantId does not exist.

Parameter	Type	Description
message	string	Indicates that the merchant was not found
statusCode	number	HTTP status code
request_id	string	Unique identifier for the API request
timestamp	string	Time when the response was generated (ISO 8601 format)

Not Authorized (401) - Returned when authentication fails due to a missing, invalid, or expired token.

Parameter	Type	Description
message	string	Details about the authorization failure
responseCode	string	Internal response code for authorization errors
statusCode	number	HTTP status code
request_id	string	Unique identifier for the API request
timestamp	string	Time when the response was generated (ISO 8601 format)

Store

The following APIs allow you to manage store-level operations:

Onboard Store and TPN (Terminal Processing Number)
Enable or Disable ACH Payments

If you require additional functionality or custom parameters, please contact your Dejavoo representative.

Add Store

This API is used to add a store under an existing merchant and assign a TPN (device/terminal configuration).

Request

{  "merchantData": {
    "merchantId": "<merchantId>"
  },
  "storeData": {
    "mccCode": "<mccCode>",
    "firstName": "<firstName>",
    "lastName": "<lastName>",
    "dba": "<DBA>",
    "addressLine1": "<addressLine1>",
    "addressLine2": "<addressLine2>",
    "zipCode": “<zipCode>”,
    "email": "<email>",
    "phoneNumber": “<phoneNumber>”,
    "ISDcode": "<ISDcode>"
  },
  "tpnData": {
    "deviceManufacturer": "<deviceManufacturer>",
    "deviceModel": "<deviceModel>",
    "tpnApplicationSign": "<tpnApplicationSign>",
    "tpnRoutingType": "<tpnRoutingType>",
    "tpnBin": "<tpnBin>",
    "defaultLabel": "<defaultLabel>",
    "tpnAssignTemplate": "<tpnAssignTemplate>",
    "tpnProcessor": {
      "processorName": "TSYS",
      "profile": [
        {
          "profileId": "01",
          "Mid": "Mid number info",
          "Agent": "Agent number info",
          "Chain": "Chain number info",
          "Store": "Store number info",
          "TermNo": "Term Number info",
          "TermId": "TermId number info",
          "ABA_No": "ABA Number details",
          "Agent_FIID": "Agent FIID info",
          "dsGroup": "ds group info"
        },
        {
          "profileId": "02",
          "Mid": "Mid number info",
          "Agent": "Agent number info",
          "Chain": "Chain number info",
          "Store": "Store number info",
          "TermNo": "Term Number info",
          "TermId": "TermId number info",
          "ABA_No": "ABA Number details",
          "Agent_FIID": "Agent FIID info",
          "dsGroup": "ds group info"
        }
      ]
    }
  }}

Device Compatibility

Device model and manufacturer must match supported combinations:

Device Manufacturer	Supported Models
Kozen	P1, P3, P5, P8, P12
Wizer POS	Q2, QD2, QD3, QD4, QD5, QD6
Cloud POS	Cloud POS
Android Phone	Tap on Phone
Apple	Apple Pay

TPN Processor

Each processor requires a specific payload structure.

Example shown above: TSYS Processor
For other processors (PNWX, CKNX, ZCRD, FDRC, WPAY, ELVN), use their respective predefined payload formats.

Header Parameters

Parameter	Type	Description
Authorization	string	Token used to authenticate the API request

Body Parameters

merchantData

Parameter	Type	Required	Description
merchantId*	string	Yes	Unique identifier of the merchant

storeData

Parameter	Type	Required	Description
mccCode*	string	Yes	Merchant Category Code (4 digits)
firstName*	string	Yes	Store owner/manager first name
lastName	string	No	Store owner/manager last name
dba*	string	Yes	Store DBA name
addressLine1*	string	Yes	Store address line 1
addressLine2	string	No	Store address line 2
zipCode*	string	Yes	5-digit ZIP code (auto-maps city/state)
email*	string	Yes	Store email address
phoneNumber*	string	Yes	Store phone number
ISDcode*	string	Yes	International dialing code (e.g., +1)
ebt	string	No	Optional EBT configuration value

tpnData

Parameter	Type	Required	Description
deviceManufacturer*	string	Yes	Device manufacturer (predefined values only)
deviceModel*	string	Yes	Device model (must match manufacturer)
tpnApplicationSign*	string	Yes	Application type (e.g., CRDT)
tpnRoutingType*	string	Yes	Routing type (default: SIMPLE)
tpnBin	string	No	BIN configuration
defaultLabel	string	No	Default label (max 18 characters)
tpnAssignTemplate	string	No	Template assignment
tpnProcessor*	object	Yes	Processor-specific configuration

tpnProcessor

Parameter	Type	Required	Description
processorName*	string	Yes	Processor name (e.g., TSYS)
profile*	array	Yes	List of processor profiles

profile Object

Parameter	Type	Required	Description
profileId*	string	Yes	Profile identifier
Mid*	string	Yes	Merchant ID
Agent*	string	Yes	Agent number
Chain*	string	Yes	Chain number
Store*	string	Yes	Store number
TermNo*	string	Yes	Terminal number
TermId*	string	Yes	Terminal ID
ABA_No	string	No	ABA number
Agent_FIID	string	No	Agent FIID
dsGroup	string	No	DS group

Response

Success (200)

{
  "message": "Store onboard successfully",
  "data": {
    "merchantId": "Merchant Id",
    "storeId": "Store Id",
    "tpn": " TPN Number",
    "tpnId": "TPN Id"
  }
}

Error Responses

Status Code	Description
400	Bad Request
401	Unauthorized

Edit Store

This API allows you to enable or disable features at the store level for an existing merchant.

Currently supported: Bank Payments (ACH)

Authentication

Use the Auth-Token endpoint to generate a token using your API Key and Secret Key. Include the token in the Authorization header for all requests.

Bank Payments (ACH)

Use this API to enable or disable bank (ACH) payments for a store.

Supported processors:

Payroc
Paya

Enable ACH

Payroc ACH

{
  "storeI1d": "storeId-12-chars",
  "achDetails": {
    "achStatus": true,
    "achProcessorName": "Payroc",
    "payrocDetails": {
      "clientId": "123456"
    }
  }
}

Paya ACH

{
  "storeId": "storeId-12-chars",
  "achDetails": {
    "achStatus": true,
    "achProcessorName": "Paya",
    "payaDetails": {
      "isMandatoryCheck": true,
      "terminalSettings": {
        "web": "1234",
        "tel": "5678",
        "ppd": "9012",
        "ccd": "3456"
      }
    }
  }
}

Disable ACH

{
  "storeId": "storeId-12-chars",
  "achDetails": {
    "achStatus": false
  }
}

Header Parameters

Parameter	Type	Description
Authorization	string	Token used to authenticate and authorize the request

Body Parameters

Parameter	Type	Required	Description
storeId*	string	Yes	Unique identifier of the store
achDetails*	object	Yes	ACH configuration details

achDetails Object

Parameter	Type	Required	Description
achStatus*	boolean	Yes	Controls ACH state (true = enable, false = disable)
achProcessorName	string	Conditional	Required when enabling ACH (Paya or Payroc)

Payroc Configuration

Parameter	Type	Description
clientId	string	Unique client identifier provided by Payroc

Paya Configuration

Parameter	Type	Description
isMandatoryCheck	boolean	Enables mandatory ACH field validation
terminalSettings	object	Configuration for ACH transaction types

terminalSettings

Parameter	Description
web	Web transaction configuration
tel	Telephone (TEL) transaction configuration
ppd	Prearranged Payment & Deposit configuration
ccd	Corporate Credit/Debit configuration

Response

Success (200)

Parameter	Type	Description
message	string	Summary of the response
statusCode	number	HTTP status code
request_id	string	Unique request identifier for tracking
timestamp	string	Response timestamp (ISO 8601 format)

Error Responses

Status Code	Description
400	Bad Request
403	Not Authorized
404	Store Not Found
422	Validation Error
500	Internal Server Error

TPN

This API allows you to add a TPN under an existing merchant and store, update TPN parameters required for device onboarding and integration, and retrieve TPN details.

If you require additional parameters or custom configurations, contact your Dejavoo representative.

Add TPN

This API is used to add a TPN under an existing Merchant and Store by submitting merchant, store, device, and processor configuration details.

Request

{
  "merchantData": {
    "merchantId": "<merchantId>"
  },
  "storeData": {
    "storeId": "<storeId>"
  },
  "tpnData": {
    "deviceManufacturer": "<deviceManufacturer>",
    "deviceModel": "<deviceModel>",
    "tpnApplicationSign": "<tpnApplicationSign>",
    "tpnRoutingType": "<tpnRoutingType>",
    "tpnBin": "<tpnBin>",
    "defaultLabel": "<defaultLabel>",
    "tpnAssignTemplate": "<tpnAssignTemplate>",
    "tpnProcessor": {
      "processorName": "TSYS",
      "profile": [
        {
          "profileId": "01",
          "Mid": "Mid number info",
          "Agent": "Agent number info",
          "Chain": "Chain number info",
          "Store": "Store number info",
          "TermNo": "Term Number info",
          "TermId": "TermId number info",
          "ABA_No": "ABA Number details",
          "Agent_FIID": "Agent FIID info",
          "dsGroup": "ds group info"
        },
        {
          "profileId": "02",
          "Mid": "Mid number info",
          "Agent": "Agent number info",
          "Chain": "Chain number info",
          "Store": "Store number info",
          "TermNo": "Term Number info",
          "TermId": "TermId number info",
          "ABA_No": "ABA Number details",
          "Agent_FIID": "Agent FIID info",
          "dsGroup": "ds group info"
        }
      ]
    }
  }
}

Device Manufacturer & Model Mapping

The device model must correspond to the correct manufacturer.

Manufacturer	Supported Models
Kozen	P1, P3, P5, P8, P12
WizarPOS	Q2, QD2, QD3, QD4, QD5, QD6
Cloud POS	CloudPOS
Android Phone	Tap on Phone
Apple	Apple Pay

TPN Processor Configuration

Each processor requires a specific payload structure.

TSYS Processor

"tpnProcessor": {
  "processorName": "TSYS",
  "profile": [
    {
      "profileId": "01",
      "Mid": "Mid number info",
      "Agent": "Agent number info",
      "Chain": "Chain number info",
      "Store": "Store number info",
      "TermNo": "Term Number info",
      "TermId": "TermId number info",
      "ABA_No": "ABA Number details",
      "Agent_FIID": "Agent FIID info",
      "dsGroup": "ds group info"
    }
  ]
}

Key Fields

profileId: "01" (with fee), "02" (without fee)
Mid: 12-digit merchant ID
Agent, Chain: 6 digits
Store, TermNo: 4 digits
TermId: 8-character alphanumeric

PNWX (Paynetworx) Processor

"tpnProcessor": {
  "processorName": "PNWX",
  "profile": [
    {
      "profileId": "01",
      "AccessTokenUser": "Access token user",
      "AccessTokenPassword": "Access token password"
    }
  ]
}

CKNX (Cardknox) Processor

"tpnProcessor": {
  "processorName": "CKNX",
  "profile": [
    {
      "profileId": "01",
      "apiKey": "apikey"
    }
  ]
}

ZCRD (Z Credit) Processor

"tpnProcessor": {
  "processorName": "ZCRD",
  "profile": [
    {
      "profileId": "01",
      "TerminalNumber": "Terminal Number",
      "Password": "password info",
      "Track2": "Track2 info"
    }
  ]
}

FDRC (Fiserv North) Processor

"tpnProcessor": {
  "processorName": "FDRC",
  "profile": [
    {
      "profileId": "01",
      "Mid": "Mid number info",
      "TermId": "TermId number info",
      "GroupId": "Group Number info"
    }
  ]
}

WPAY (WorldPay) Processor

"tpnProcessor": {
  "processorName": "WPAY",
  "profile": [
    {
      "profileId": "01",
      "TermId": "TermId number info",
      "Mid": "Mid number info",
      "BankId": "BankId number info"
    }
  ]
}

ELVN (Elavon) Processor

"tpnProcessor": {
  "processorName": "ELVN",
  "profile": [
    {
      "profileId": "01",
      "TermId": "TermId number info",
      "Mid": "Mid number info",
      "BankNo": "Bank Number Info"
    }
  ]
}

Header Parameters

Parameter	Type	Description
Authorization	string	Bearer token used for authentication

Body Parameters (Summary)

Field	Type	Required	Description
merchantData*	object	Yes	Merchant details
storeData*	object	Yes	Store details
tpnData*	object	Yes	TPN configuration

Response (200)

{
  "message": "TPN onboard success",
  "data": {
    "merchantId": "Merchant Id",
    "storeId": "Store Id",
    "tpn": "TPN Number",
    "tpnId": "TPN Id"
  }
}

Edit TPN

This API allows you to enable/disable specific features at the TPN level

Currently Supported - Enable/disable SPIn integration and configure the integration type and mode.

Request Examples

Enable SPIn (Cloud Mode)

{
  "tpnId": "abcdef123456",
  "integrationDetails": {
    "integrationType": "spin",
    "spinMode": "cloud",
    "isvName": "iPOSpays",
    "deviceModel": "P1"
  }
}

Enable SPIn (Local Mode)

{
  "tpnId": "abcdef123456",
  "integrationDetails": {
    "integrationType": "spin",
    "spinMode": "local"
  }
}

Disable SPIn

{
  "tpnId": "abcdef123456",
  "integrationDetails": {
    "integrationType": "none"
  }
}

Header Parameters

Parameter	Type	Description
Authorization	string	Token used to authenticate the request. Must include permissions to modify SPIN features for the specified merchant

Body Parameters

Parameter	Type	Required	Description
tpnId*	string	Yes	Unique Terminal Profile Number identifying the terminal device
integrationDetails*	object	Yes	Configuration object defining integration behavior

integrationDetails Object

Parameter	Type	Required	Description
integrationType*	string	Yes	Type of integration. Determines required fields and behavior. Allowed values: spin, none
spinMode	string	Conditional	Required when integrationType = spin. Allowed values: cloud, local
isvName	string	Conditional	Required for SPIN cloud integrations when applicable
deviceModel	string	Conditional	Required for SPIN cloud when device-specific configuration is needed

Response

Enable SPIN (Local Mode) / Disable SPIN — 200

{
  "message": "Success",
  "statusCode": 200,
  "request_id": "request-id",
  "timestamp": "ISO-8601"
}

Enable SPIN (Cloud Mode) — 200

{
  "spinData": {
    "registerId": "",
    "authKey": ""
  },
  "message": "Success",
  "statusCode": 200,
  "request_id": "request-id",
  "timestamp": "ISO-8601"
}

Error Responses

400 — Bad Request

Field	Type	Description
message	string	Description of the error
statusCode	number	HTTP status code
request_id	string	Request identifier
timestamp	string	ISO 8601 timestamp

401 — Unauthorized

Field	Type	Description
message	string	Authentication or authorization failure
statusCode	number	HTTP status code
request_id	string	Request identifier
timestamp	string	ISO 8601 timestamp

404 — TPN Not Found

Field	Type	Description
message	string	Indicates the TPN was not found
statusCode	number	HTTP status code
request_id	string	Request identifier
timestamp	string	ISO 8601 timestamp

422 — Validation Error

Field	Type	Description
message	string	Validation failure details
statusCode	number	HTTP status code
request_id	string	Request identifier
timestamp	string	ISO 8601 timestamp

Get TPN Details

Use this API to retrieve OTP, Auth Token, SPIn details, and integration type.

Request

{
  "tpnId": "abcdef123456",
  "dataFields": ["OTP", "AUTH_TOKEN", "INTEGRATION_TYPE"]
}

Response (200)

{
  "data": {
    "oneTimePasscode": "123456",
    "auth_token": "token-value",
    "integration_type": "spinCloud",
    "spinDetails": {
      "registerId": "",
      "authKey": ""
    }
  },
  "status_code": 200,
  "request_id": "IPOS-20250216120000-ABC123",
  "timestamp": "2025-02-16T12:00:00.000Z"
}

Merchant Onboarding Batch Report