Create and submit merchant application. Initial status of application is "UW Level 1"

Time	Status	User Agent
Retrieving recent requests…

Create and Submit Merchant Application

⚠️
Deprecated — use POST /api/v2/merchant/submit instead.

Submits a complete merchant application including business details, owner information, banking data, site inspection, service acceptance, fees, and equipment. On success returns a merchantProfileId used in all subsequent boarding API calls. The application is placed in UW Level 1 status immediately upon submission.

Endpoint

POST /api/v1/merchant/submit

Authentication

Basic HTTP Authentication required.

Authorization: Basic {base64(username:password)}

When to use

Use this as the initial step in the merchant boarding flow after an ISO agent has collected all required merchant data. For new integrations, prefer POST /api/v2/merchant/submit. Use v1 only for legacy integrations.

Request Body

Top-level structure

Field	Type	Required	Description
merchantProfile	TsysMerchant	Yes	Agent, POS type, and cash discount settings
businessAndOwnerInformation	TsysParameters	Yes	Business details, addresses, owners, controlling officers
salesAndBusinessProfile	TsysMerchantAccount	Yes	Sales volumes, banking info, business type
siteInspection	TsysSiteInspection	Yes	Physical/online site inspection details
serviceAcceptance	TsysProductSetup	Yes	Card types and networks accepted
fees	TsysFees	No	Full fee structure
equipment	TsysEquipment	Yes	Terminal equipment
merchantProfileId	integer	No	Provide to re-submit an existing draft

`merchantProfile` (TsysMerchant)

Field	Type	Required	Description
agentProfileId	integer	Yes	ID of the agent submitting the application
cashDiscount	string (enum)	Yes	`No`, `Yes`
pos	string (enum)	Yes	POS system. See enum values below
boardingSettingsId	integer	No	Boarding settings template ID
mid	string	No	Pre-assigned Merchant ID
externalClientID	string	No	External client reference ID
externalChainID	string	No	External chain reference ID

pos enum values: None, AptitoPalomaPOS, Clover, PalomaPOS, Aldelo, Restoactive, PoyntPOS, CloverGo, UnifiedMpos, CustomPos, RetailCloud, EHopper, FreedomPos, ClubPos, SelfLane, OtfPOS, NProKiosk, GretaPOS

`businessAndOwnerInformation` (TsysParameters)

Field	Type	Required	Description
customerServicePhoneNum	string	Yes	10-digit phone, must not start with 1
federalTaxId	string	Yes	9-digit EIN (`^\d{9}$` or masked with `*`)
dateOfStartBusiness	string (date-time)	Yes	Business start date ISO 8601
merchantEmail	string	No	Merchant contact email
merchantWebsite	string	No	Business website URL
multipleLocations	boolean	No	Whether merchant has multiple locations
numOfLocations	integer	No	Number of locations
legalAddress	AddressBase	Yes	Legal registered address
dbaAddress	AddressBase	Yes	DBA operating address
primaryOwner	Owner	Yes	Primary owner details
secondaryOwner	SecondaryOwner	No	Second owner
owner3	SecondaryOwner	No	Third owner
owner4	SecondaryOwner	No	Fourth owner
controllingOfficer1	ControllingOfficer	No	Controlling officer 1
controllingOfficer2	ControllingOfficer	No	Controlling officer 2

AddressBase (used for legalAddress and dbaAddress):

Field	Type	Required	Description
name	string	Yes	Business name at this address
address	string	Yes	Street address line 1
address2	string	No	🆕 Suite, unit, floor, apartment
postalCode	string	Yes	ZIP code
city	string	Yes	City
state	string (enum)	Yes	Full US state name, e.g. `Georgia`
phone	string	Yes	Phone, must not start with 1
fax	string	No	Fax number

state enum: Alaska, Alabama, Arkansas, Arizona, California, Colorado, Connecticut, DistrictOfColumbia, Delaware, Florida, Georgia, Hawaii, Iowa, Idaho, Illinois, Indiana, Kansas, Kentucky, Louisiana, Massachusetts, Maryland, Maine, Michigan, Minnesota, Missouri, Mississippi, Montana, NorthCarolina, NorthDakota, Nebraska, NewHampshire, NewJersey, NewMexico, Nevada, NewYork, Ohio, Oklahoma, Oregon, Pennsylvania, PuertoRico, RhodeIsland, SouthCarolina, SouthDakota, Tennessee, Texas, Utah, Virginia, VirginIslands, Vermont, Washington, Wisconsin, WestVirginia, Wyoming

Owner (used for primaryOwner):

Field	Type	Required	Description
firstName	string	Yes	2–25 letters only
lastName	string	Yes	2–25 letters only
middleName	string	No	2–25 letters only
dateOfBirth	string (date-time)	Yes	Date of birth
ssn	string	Yes	9-digit SSN, no sequential/repeated patterns
address	string	Yes	Street address, max 40 chars, alphanumeric
city	string	Yes	2–25 chars
state	string (enum)	Yes	Full US state name
zip	string	Yes	5 or 9 digit ZIP (`^\d{5}(-\d{4})?$`)
homePhone	string	Yes	Must not start with 1
title	string (enum)	Yes	`President`, `VPresident`, `Owner`, `Partner`, `Manager`, `Treasurer`, `Secretary`, `ExecDirector`
ownership	integer	Yes	0–100 (ownership percentage)
email	string	Yes	Max 60 chars
guarantor	boolean	No	Whether owner is a guarantor
typeOfIssuedID	string (enum)	No	`USPassport`, `PermanentRegistrationCard`, `DriversLicense`, `USMilitaryCard`, `USCostGuardMerchantMarinerCard`, `USCitizenIdCard`
idNumber	string	No	Alphanumeric ID number
idExpirationDate	string (date-time)	No	ID expiration date

SecondaryOwner — same structure as Owner (used for secondaryOwner, owner3, owner4).

ControllingOfficer (used for controllingOfficer1 and controllingOfficer2):

Field	Type	Required	Description
firstName	string	Yes	2–25 letters only
lastName	string	Yes	2–25 letters only
middleName	string	No	2–25 letters only
dateOfBirth	string (date-time)	Yes	Date of birth
ssn	string	Yes	9-digit SSN
title	string (enum)	Yes	`President`, `VPresident`, `Owner`, `Partner`, `Manager`, `Treasurer`, `Secretary`, `ExecDirector`
address	string	Yes	Max 40 chars, alphanumeric
city	string	Yes	2–25 chars
state	string (enum)	Yes	Full US state name
zip	string	Yes	ZIP code
homePhone	string	Yes	Must not start with 1
email	string	No	🆕 Max 60 chars
guarantor	boolean	No	Whether officer is a guarantor
typeOfIssuedID	string (enum)	No	Same enum as Owner
idNumber	string	No	Alphanumeric
idExpirationDate	string (date-time)	No	ID expiration

`salesAndBusinessProfile` (TsysMerchantAccount)

Field	Type	Required	Description
sic	string	Yes	Standard Industry Classification code (4 digits)
typeOfOwnership	string (enum)	Yes	`Corporation`, `SoleProprietorship`, `Partnership`, `AssociationEstateTrust`, `TaxExempt501C`, `International`, `LimitedLiabilityLlc`, `GovernmentAgency`
businessType	string (enum)	Yes	`Other`, `Internet`, `Lodging`, `MailOrder`, `Restaurant`, `Retail`, `QSR`, `Supermarket`, `Petroleum`, `Utilities`, `Healthcare`, `Education`, `Government`, `Charity_NonProfit`, `B2B`, `Service`
accountType	string (enum)	No	`C` (Checking), `S` (Savings), `G` (General)
accountNumber	string	Yes	Bank account number, max 17 digits
businessCheckingRoutingNumber	string	Yes	9-digit ABA routing number
achMethod	string (enum)	Yes	`Combine`, `Deposit`, `CombineAndDeposit`
averageTicket	integer	Yes	Average transaction amount (minimum 1)
highTicket	integer	No	Maximum expected transaction amount (1–999999)
salesToConsumers	number	No	% of sales to consumers (0–100)
salesToBusiness	number	No	% of sales to businesses (0–100)
salesToGovernment	number	No	% of sales to government (0–100)
bankName	string	No	Name of the bank
goodsAndServices	string	No	Description of goods/services sold
returnPolicy	string	No	Merchant's return policy
nextDayFunding	boolean	No	Whether next-day funding is requested
sameDayFunding	boolean	No	Whether same-day funding is requested
isVsMcDsNetwork	boolean	No	Whether Visa/MC/Discover network is used
monthlyVolume	integer	Yes	Expected monthly processing volume (minimum 1)
annualVolume	integer	No	Read-only. Annual volume (computed)
retail	integer	Yes	% card-present transactions (0–100)
imprint	integer	Yes	% imprint transactions (0–100)
moto	integer	Yes	% mail/phone order transactions (0–100)
internet	integer	Yes	% internet transactions (0–100)
cardNotPresentInformation	TsysCnpInformation	No	Required if `internet > 0` — see below

⚠️
retail + imprint + moto + internet must equal 100.

cardNotPresentInformation (TsysCnpInformation) — required when internet % > 0:

Field	Type	Description
isWebHosting	boolean	Sells web hosting
isDomainRegistration	boolean	Sells domain registration
isWebPageDesign	boolean	Sells web design services
isAuction	boolean	Operates auction site
isInternetServiceGateway	boolean	Internet service gateway
isSellingDigitalService	boolean	Sells digital products
isAdvertisement	boolean	Sells advertising
isSellingHardGoods	boolean	Sells physical goods online
isOther	boolean	Other internet business type
otherInternetBusinessType	string	Description if `isOther` is true
saleDescription	string	Description of items sold
advertiseOrPromotion	string	How products are advertised
secureTransactionInformation	string	Security measures used
vendors	string	Vendor information
productFulfillment	string	How products are fulfilled
monthly/yearly/quarterly/oneTime/hourly	integer	Billing frequency breakdown
isMonthly/isYearly/isQuarterly/isOneTime/isHourly	boolean	Active billing frequencies

`siteInspection` (TsysSiteInspection)

Field	Type	Required	Description
inventoryMaintainedType	string (enum)	No	`OnSite`, `WarehouseOffSite`, `FulfillmentCenter`
fulfillmentCenterNameAndAddress	string	No	Address if `FulfillmentCenter`
question1	boolean	No	Is the business operating at this address?
question1Explanation	string	No	Explanation if `question1` is false
question2	boolean	No	Is the business open to the public?
question2Explanation	string	No	Explanation if `question2` is false
question3	boolean	No	Does the business have adequate signage?
question3Explanation	string	No	Explanation if `question3` is false
question4	boolean	No	Is the location consistent with the business type?
question4Explanation	string	No	Explanation if `question4` is false
zoning	string (enum)	No	`Comml`, `Industrial`, `Residential`
squareFootageType	string (enum)	No	`From_0_To_500`, `From_501_To_1000`, `From_1001_To_2000`, `From_2001_To_4000`, `Other`
squareFootageTypeOther	integer	No	Exact sq ft if `Other`
merchant	string (enum)	No	`Owns`, `Leases`
nameAddressLandlord	string	No	Landlord name and address if leasing

`serviceAcceptance` (TsysProductSetup)

Field	Type	Required	Description
amexESA	boolean	No	Accept Amex ESA
amexOptBlue	boolean	No	Accept Amex OptBlue
discover	boolean	No	Accept Discover
payPal	boolean	No	Accept PayPal
jcb	boolean	No	Accept JCB
ebt	boolean	No	Accept EBT
debitCard	boolean	No	Accept debit cards
amexNumber	string	No	10-digit Amex ESA number (required if `amexESA` = true)
fcsNumber	string	No	7-digit FCS number (required if `amexESA` = true)

`fees` (TsysFees)

Field	Type	Required	Description
minimumDiscountAmount	number	No	Minimum discount amount (0–500)
minimumDiscountStartDate	string (date-time)	No	When minimum discount starts
minimumDiscountType	string (enum)	No	`Daily`, `Monthly`
earlyTerminationFeeAmount	number	No	Early termination fee amount (0–999999)
earlyTerminationFeeContractMonths	integer	No	Contract length in months (0–60)
amex	AmexFees	No	Amex fee structure
visaMasterCardDiscover	VisaMasterCardDiscoverFees	No	Visa/MC/Discover fee structure
authorizationMonthlyAndSpecialProgram	AuthorizationMonthlyAndSpecialProgramFees	No	Auth, monthly and special program fees
pos	POSFees	No	POS software fees
standard	StandardFees	No	Standard fees (dial pay, online portal, etc.)
cardBrand	CardBrandFees	No	Card brand fee flags
debitPinAndEBT	DebitPinAndEBTFees	No	Debit PIN and EBT fees
gatewayProducts	GatewayProductsFees	No	Gateway and wireless fees
miscFees	array of TsysMiscFee	No	Custom miscellaneous fees
miscFeesVolume	array of TsysMiscFee	No	Volume-based misc fees

TsysFee (used throughout fees object):

Field	Type	Required	Description
perItem	number	Yes	Per-transaction flat fee
percent	number	Yes	Percentage fee

TsysMiscFee (for miscFees and miscFeesVolume):

Field	Type	Required	Description
name	string	Yes	Fee name (must match allowed SIF names from `GET /api/v1/SIFFeeNames`)
frequency	string (enum)	Yes	`Annual`, `SemiAnnual`, `Quarterly`, `Monthly`, `OneTime`
perItem	number	Yes	Flat fee amount
percent	number	Yes	Percentage amount
startDate	string (date-time)	No	Fee start date
stopDate	string (date-time)	No	Fee stop date
month	integer	No	Month number (for annual fees)
year	integer	No	Year (for annual fees)

authorizationMonthlyAndSpecialProgram key fee fields:

Field	Description
vsmcdiscAuth	Visa/MC/Disc authorization fee
amexAuth	Amex authorization fee
avs	Address Verification Service fee
batch	Batch settlement fee
voiceAuthorization	Voice auth fee
retrieval	Retrieval request fee
chargeback	Chargeback fee
achReject	ACH reject fee
pciAnnual	PCI annual compliance fee
pciNonCompliance	PCI non-compliance monthly fee
tinMismatch	TIN mismatch fee

`equipment` (TsysEquipment)

Field	Type	Required	Description
terminals	array of TsysTerminal	Yes	List of terminals (can be empty array `[]`)

TsysTerminal:

Field	Type	Required	Description
terminalType	string (enum)	Yes	Terminal model. See full list below

terminalType enum: HYPERCOM_M4230_SPOSDCC, HYPERCOM_T4230_SPOSDCC, INGENICO_ICT220_INGEMV4, INGENICO_ICT220CTL_INGEMV4, INGENICO_ICT250_INGEMV4, INGENICO_IWL220_INGEMV4, INGENICO_IWL250_INGEMV4, INGENICO_IPP320_INGEMV4, VERIFONE_VX520_XEVA440, VERIFONE_VX680_XEVA440, CLSBPLUS_PAX, MULTIPASS, HCSTAGE, DIAL_PAY, NETEVIA_GATEWAY, AUTH_NET_GATEWAY, NMI_Unified_Gateway, USAePay_Gateway, Aldelo_EDC, Cardflight_mPOS, Dejavoo_Z8, Dejavoo_Z9, Dejavoo_Z11, Pax_S80, Pax_S300, Poynt, EHopper, Freedom_POS, Netevia_Light_POS, STGENCR, HCSTGEN, ValorVP100, ValorVP300, DejavooQD2, DejavooQD4, DejavooQD3, DejavooQD5, DejavooP1, DejavooP3, DejavooP5, ValorVL100, ValorVL300, ValorVL110, ValorVP550, ValorVP800, ValorRCKT, ValorVirtualTerminal

Full Request Example

{
  "merchantProfile": {
    "cashDiscount": "No",
    "agentProfileId": 201,
    "pos": "Clover",
    "boardingSettingsId": 15
  },
  "businessAndOwnerInformation": {
    "customerServicePhoneNum": "8005551234",
    "federalTaxId": "123456789",
    "dateOfStartBusiness": "2018-03-15T00:00:00Z",
    "merchantEmail": "[email protected]",
    "merchantWebsite": "https://greentreecafe.com",
    "legalAddress": {
      "name": "Green Tree Cafe LLC",
      "address": "450 Main St",
      "address2": "Suite 100",
      "postalCode": "30301",
      "city": "Atlanta",
      "state": "Georgia",
      "phone": "4045557890"
    },
    "dbaAddress": {
      "name": "Green Tree Cafe",
      "address": "450 Main St",
      "address2": "Suite 100",
      "postalCode": "30301",
      "city": "Atlanta",
      "state": "Georgia",
      "phone": "4045557890"
    },
    "primaryOwner": {
      "firstName": "Marcus",
      "lastName": "Jordan",
      "dateOfBirth": "1978-06-21T00:00:00Z",
      "ssn": "500123456",
      "address": "112 Peachtree Ln",
      "city": "Atlanta",
      "state": "Georgia",
      "zip": "30302",
      "homePhone": "4045559876",
      "title": "Owner",
      "ownership": 100,
      "email": "[email protected]",
      "guarantor": true,
      "typeOfIssuedID": "DriversLicense",
      "idNumber": "GA123456789",
      "idExpirationDate": "2028-06-21T00:00:00Z"
    },
    "controllingOfficer1": {
      "firstName": "Sarah",
      "lastName": "Jordan",
      "dateOfBirth": "1980-04-10T00:00:00Z",
      "ssn": "500987654",
      "title": "President",
      "address": "112 Peachtree Ln",
      "city": "Atlanta",
      "state": "Georgia",
      "zip": "30302",
      "homePhone": "4045559877",
      "email": "[email protected]"
    }
  },
  "salesAndBusinessProfile": {
    "sic": "5812",
    "typeOfOwnership": "LimitedLiabilityLlc",
    "businessType": "Restaurant",
    "accountNumber": "123456789012",
    "businessCheckingRoutingNumber": "061000104",
    "achMethod": "Combine",
    "averageTicket": 3500,
    "highTicket": 15000,
    "monthlyVolume": 120000,
    "retail": 90,
    "imprint": 0,
    "moto": 5,
    "internet": 5,
    "bankName": "Bank of America",
    "goodsAndServices": "Full-service restaurant serving American cuisine",
    "returnPolicy": "No refunds on food; merchandise returns within 30 days",
    "cardNotPresentInformation": {
      "isSellingHardGoods": false,
      "isOther": true,
      "otherInternetBusinessType": "Online reservations and gift card sales",
      "saleDescription": "Online gift cards and table reservations",
      "isMonthly": true
    }
  },
  "siteInspection": {
    "inventoryMaintainedType": "OnSite",
    "zoning": "Comml",
    "squareFootageType": "From_1001_To_2000",
    "merchant": "Leases",
    "nameAddressLandlord": "Peachtree Properties, 800 Corp Blvd, Atlanta GA 30303",
    "question1": true,
    "question2": true,
    "question3": true,
    "question4": true
  },
  "serviceAcceptance": {
    "amexOptBlue": true,
    "discover": true,
    "debitCard": true,
    "payPal": false,
    "jcb": false,
    "ebt": false
  },
  "fees": {
    "minimumDiscountAmount": 25.00,
    "minimumDiscountType": "Monthly",
    "earlyTerminationFeeAmount": 295,
    "earlyTerminationFeeContractMonths": 36,
    "authorizationMonthlyAndSpecialProgram": {
      "vsmcdiscAuth": { "perItem": 0.10, "percent": 0.0 },
      "amexAuth": { "perItem": 0.10, "percent": 0.0 },
      "avs": { "perItem": 0.02, "percent": 0.0 },
      "chargeback": { "perItem": 25.00, "percent": 0.0 },
      "retrieval": { "perItem": 10.00, "percent": 0.0 },
      "pciAnnual": { "perItem": 99.00, "percent": 0.0 },
      "pciNonCompliance": { "perItem": 29.99, "percent": 0.0 }
    },
    "miscFees": [
      {
        "name": "SERVICE FEE",
        "frequency": "Monthly",
        "perItem": 9.95,
        "percent": 0.0
      }
    ]
  },
  "equipment": {
    "terminals": [
      { "terminalType": "Poynt" }
    ]
  }
}

Response

200 OK

Field	Type	Description
data.merchantProfileId	integer	Unique ID assigned to the submitted application — use in all subsequent calls
status	string	HTTP status name, e.g. `OK`
error	string	Error message if failed, otherwise null
warning	string	Non-fatal warning if any
validationResults	array	Field-level validation errors if any
requestId	integer	Internal request tracking ID

{
  "data": {
    "merchantProfileId": 10482
  },
  "status": "OK",
  "error": null,
  "warning": null,
  "validationResults": [],
  "requestId": 456
}

Error Codes

Code	When it happens
400	Missing required fields or validation errors — check `validationResults` for details
401	Invalid or missing Basic Auth credentials
403	No permission to submit under this agent profile
404	`agentProfileId` or `boardingSettingsId` not found
500	Internal server error

Common Mistakes

retail + imprint + moto + internet must equal exactly 100 — any other sum causes a 400 error.
customerServicePhoneNum must be exactly 10 digits, no dashes or spaces, must not start with 1.
federalTaxId must be exactly 9 digits matching ^\d{9}$ or masked with *.
businessCheckingRoutingNumber must be exactly 9 digits.
ssn must be 9 digits and cannot be sequential (123456789) or repeated (111111111).
address2 is optional — omitting it does not affect existing integrations.
Controlling officer email is optional — omitting it does not affect existing integrations.
cardNotPresentInformation should be provided when internet > 0.
amexNumber (10 digits) and fcsNumber (7 digits) are required when amexESA: true.
This is a deprecated v1 endpoint — prefer POST /api/v2/merchant/submit for new integrations.

Related Endpoints

POST /api/v2/merchant/submit — recommended v2 replacement
POST /api/v1/merchant/parameters — update business and owner info after submission
GET /api/v1/merchant/status — check application status after submission
GET /api/v1/merchant/underwritingNotes — retrieve underwriting notes

Example

curl -X POST https://hq.staging.netevia.dev/api/v1/merchant/submit \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{ ... request body ... }'

Create and submit merchant application. Initial status of application is "UW Level 1"