NAV Navbar

Logo

Introduction

Usio - Enrollment API Documentation

Usio Enrollment API is a robust web service with SOAP, WCF and REST/JSON endpoints.
You will be able to create sub-merchants as well as view their current status.

Last updated on, 05/04/2021 © Usio.

Change Log

DateAuthorVersionChange Summary
11/9/2018 Tracy Rickman 1.0 Initial web release
1/28/2019 Rachel Carlini 1.1 Updated endpoints
3/25/2019 Rachel Carlini 1.2 Added webhook section
4/16/2019 Rachel Carlini 1.3 Added sandbox environment
7/24/2019 Andrew Reese 1.4 Usio brand update
8/26/2019 Andrew Reese 1.5 Added disableWelcomeEmail boolean to CreateMerchant method
9/03/2019 Rachel Carlini 1.6 Added filter parameter to GetMerchantStatus call
2/11/2020 Rachel Carlini 1.7 Added GetCategoryCodes method
6/22/2020 Tracy Rickman 1.8 Added fees account and time zone to CreateMerchant method
6/25/2020 Rachel Carlini 1.9 Added AddOwner method
09/28/2020 Rachel Carlini 1.10 Added PinlessMCC field
05/04/2021 Rachel Carlini 1.11 Added Risk Response for Sandbox KYC

Environment

PRODUCTION https://enroll.securepds.com

Production

https://enroll.securepds.com

SOAP/WFC WSDL

https://enroll.securepds.com/enroll.svc?wsdl

REST/JSON Endpoints and definitions:

https://enroll.securepds.com/enroll.svc/JSON/help

Sandbox

https://devenroll.usiopay.com

SOAP/WFC WSDL

https://devenroll.usiopay.com/enroll.svc?wsdl

REST/JSON Endpoints and definitions:

https://devenroll.usiopay.com/enroll.svc/JSON/help

Required Parameters in all calls

Parameter NameDescription
merchantID Merchant ID assigned by Usio
login API Username
passwordAPI Password

Parameter values for sandbox

parameter nametest value
merchantID 12706313
login API12706313
password2pscavkjwe

Enrollment

Create Sub-Merchant

POST https://enroll.securepds.com/enroll.svc/JSON/CreateMerchant

            
{
   "merchantID": "string",
   "login": "string",
   "password": "string",
   "emailAddress": "string",
   "dbaName": "string",
   "legalName": "string",
   "businessDesc": "string",
   "businessStartDate": "string",
   "mcc": "string",
   "pinlessMCC": "string",
   "naics": "string",
   "ownershipType": "string",
   "fedTaxID": "string",
   "addressLine1": "string",
   "addressLine2": "string",
   "city": "string",
   "state": "string",
   "postalCode": "string",
   "busPhoneNo": "string",
   "website": "string",
   "ccMonthlyVolume": "string",
   "ccAverageTicket": "string",
   "ccHighTicket": "string",
   "achMonthlyVolume": "string",
   "achAverageTicket": "string",
   "achHighTicket": "string",
   "swipedPercent": int,
   "keyedPercent": int,
   "eComPercent": int,
   "principalFirstName": "string",
   "principalLastName": "string",
   "principalTitle": "string",
   "principalAddress1": "string",
   "principalAddress2": "string",
   "principalCity": "string",
   "principalState": "string",
   "principalPostalCode": "string",
   "principalPhoneNo": "string",
   "principalDOB": "string",
   "principalLast4SSN": "string",
   "ownershipPercent": 0,
   "accountHolderName": "string",
   "bankRouteNo": "string",
   "bankAccountNo": "string",
   "isPersonal": false,   
   "feesAccountHolderName": string,
   "feesBankRouteNo": string,
   "feesBankAccountNo": string,
   "feesAccountIsPersonal": false,
   "webhook_url": "string",
   "disableWelcomeEmail": false,
   "timeZoneID": int
}
                
            

The above command returns the following JSON structure:

            
{
   "message": "string",
   "status": "string",
 "validationErrors":
         [ 
           { 
      	     "errorDescription": "string",
      	     "fieldName": "string"
           }
      ],
   "guid": "string"
}
                
            

Enroll a merchant in Usio

Important Information

In order to simulate a KYC failure, please send "999999999" as the Federal Tax ID. When the click-to-agree form is submitted with this value, the KYC checks will fail and the account will be placed into the Risk status.

HTTP Request

POST https://enroll.securepds.com/enroll.svc/JSON/CreateMerchant

Parameters

NameTypeRequiredLengthDescription
merchantID string Required 50 Your Merchant ID
login string Required 50 Username for the Enrollment Site
password string Required 100 Password for the Enrollment Site
emailAddress string Required 50 Business Address
dbaName string Required 50 Doing Business As Name
legalName string Required 50 Legal Business Name / Legal Name if Sole Prop
businessDesc string Optional 50 Business Description
businessStartDate string Optional N/A Date of Business Start
mcc string Optional 10 Merchant Category Code
pinlessMCC string Optional 10 Merchant Category Code for Pinless transactions
naics string Optional 10 NAICS Code
ownershipType string Optional 50 Ownership Types: "Partnership Public", "C-Corp Private", "S-Corp Private", "Sole Prop", "Partnership Private", "LLC Private", "Not For Profit", "C-Corp Public", "S-Corp Public", "Government Agency", "LLC Public"
fedTaxID string Optional 11 Federal Tax ID / SSN if Sole Prop
addressLine1 string Optional 50 Business Address Line 1
addressLine2 string Optional 50 Business Address Line 2
city string Optional 38 Business City
state string Optional 2 Business State
postalCode string Optional 5 Business Postal Code
busPhoneNo string Optional 12 Business Phone Number
website string Optional 50 Business Website
ccMonthlyVolume string Optional 0 - 1,000,000 CC Monthly Volume
ccAverageTicket string Optional 0 - 1,000,000 CC Average Ticket
ccHighTicket string Optional 0 - 1,000,000 CC High Ticket
achMonthlyVolume string Optional 0 - 1,000,000 ACH Monthly Volume
achAverageTicket string Optional 0 - 1,000,000 ACH Average Ticket
achHighTicket string Optional 0 - 1,000,000 ACH High Ticket
swipedPercent int Optional 0 - 100, whole numbers only Percentage of Business Done via Card Swiped
keyedPercent int Optional 0 - 100, whole numbers only Percentage of Business Done via Keyed Card (Card Not Present)
eComPercent int Optional 0 - 100, whole numbers only Percentage of Business Done via eCommerce
principalFirstName string Optional 50 Principal First Name
principalLastName string Optional 50 Principal Last Name
principalTitle string Optional 50 Principal Title
principalAddress1 string Optional 50 Principal Address Line 1
principalAddress2 string Optional 50 Principal Address Line 2
principalCity string Optional 38 Principal City
principalState string Optional 2 Principal State
principalPostalCode string Optional 5 Principal Postal Code
principalPhoneNo string Optional 12 Principal Phone Number
principalDOB string Optional N/A Principal DOB
principalLast4SSN string Optional 4 Principal Last 4 SSN
ownershipPercent int Optional 0 - 100, whole numbers only Ownership Percentage
accountHolderName string Optional 50 Name on Account
bankRouteNo string Optional 9 Settlement Account Routing Number
bankAccountNo string Optional 4 - 17 Settlement Account Number
isPersonal boolean Optional N/A Settlement Account Type
feesAccountHolderName string Optional 50 Name on Fees Account
feesBankRouteNo string Optional 9 Fees Settlement Account Routing Number
feesBankAccountNo string Optional 4 - 17 Fees Settlement Account Number
feesAccountIsPersonal boolean Optional N/A Fees Settlement Account Type
webhook_url string Optional 100 Webhook URL
disableWelcomeEmail boolean Optional N/A Disables the sending of the Welcome Email
timeZoneID int Optional Whole numbers only Time Zone ID from list below

Response

NameTypeDescription
message string Response Message
status string Indicates success or failure
validationErrors object Displays list of errors, if any
   -errorDescription string Description of the error
   -fieldName string Name of erroneous field
guid string New merchant identifier

Add Owner

POST https://enroll.securepds.com/enroll.svc/json/AddOwner

            
{
   "merchantID": "string",
   "login": "string",
   "password": "string",   
   "guid": "string",   
   "firstName": "string",   
   "lastName": "string",   
   "title": "string",   
   "addressLine1": "string",   
   "addressLine2": "string",   
   "city": "string",   
   "state": "string",   
   "postalCode": "string",   
   "phone": "string",   
   "dob": "string",   
   "last4SSN": "string",   
   "ownershipPercent": int 
}
                
            

The above command returns the following JSON structure:

            
{
   "message": "string",
   "status": "string",
   "validationErrors":
         [ 
           { 
      	     "errorDescription": "string",
      	     "fieldName": "string"
           }
      ]
}
                
            

Add an owner to an eligible merchant. Owners can only be added to merchants in statuses: New Entry, Sales, Merchant Sales, and Awaiting Merchant.

HTTP Request

POST https://enroll.securepds.com/enroll.svc/json/AddOwner

Parameters

NameTypeRequiredLengthDescription
merchantID string Required 50 Your Merchant ID
login string Required 50 Username for the Enrollment Site
password string Required 100 Password for the Enrollment Site
guid string Required 100 GUID of the merchant to add an Owner to
firstName string Required 50 Owner First Name
lastName string Required 50 Owner Last Name
title string Required 50 Owner Title. See Owner Titles table below for suggested values.
addressLine1 string Required 50 Owner Address Line 1
addressLine2 string Optional 50 Owner Address Line 2
city string Required 38 Owner City
state string Required 2 Owner State
postalCode string Required 5 Owner Postal Code
phone string Required 10 Owner Phone
dob string Required N/A Owner Date of Birth
last4SSN string Required 4 Owner Last 4 SSN
ownershipPercent int Required 3 Ownership percentage (total of all owners cannot exceed 100%)

Response

NameTypeDescription
message string Response Message
status string Indicates success or failure
validationErrors list Displays list of errors, if any
   -errorDescription object Description of the error
   -fieldName string Name of erroneous field

Sub-Merchant Status

POST https://enroll.securepds.com/enroll.svc/json/GetMerchantStatus

            
{
   "merchantID": "string",
   "login": "string",
   "password": "string",   
   "guid": "string",   
   "filter": "string"   
}
                
            

The above command returns the following JSON structure:

            
{
   "message": "string",
   "status": "string",
   "validationErrors":
         [ 
           { 
      	     "errorDescription": "string",
      	     "fieldName": "string"
           }
      ],
   "merchantList":
      [ 
           { 
      	     "dbaName": "string",
      	     "guid": "string",
      	     "legalName": "string",
      	     "login": "string",
      	     "merchantID": "string",
      	     "merchantStatus": "string",
      	     "password": "string"
             "merchantKey": "string"
           }
      ]
}
                
            

Check the status of a merchant. Send in guid to retrieve single merchant. Omit guid to retrieve information for all submerchants.

HTTP Request

POST https://enroll.securepds.com/enroll.svc/json/GetMerchantStatus

Parameters

NameTypeRequiredLengthDescription
merchantID string Required 50 Your Merchant ID
login string Required 50 Username for the Enrollment Site
password string Required 100 Password for the Enrollment Site
guid string Optional 50 Sub-Merchant Partner ID
filter string Optional 100 Search Filter. Merchants can be filtered by legal name, dba, or status. For example, to see all merchants in the Onboarded status, set the filter parameter as "status:Onboarded". See Filter Options table below for more details.

Response

NameTypeDescription
message string Response Message
status string Indicates success or failure
validationErrors list Displays list of errors, if any
   -errorDescription object Description of the error
   -fieldName string Name of erroneous field
merchantList list Array of Merchants
   -dbaName string Merchant DBA Name
   -guid string Merchant GUID Identifier
   -legalName string Merchant Legal Name
   -login string Merchant Username
   -merchantID string Merchant's ID
   -merchantStatus string Merchant Current Status
   -password string Merchant Password
   -merchantKey string Merchant API Key

Category Codes

POST https://enroll.securepds.com/enroll.svc/json/GetCategoryCodes

            
{
   "merchantID": "string",
   "login": "string",
   "password": "string",   
   "includeMCC": true,   
   "includeNAICS": true   
}
                
            

The above command returns the following JSON structure:

            
{
   "status": "string",
   "message": "string",
   "codes":
         [ 
           { 
      	     "type": "string",
      	     "code": "string",
      	     "description": "string",
      	     "allowedOnWorldPay": true,
      	     "allowedOnTSYS": true,
      	     "allowedOnPinless": true
           }
      ]
}
                
            

Retrieve a list of valid NAICS and MCC codes.

HTTP Request

POST https://enroll.securepds.com/enroll.svc/json/GetCategoryCodes

Parameters

NameTypeRequiredLengthDescription
merchantID string Required 50 Your Merchant ID
login string Required 50 Username for the Enrollment Site
password string Required 100 Password for the Enrollment Site
includeMCC string Optional 50 Include Merchant Category Codes
includeNAICS string Optional 50 Include North American Industry Classification System Codes

Response

NameTypeDescription
message string Response Message
status string Indicates success or failure
codes list List of Codes
   -type string Code Type (NAICS or MCC)
   -code string The code
   -description string The code's description
   -allowedOnWorldPay bool Whether or not the code is allowed on WorldPay (Vantiv)
   -allowedOnTSYS bool Whether or not the code is allowed on TSYS
   -allowedOnPinless bool Whether or not the code is allowed on Pinless

References

Filter Options

In order to use the search filter, leave the guid parameter blank and send the filter type and your filter text separated by a colon. The status is represented by its ID. A list of status descriptions can be found in the Merchant Statuses table.

AttributeFilter Text
Legal Name "legal:name"
DBA Name "dba:name"
Status "status:description"

Merchant Statuses

Description
New Entry
Sales
Merchant Sales
Awaiting Merchant
Risk
Decline
Approved
Onboarded
Terminated

Owner Titles

Title
CEO
COO
CFO
CTO
Director
Supervisor
Analyst
Manager
Other
Owner

Time Zones

If the time zone is not supplied or is not a valid value the merchant will be setup with UTC as the default time zone

ValueDescription
1 (UTC) Coordinated Universal Time
2 (UTC-05:00) Eastern Time (US & Canada)
3 (UTC-05:00) Indiana (East)
4 (UTC-06:00) Central Time (US & Canada)
5 (UTC-07:00) Arizona
6 (UTC-07:00) Mountain Time (US & Canada)
7 (UTC-08:00) Pacific Time (US & Canada)
8 (UTC-09:00) Alaska")
9 (UTC-10:00) Hawaii

Usio Response Codes

Usio will return 6000 series response codes for errors that occur within our Enrollment system.

CodeDescription
6000Security Violation
6004Unable to Load Merchant Details
6005Invalid API Search Filter
6089Merchant Data Did Not Pass Validation
6090Error Applying Inherited Data to Submerchant
6091Invalid MCC Code
6092Invalid NAICS Code
6093Error Inserting Merchant into Database
6094Error Updating Merchant Status
6095Invalid Request
6096Owner Data did not pass validation
6097Invalid Status for Adding Owner
6098Adding Owner Would Exceed Maximum Owner Count
6099Adding Owner Would Exceed Maximum Total Owner Percentage
6100Invalid Merchant GUID provided
6101Invalid Pinless MCC Code

Webhooks

If you provided a webhook url during enrollment, any time the merchant status changes, a payload containing update information will be sent to the specified address. Also, if a webhook url is supplied Usio will not send approval and credential emails. Details of the payload are described below:

Information will be POSTed to the webhook URL in the following JSON structure:

                
                    {
                    "dbaName": "string",
                    "guid": "string",
                    "legalName": "string",
                    "login": "string",
                    "merchantID": "string",
                    "merchantStatus": "string",
                    "password": "string"
                    "merchantKey": "string"
                    }
                
            
NameTypeDescription
   dbaName string Merchant DBA Name
   guid string Merchant GUID Identifier
   legalName string Merchant Legal Name
   login string Merchant Username
   merchantID string Merchant's ID
   merchantStatus string Merchant Current Status
   password string Merchant Password
   merchantKey string Merchant API Key

Payments API

Please click here for access to our Payments API.