Management API

## Sections
• [Merchant Onboarding API](https://app.theneo.io/dejavoo/management-api/introduction.md): Merchant Onboarding API enable ISOs to programmatically onboard and manage merchants, stores, and TPNs directly from external systems (CRM/portal), eliminating manual portal interaction. With this API, all data entered in your CRM or portal is automatically synced with the iPOSpays portal, enabling you to onboard merchants conveniently and efficiently. Supported Operations Title Description Entity Operations Merchant Onboard, Edit Store Add, Edit TPN Add, Edit, Get Details Key Capabilities Onboard a completely new merchant along with their first store and TPN. Enable merchant-level add-on features (e.g., Whitelisting) Expand an existing merchant’s setup by adding a new store and TPN. Request and retrieve required TPN parameter information like OTP, AUTH-TOKEN, SPIN details (i.e., Registered Id, AUTH-KEY) Enable or disable specific TPN parameters like SPIn Enable store-level add-on features (e.g., ACH) Prerequisites Before invoking any API in this document, the following conditions must be satisfied: The ISO (Independent Sales Organization) must already be onboarded in the iPOSpays portal. The following entities must be created and active, except the onboard API call: Merchant Store TPN (Terminal Profile Number) The integrator must possess: API Key Secret Key These are required to generate an Access Token , which must be included in all subsequent API calls. Contact support@dejavoo.io and CC your sales executive to get the API and Secret Key
  • [Merchant](https://app.theneo.io/dejavoo/management-api/introduction/merchant-api.md): This section includes APIs for: Merchant, Store, and 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. Title Description Indicator Description * Mandatory # Pre-defined values shared in these documents API Details API Request URL Title Description 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: Title Description Title Field Description onboardmerchant ( API ) 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 Request Parameters Header Authorization – Request Parameters Title Description Objects Description Authorization API KEY <your-api-key-value> Content-Type application/json Body – Request Parameters Title Description Title 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. Title Description 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. Title Description Title ield 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 (Paynetworx) 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) 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) 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) 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) 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) 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) 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 Title Description 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](https://app.theneo.io/dejavoo/management-api/introduction/merchant-api/creation-of-merchant-store-and-tpn.md): 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 Title Description Object Description Method POST Header Authorization Info Title Description Object Description Authorization api-key <your-api-key-value> Content-Type application/json Pre-defined Input Field – Values and Description Title Description Field Description Processor Name details ( Field & Descriptions ) 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 ) 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 ) Title Description SIMPLE SIMPLE type Application Signature details ( Field & Descriptions ) 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. Plain text { "merchantData": { "dba": "<DBA>", "firstName": "<firstName>", "lastName": "<lastName>", "email": "<email>", "addressLine1": "<addressLine1>", "addressLine2": "<addressLine2>", "zipCode": "<zipCode>", "phoneNumber": "<phoneNumber>", "ebt": "<EBT>", "isoAgentReference": "<isoAgentReference>", "isoMerchant": "<isoMerchant>", "merchantLogoUrl": "<merchantLogoUrl>", "ISDcode": "<ISDcode>" }, "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" } ] } } } { "merchantData": { "dba": "<DBA>", "firstName": "<firstName>", "lastName": "<lastName>", "email": "<email>", "addressLine1": "<addressLine1>", "addressLine2": "<addressLine2>", "zipCode": "<zipCode>", "phoneNumber": "<phoneNumber>", "ebt": "<EBT>", "isoAgentReference": "<isoAgentReference>", "isoMerchant": "<isoMerchant>", "merchantLogoUrl": "<merchantLogoUrl>", "ISDcode": "<ISDcode>" }, "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" } ] } } } Processor-Specific Data Formats Each processor has a unique set of required and optional fields. Below is a breakdown of the input structure for each processor. The reference for processor request information in the tpnData object is provided below. For TSYS Processor: Sample Payload: JSON "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: Sample Payload: JSON "tpnProcessor": { "processorName": "PNWX", "profile": [ { "profileId": "01", "AccessTokenUser":"Access token user", "AccessTokenPassword":"Access token password" }, { "profileId": "02", "AccessTokenUser":"98984949484985", "AccessTokenPassword":"98e98e9e88888" } ] } For CKNX Processor: Sample Payload: JSON "tpnProcessor": { "processorName": "CKNX", "profile": [ { "profileId": "01", "apiKey": "apikey" }, { "profileId": "02", "apiKey": "apikey" } ] } For ZCRD Processor: Sample Payload: JSON "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: Sample Payload: JSON "tpnProcessor": { "processorName": "FDRC", "profile": [ { "profileId": "01", "Mid": "Mid number info", "TermId": "TermId number info", "GroupId": "Group Number info", "EcommURL":"Ecomm URL info" }, { "profileId": "02", "Mid": "Mid number info", "TermId": "TermId number info", "GroupId": "Group Number info", "EcommURL":"Ecomm URL info" } ] } For WPAY Processor: Sample Payload: JSON "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: Sample Payload: JSON "tpnProcessor": { "processorName": "ELVN", "profile": [ { "profileId": "01", "TermId": "TermId number info", "Mid": "Mid number info", "BankNo": "Bank Number Info" } ]
    • [Edit Merchant](https://app.theneo.io/dejavoo/management-api/introduction/merchant-api/edit-merchant.md): 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 JSON { "merchantId": "merchId-12-chars", "whitelistDomains": { "originUrls": [ "https://example.com", "https://store.example.com" ] } }
  • [Store](https://app.theneo.io/dejavoo/management-api/introduction/store-api.md): 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. Device Compatibility Device model and manufacturer must match supported combinations: Title Description 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. Error Responses Title Description Status Code Description 400 Bad Request 401 Unauthorized
    • [Creation of Store,TPN](https://app.theneo.io/dejavoo/management-api/introduction/store-api/creation-of-store-tpn.md): Sample JSON – Store-TPN Creation
    • [Edit Store](https://app.theneo.io/dejavoo/management-api/introduction/store-api/edit-store.md): 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 Request (Payroc ACH) JSON { "storeI1d": "storeId-12-chars", "achDetails": { "achStatus": true, "achProcessorName": "Payroc", "payrocDetails": { "clientId": "123456" } } } Request (Paya ACH) JSON { "storeId": "storeId-12-chars", "achDetails": { "achStatus": true, "achProcessorName": "Paya", "payaDetails": { “isMandatoryCheck": true, "terminalSettings":{ "web": "1234", "tel": "5678", "ppd": "9012", "ccd": "3456" } } } } Request (Disable ACH) JSON { "storeId": "storeId-12-chars", "achDetails": { "achStatus": false } }
  • [TPN](https://app.theneo.io/dejavoo/management-api/introduction/tpn-api.md): 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.
    • [Creation of TPN](https://app.theneo.io/dejavoo/management-api/introduction/tpn-api/creation-of-tpn.md): Sample JSON Request – TPN Creation
    • [Edit TPN](https://app.theneo.io/dejavoo/management-api/introduction/tpn-api/edit-tpn.md): 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 (SPIN Cloud): JSON { "tpnId": "abcdef123456", "integrationDetails": { "integrationType": "spin", "spinMode": "cloud", "isvName": "iPOSpays", "deviceModel": "P1" } } Request (SPIN Local): JSON { "tpnId": "abcdef123456", "integrationDetails": { "integrationType": "spin", "spinMode": "local" } } Request (Disable Integration): JSON { "tpnId": "abcdef123456", "integrationDetails": { "integrationType": "none" } }
    • [Get TPN Details](https://app.theneo.io/dejavoo/management-api/introduction/tpn-api/get-tpn-details.md): Use this API to retrieve OTP, Auth Token, SPIn details, and integration type. Request: JSON { "tpnId": "abcdef123456", "dataFields": ["OTP", "AUTH_TOKEN", "INTEGRATION_TYPE"] }