Required Merchant Onboarding API Fields
Below are the required Merchant onboarding fields when submitting via the Payrix API. Additionally, we’ve included a brief description for both required and optional fields to give you an idea of what data should be submitted for each field.
Examples of an Onboarding API payload: Merchant Boarding via API
In the table below, you can see the specific field syntax for each field in parenthesis.
Â
Business Information:
In the table below you will find the required & optional API fields when sending a POST request to the /entities & /merchants endpoints during the onboarding process.
Field Name | Required | Description |
---|---|---|
Legal Business Name (name) |
| Enter the Merchant’s full legal business name (as registered with the State and/or IRS). Note, This field must be between 1 and 100 characters long. |
Statement Descriptor (dba) |
| Defines how the merchant's business name will appear on the customer credit card statements. If no descriptor is set then this field will display the Legal Business Name
|
Tax ID Number (ein) |
| The 9-digit business identification code as issues by the IRS. Note, This field must be 9 characters long. If the business is a sole proprietorship - and no EIN was issued - enter the primary owner’s Social Security Number (SSN). |
Type (type) |
| Accepted values include: |
Public (public) |
| Indicates whether a business is publicly or privately held. 0 = Private
1 = Public
|
Custom Description (custom) | Â | Use this field to enter custom text - e.g. enter your platform ID for this Merchant for internal tracking or record keeping. Note, This field must be between 1 and 100 characters long. |
Website (website) |
| Enter the Merchant’s business website where sales are run. |
Business Email (email) |
| The Merchant’s business email address. Note, This field must be between 1 and 100 characters long. |
Business Address (address1, address2, city, state, zip) |
| The Merchant's street address where their business is conducted. PO Boxes, public shared office spaces, & forwarding services address are not accepted. Note, This field must be between 1 and 100 characters long. |
Business Phone (phone) |
| Enter the Merchant’s 10-digit business phone number. Do not include any spaces or dashes. Note, This field must be between 5 and 15 characters long. |
Customer Service Phone (customerPhone) |  | The phone number that will show on the customer’s statement. If no Customer Service Phoner is provided the Business Phone number on file will be displayed. Note, This field must be between 5 and 15 characters long. |
Fax (fax) | Â | The business 10-digit fax number. Do not include any spaces or dashes. Note, This field must be between 5 and 15 characters long. |
MCC (mcc) |
| Enter the relevant 4-digit Merchant Category Code (MCC). Note, This field must be 4 characters long. |
Boarding Status (status) |
| Set the Merchant’s boarding status. If the Merchant is ready to be submitted, set this status to 1 (ready). If you would like to save this account for future boarding but it is currently incomplete, set the boarding status to 5 (incomplete). |
Terms + Conditions Version |
| Â |
Terms + Conditions Acceptance Date |
|
|
Merchant IP Address |
| 10.2.30.168 |
Payment Parameters Annual Sales + Average Ticket |
|
|
Primary Owner’s Information:
In the table below you will find the required & optional API fields when sending a POST request to the /members endpoint during the onboarding process.
Field Name | Required | Description |
---|---|---|
First Name (first) |
| The primary owner’s full legal first name (as appears on their birth certificate or ID). Note, This field must be between 1 and 100 characters long. |
Last Name (last) |
| The primary owner’s full legal last name (as appears on their birth certificate or ID). Note, This field must be between 1 and 100 characters long. |
Birthdate (dob) |
| The primary owner’s date of birth in MMDDYYYY format (with no spaces or dashes). Note, This field must be between 8 and 8 characters long. |
Social Security Number (ssn) |
| The primary owner’s full 9-digit Social Security Number with no spaces or dashes. Note, This field must be between 9 and 9 characters long. |
Business Title (title) |
| Enter the primary owner’s role in the company. Sample values include: CEO, Director, Owner etc. Note, This field must be between 1 and 100 characters long. |
Ownership Percentage (ownership) |
| Enter the numerical percentage stake that the primary owner has in the business (expressed in basis points). |
Drivers License Number (dl) |  | Enter the owner’s drivers license number with no spaces or dashes. Note, This field must be between 0 and 15 characters long. |
Drivers License State (dlstate) |  | If entering the owner’s license number also include the issuing state. Only 2-digit state abbreviations are accepted (e.g. 'CA' for California). Note, This field must be between 2 and 2 characters long. |
Owner’s Email (email) |
| Enter the primary owner’s personal email address. Note, This field must be between 1 and 100 characters long. |
Significant Responsibility (significantResponsibility) |
| Is the primary owner a controlling authority for this business? Accepted values are: 0 - No, does not have significant responsibility 1 - Yes, does have significant responsibility |
Politically Exposed (politicallyExposed) |
| Is the primary owner politically exposed? Accepted values are: 0 - No, not politically exposed 1 - Yes, this is a politically exposed individual |
Owner’s Address (address1, address2, city, state, zip) |
| The owner’s personal home street address. PO Boxe & forwarding services address are not accepted. Please do not use the business address in this field. Note, This field must be between 1 and 100 characters long. |
Owner’s Phone (phone) |
| Submit the primary owner’s personal 10-digit phone number without spaces or dashes. Note, This field must be between 5 and 15 characters long. |
Banking Information:
In the table below you will find the required & optional API fields when sending a POST request to the /accounts endpoint during the onboarding process.
Field Name | Required | Description |
---|---|---|
Account Type (type) |
| Indicate whether this account is for all uses (all), payouts only (credit), or debits only (debit). |
Account Method (method) |
| Indicate what type of bank account this is. Accepted values include: 8 - Personal checking account 9 - Personal savings account 10 - Corporate checking account 11 - Corporate savings account |
Account Name (name) | Â | Add an optional bank account name for your own record keeping purposes. Note, This field must be between 1 and 100 characters long. |
Account Number (number) |
| Enter the bank account number without any spaces or dashes. |
Routing Number (routing) |
| Enter the bank account routing number without any spaces or dashes. Note, This field must be 9 characters long. |
Primary Account (primary) |
| Indicate whether this is the Merchant’s primary bank account. Accepted values are: 0 - No, not primary bank account 1 - Yes, this is the Merchant’s primary bank account |