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, 10/14/2022 © Usio.

Change Log

Date	Author	Version	Change 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
04/26/2022	Brianna Keck	1.12	Fixed small formatting errors in the JSON structures
08/09/2022	Daniel Jackson	1.13	Added timeZoneID to webhook JSON and to GetMerchantStatus
10/14/2022	Raul Valadez	1.14	Added Click to Agree IFrame callback response

Environment

PRODUCTION https://enroll.usiopay.com

Production

https://enroll.usiopay.com

SOAP/WFC WSDL

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

REST/JSON Endpoints and definitions:

https://enroll.usiopay.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 Name	Description
merchantID	Merchant ID assigned by Usio
login	API Username
password	API Password

Parameter values for Sandbox

Parameter Name	Test Value
merchantID	12706313
login	API12706313
password	2pscavkjwe

Enrollment

Create Sub-Merchant

POST https://enroll.usiopay.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

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.usiopay.com/enroll.svc/JSON/CreateMerchant

Parameters

Name	Type	Required	Length	Description
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 Email 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	Business Start Date
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

Name	Type	Description
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.usiopay.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.usiopay.com/enroll.svc/json/AddOwner

Parameters

Name	Type	Required	Length	Description
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

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

IFrame Integration

Example IFrame

            
<iframe>
    src='https://enroll.usiopay.com/click_to_agree.aspx?id=DD7939C9-E50C-450A-8509-D7259C4E984D&embedded=TRUE'
    frameborder='0'
    onload='scrollTo(0,0)' 
    style='background: rgba(0, 0, 0, 0.5);margin: 0px;padding: 0px;allowtransparency=true;'>
</iframe>

Event Listener Example

            
<script>
    function receiveMessage(event)
    {
        //your business logic goes here
        alert(event.origin); //"https://enroll.usiopay.com"
        alert(event.data);   //"Completed"
    }
    
    window.addEventListener("message", receiveMessage, false);
</script>

When the click to agree page is embedded in an iframe, it will communicate with the containing page using the JavaScript window.postMessage() method to send events containing a pre-defined string. This allows the containing page to react to events as they occur (e.g., by directing to a new page once the submmited form is received). Events include a string that allows the containing page to notify it the click to agree form has been submitted.

Using JavaScript, the containing page can receive the notification and consume the data it contains by listening for the message event on the global window object and reacting to it as needed. The data passed by this click to agree page notification is represented as string in the data string property of the listener method's event argument.

URL

SOURCE https://enroll.usiopay.com/click_to_agree.aspx?id={Your GUID goes here}&embedded=TRUE

Response

The response is represented as string, the response can be read in the data string property of the listener method event argument as showed in the example.

"Completed" : string

Sub-Merchant Status

POST https://enroll.usiopay.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",
             "timeZoneID": int
           }
      ]
}

Check the status of a merchant. Send in GUID to retrieve single merchant. Omit GUID to retrieve information for all sub-merchants.

HTTP Request

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

Parameters

Name	Type	Required	Length	Description
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

Name	Type	Description
message	string	Response Message
status	string	Indicates success or failure
validationErrors	list	Displays list of errors, if any
-errorDescription	string	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
-timeZoneID	int	Merchant Timezone

Category Codes

POST https://enroll.usiopay.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.usiopay.com/enroll.svc/json/GetCategoryCodes

Parameters

Name	Type	Required	Length	Description
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	bool	Optional	50	Include Merchant Category Codes
includeNAICS	bool	Optional	50	Include North American Industry Classification System Codes

Response

Name	Type	Description
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

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.

Attribute	Filter 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.

Value	Description
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.

Code	Description
6000	Security Violation
6004	Unable to Load Merchant Details
6005	Invalid API Search Filter
6089	Merchant Data Did Not Pass Validation
6090	Error Applying Inherited Data to Submerchant
6091	Invalid MCC Code
6092	Invalid NAICS Code
6093	Error Inserting Merchant into Database
6094	Error Updating Merchant Status
6095	Invalid Request
6096	Owner Data did not pass validation
6097	Invalid Status for Adding Owner
6098	Adding Owner Would Exceed Maximum Owner Count
6099	Adding Owner Would Exceed Maximum Total Owner Percentage
6100	Invalid Merchant GUID provided
6101	Invalid 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",
                    "timeZoneID": int
                }

Name	Type	Description
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
timeZoneID	int	Merchant Timezone

Payments API

Please click here for access to our Payments API.

Introduction

Usio - Enrollment API Documentation

Change Log

Environment

Production

SOAP/WFC WSDL

REST/JSON Endpoints and definitions:

Sandbox

SOAP/WFC WSDL

REST/JSON Endpoints and definitions:

Required Parameters in all calls

Parameter values for Sandbox

Enrollment

Create Sub-Merchant

Important Information

HTTP Request

Parameters

Response

Add Owner

HTTP Request

Parameters

Response

IFrame Integration

URL

Response

Sub-Merchant Status

HTTP Request

Parameters

Response

Category Codes

HTTP Request

Parameters

Response

References

Filter Options

Merchant Statuses

Owner Titles

Time Zones

Usio Response Codes

Webhooks

Payments API