Submit Merchant Application V2

Submits the full merchant application to the TSYS processor in a single atomic call. Combines merchant profile, business and owner information, sales profile, site inspection, service acceptance, fees, and equipment into one submission. On success the merchant is queued for underwriting review at UW Level 1 status.

Endpoint

POST /api/v2/merchant/submit

Authentication

Basic HTTP Authentication required.

Authorization: Basic {base64(username:password)}

When to use

Use this as the preferred submission method for V2 integrations. It can be used to submit a new merchant in one shot, or to finalize a draft previously created with POST /api/v2/merchant/create. After a successful call, use GET /api/v1/merchant/status to track the processing status.

Differences from V1

Request Body

Top-level structure

merchantProfile (TsysMerchantV2Edit)

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

businessAndOwnerInformation (TsysParameters)

AddressBase (used for legalAddress and dbaAddress):

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):

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

ControllingOfficer (used for controllingOfficer1 and controllingOfficer2):

salesAndBusinessProfile (TsysMerchantAccount)

⚠️

retail + imprint + moto + internet must equal exactly 100.

cardNotPresentInformation (TsysCnpInformation) — provide when internet > 0:

siteInspection (TsysSiteInspection)

serviceAcceptance (TsysProductSetup)

fees (TsysFeesV2)

V2 adds cashDiscountRate compared to V1 fees schema.

TsysFee (base fee object used throughout):

TsysPOSFee (used in pos fees):

TsysFeeDiscountType (used in noSurcharge and debit fees):

authorizationMonthlyAndSpecialProgram key fields:

AmexFees — choose one pricing model:

VisaMasterCardDiscoverFees — choose one pricing model:

TsysMiscFee (for miscFees / miscFeesVolume):

StandardFees:

GatewayProductsFees:

DebitPinAndEBTFees:

CardBrandFees:

POSFees — POS software license fees (TsysPOSFee each):

equipment (TsysEquipment)

TsysTerminal:

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": {
    "feesProgram": "Traditional",
    "agentProfileId": 204,
    "pos": "Clover",
    "boardingSettingsId": 15
  },
  "businessAndOwnerInformation": {
    "customerServicePhoneNum": "8005550100",
    "federalTaxId": "471234567",
    "dateOfStartBusiness": "2019-01-15T00:00:00Z",
    "merchantEmail": "[email protected]",
    "merchantWebsite": "https://www.tlcrestaurant.com",
    "multipleLocations": false,
    "legalAddress": {
      "name": "TLC Restaurant Inc",
      "address": "850 Main Street",
      "address2": "Suite 100",
      "postalCode": "90210",
      "city": "Beverly Hills",
      "state": "California",
      "phone": "3105550180"
    },
    "dbaAddress": {
      "name": "TLC Bistro",
      "address": "850 Main Street",
      "address2": "Suite 100",
      "postalCode": "90210",
      "city": "Beverly Hills",
      "state": "California",
      "phone": "3105550180"
    },
    "primaryOwner": {
      "firstName": "Angela",
      "lastName": "Torres",
      "dateOfBirth": "1975-07-04T00:00:00Z",
      "ssn": "456781239",
      "address": "200 Palm Drive",
      "city": "Beverly Hills",
      "state": "California",
      "zip": "90210",
      "homePhone": "3105550292",
      "title": "Owner",
      "ownership": 100,
      "email": "[email protected]",
      "guarantor": true,
      "typeOfIssuedID": "DriversLicense",
      "idNumber": "CA987654321",
      "idExpirationDate": "2029-07-04T00:00:00Z"
    },
    "controllingOfficer1": {
      "firstName": "Maria",
      "lastName": "Torres",
      "dateOfBirth": "1978-09-20T00:00:00Z",
      "ssn": "456789001",
      "title": "President",
      "address": "200 Palm Drive",
      "city": "Beverly Hills",
      "state": "California",
      "zip": "90210",
      "homePhone": "3105550293",
      "email": "[email protected]"
    }
  },
  "salesAndBusinessProfile": {
    "sic": "5812",
    "typeOfOwnership": "Corporation",
    "businessType": "Restaurant",
    "accountNumber": "123456789012",
    "businessCheckingRoutingNumber": "021000021",
    "achMethod": "Combine",
    "averageTicket": 4500,
    "highTicket": 20000,
    "monthlyVolume": 85000,
    "retail": 95,
    "imprint": 0,
    "moto": 5,
    "internet": 0,
    "bankName": "JPMorgan Chase",
    "goodsAndServices": "Full-service restaurant serving American cuisine",
    "returnPolicy": "No refunds on food; merchandise returns within 30 days"
  },
  "siteInspection": {
    "inventoryMaintainedType": "OnSite",
    "zoning": "Comml",
    "squareFootageType": "From_1001_To_2000",
    "merchant": "Leases",
    "nameAddressLandlord": "Beverly Hills Properties LLC, 100 Rodeo Dr, Beverly Hills CA 90210",
    "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

{
  "data": {
    "merchantProfileId": 30912
  },
  "requestId": 456,
  "success": true,
  "error": null,
  "validationErrors": []
}

Error Codes

Common Mistakes

• retail + imprint + moto + internet must equal exactly 100 — any other sum causes a 400 error.
• feesProgram is required in V2 — unlike V1 which used a cashDiscount string flag.
• pos is required — use None if no specific POS system.
• federalTaxId must be exactly 9 digits — no dashes (47-1234567 is invalid).
• accountNumber must be purely numeric, max 17 digits — no dashes or spaces.
• businessCheckingRoutingNumber must be exactly 9 digits.
• ssn must be 9 digits and cannot match sequential or repeated patterns.
• cardNotPresentInformation should be provided when internet > 0.
• amexNumber (10 digits) and fcsNumber (7 digits) are required when amexESA: true.
• address2 and controlling officer email are optional and backward compatible.
• Providing merchantProfileId links to an existing record — omit it to create a new one.

Related Endpoints

• GET /api/v2/agent/profile — get agentProfileId before submitting
• POST /api/v2/merchant/create — create a minimal draft before building up to full submit
• POST /api/v2/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/v2/merchant/submit \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{ ... request body ... }'