Skip to main content
Skip table of contents

Merchant Boarding via API

Partners can submit new Merchant accounts directly via the API allowing them to completely control the look and feel of their clients' boarding process.

To Setup Merchant Boarding via API

  1. Send a POST request to the /entities endpoint in the API.

  2. Send the required information to the /merchants /entities /members /accounts endpoints embedded within this single-call API request

  3. In the body of the code, you will be prompted to add various information about your client’s business, the business owner, and add their bank account. (See Below)

You can also visit the Payrix API reference documentation page for additional technical details about the Merchant onboarding fields.


API Boarding Sample Code:

Expand
CODE 
{
    "type": 2,
    "name": "MERCHANT NAME",
    "address1": "111 MERCHANT ADDRESS",
    "address2": "NULL",
    "city": "Hollywood",
    "state": "CA",
    "zip": "99999",
    "country": "USA",
    "phone": "7777777777",
    "fax": null,
    "email": "EMAIL@EMAIL.COM",
    "ein": "454000000",
    "website": "https://www.website.com/",
    "custom": "CUSTOMINFOHERE",
    "tcVersion": "4.21",
    "tcDate": "2022-06-17 10:31:33",
    "clientIp": null,
    "tcAttestation": 1,
    "visaDisclosure": 1,
    "disclosureIP": "null",
    "disclosureDate": 20210716,
    "ndxDays": null,
    "merchantIp": null,
    "currency": "USD",
    "accounts": [
        {
            "primary": 1,
            "account": {
                "method": 8,
                "number": "123456789",
                "routing": "122000247"
            }
        }
    ],
    "orgEntities": [
     {"org": "p1_org_62ab92e215bc454c70xxxxx"}
     ],
    "merchant": {
        "dba": "DBA SAMPLE HERE",
        "new": 0,
        "mcc": "5812",
        "status": "1",
        "annualCCSales": 80046540,
        "avgTicket": 1250,
        "established": "20200101",
        "merchants.ndxPercentage": null,
        "merchants.ndxDays": null,
        "disclosureIP": "64.233.185.102",
        "members": [
            {
                "title": "CEO",
                "first": "NAME",
                "middle": null,
                "last": "NAME",
                "ssn": 123456789,
                "dob": "YYMMDD",
                "dl": null,
                "dlstate": null,
                "ownership": 10000,
                "significantResponsibility": 1,
                "politicallyExposed": 0,
                "email": "EMAIL@EMAIL.COM",
                "fax": null,
                "phone": "7777777777",
                "primary": "1",
                "address1": "1000 Santa Monica Blvd",
                "address2": null,
                "city": "Hollywood",
                "state": "CA",
                "zip": "99999",
                "country": "USA"
            }
        ]
    }
}

Required Business Information Fields

Expand

In the table below you will find the required & optional API fields when sending a POST request to the /merchants & /entities endpoints during the onboarding process.

Field Name

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

  • Must include at least 1 letter

  • Special characters & . , are permitted

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:

  • Sole Proprietor

  • Corporation

  • Limited Liability Company

  • Partnership

  • Non-Profit Organization

  • Government Organization

Public (public)

Indicates whether a business is publicly or privately held.

0 = Private

  • Indicates a privately held business.

  • *Sole proprietorship will automatically have a value of ‘0/Private’

1 = Public

  • Indicates that the business is publicly owned.

  • *Government agencies and NonProfit businesses will automatically have a value of ‘1/Public’

Custom Description (custom)

[not required]

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.

If the Merchant has no website (such as a brick and mortar only business) then https://nowebsite.com should be entered in this field.

Business Email (email)

The Merchant’s business email address.

Note: This field must be between 1 and 100 characters long.

The owner's personal email address should not be used (if different from business email).

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.

address2 is an optional field. The other fields are all required. For state, use the 2-digit state abbreviation (e.g. 'CA' for California).

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)

[not required]

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)

[not required]

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.

Please contact the Payrix Underwriting team for a list of your portfolio’s approved MCCs.

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

202107161111 YYYMMDDHHMM

Merchant IP Address

10.2.30.168

Payment Parameters

Annual Sales + Average Ticket

"AnnualCCSales": 1000000,

"avgTicket": 1250

Required Primary Owner’s Information:

Expand

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

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

For example, if the primary owner is the sole owner enter ‘10000’. 50% ownership would be submitted as ‘5000’.

Drivers License Number (dl)[nr]

[not reqiored

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)

[not required]

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?

This includes, but is not limited to: CEO, CFO, Owner, VP, managing member etc.

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?

This is defined as persons whom through their prominent position or influence, is more susceptible to being involved in bribery or corruption.

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.

address2 is an optional field. The other fields are all required. For state, use the 2-digit state abbreviation (e.g. 'CA' for California).

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.

Required Banking Information

Expand

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

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)

[not required]

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close