Apidocs

Merchant Onboarding

Prerequisites

Before using the Merchant Onboarding API, ensure you have the following:

ISO Registration on iPOSpays
- You must already be onboarded on the iPOSpays portal as an ISO.
Customer ID and Authentication API Key
- To obtain these credentials, send an email to devsupport@denovosystem.com and copy your Dejavoo sales representative.
- You will receive your Customer ID and API Key, which are required for all API requests.

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
Production URL	https://externalapi.ipospays.com/v1/onboardmerchant

API Reference

The onboardmerchant API request contains 3 primary objects

Field	Description
onboardmerchant ( API )
merchantData	It’s mandatory object This Objects contains the following information merchant dba, email-id first name last name address zip-code phone number ebt info (optional)
storeData	it’s a mandatory object. This Objects contains the following information store dba email-id first name last name address zip-code phone number merchant category code etc…
tpnData	it’s a mandatory object. This Objects contains the following information device manufacturer device model routing type application sign bin number assign template processor information

Request Parameters

Header Authorization – Request Parameters

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

Body – Request Parameters

Field	Type	Description
merchantData ( Obj )
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 charsAllowed special chars: Length: min – 2, max – 35 characters
addressLine2 (Optional)	string	Merchant address line 2 Format: Alphanumeric, special charsAllowed 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 )
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 charsAllowed special chars: Length: min – 2, max – 35 characters
addressLine2 (Optional)	string	Store address info line 2 Format: Alphanumeric, special charsAllowed 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 )
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 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.

Field	Type	Description
Processor : ( TSYS )
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 )
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 )
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 )
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 : ( FRDC )
tpnProcessor *	Object	Note: object name as specified in doc
processorName *	String	Format: Alphabets Values: FRDC 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
Processor : ( WPAY )
TermId *	Numbers	Term Id input value Length: max – 16 characters Format - Numeric
Mid *	Numbers	Mid input value Length: max – 12 characters Format - Numeric
BankId *	Numbers	Bank Id input value Length: max – 6 characters Format - Numeric
Processor : ( ELVN )
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

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

Field	Description
Processor Name details ( Field & Descriptions )
TSYS	TSYS processor
PNWX	PNWX processor
CKNX	CKNX processor
ZCRD	ZCRD processor
FRDC	FRDC processor
WPAY	WPAY processor
ELVN	ELVN processor
Device Manufacturer details ( Field & Descriptions )
WizardPOS	WizarPOS manufacturer
Kozen	Kozen manufacturer
Cloud POS	Cloud POS manufacturer
Android Phone	Android Phone
Device Model details ( Device Model and their Manufacturers )
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 )
SIMPLE	SIMPLE type
Application Signature details ( Field & Descriptions )
CRDT	Credit Debit

Sample JSON Request – Create Merchant, Store, and TPN

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",        
        "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"
    },
 
    "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 
                           ]    
                        }
    }
}

Processor-Specific Data Formats

Note: 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 FRDC Processor

 "tpnProcessor":
{
    "processorName": "FRDC",
    "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 ELVN Processor

 "tpnProcessor":
{
    "processorName": "ELVN",
    "profile":
    [
      {
        "profileId": "01",
            "TermId": "TermId number info",
            "Mid": "Mid number info",
            "BankNo": "Bank 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"
    }
}

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 – on create of Store-TPN

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"
        },
        "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 – on create of Store-TPN

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 – on create of TPN

Header

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

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 StatusResponseCode : 401 (UnAuthorized Access)

    {
	message: "Unauthorized Access / Forbidden",
    }

http StatusResponseCode : 200 (OK)

    {
    message: "Merchant created successfully",
	data: {
		// response data
	      }
    }

http StatusResponseCode : 400 (Bad request)

    {
    code: "error-code",
	message: "error-message",
	param: "error-on-field"
    }

API Simulator

Use the Postman API simulator below to test our onboardMerchant API:

URL: Postman API Simulator (opens in a new tab)

Need Help

devsupport@denovosystem.com

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

Onboard Merchant Tap to Pay on Android