Skip to main content
Skip table of contents

Merchant Boarding: API - Canada

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

  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.

Merchant Boarding API Request

Click here to see the complete single-call API request to board a new Merchant.

HTTP Request

CODE 
POST /entities HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com

Request Body

CODE 
{
    "type": 2,
    "name": "MERCHANT NAME",
    "address1": "111 MERCHANT ADDRESS",
    "address2": "NULL",
    "city": "Townsville",
    "state": "BC",
    "zip": "9A9999",
    "country": "CAN",
    "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": "CAD",
    "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",
                "sin": 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": "Townsville",
                "state": "BC",
                "zip": "99999",
                "country": "CAN"
            }
        ]
    }
}

Example Response

CODE 
{
  "entity": {
    "accounts": [
      {
        "account": {
          "method": 8,
          "number": "2345",
          "routing": "3924",
          "payment": null
        },
        "id": "p1_act_5a1ef5e55656698eefaf8b6",
        "created": "2017-11-28 01:02:57",
        "modified": "2017-11-28 01:02:57",
        "creator": "p1_log_5a1ef5e55653ed720159d53",
        "modifier": "p1_log_5a1ef5e55653ed720159d53",
        "entity": "p1_ent_5a1ef5e5565631155c95344",
        "token": "ae1abb3aaa18e4c374ca83fa75a7fff6",
        "name": "",
        "description": "",
        "primary": 1,
        "status": 0,
        "currency": "USD",
        "inactive": 0,
        "frozen": 0
      }
    ],
    "id": "p1_ent_5a1ef5e5565631155c95344",
    "created": "2017-11-28 01:02:57",
    "modified": "2017-11-28 01:02:57",
    "creator": "p1_log_5a1ef5e55653ed720159d53",
    "modifier": "p1_log_5a1ef5e55653ed720159d53",
    "login": "p1_log_5a1ef5e55653ed720159d53",
    ....
  },
  "members": [
    {
      "id": "p1_mbr_5a1ef5e5565716c1bef3bf9",
      "created": "2017-11-28 01:02:57",
      "modified": "2017-11-28 01:02:57",
      "creator": "p1_log_5a1ef5e55653ed720159d53",
      "modifier": "p1_log_5a1ef5e55653ed720159d53",
      "merchant": "p1_mer_5a1ef5e55656a739a85da21",
      "title": "CEO",
      "first": "James",
      "middle": null,
      "last": "Smith",
      "ssn": "6789",
      "dob": "1959",
      "dl": "6789",
      "dlstate": "NY",
      "ownership": 8000,
      "email": "james.smith@example.com",
      "fax": null,
      "phone": null,
      "country": "USA",
      "timezone": "est",
      "zip": "10001",
      "state": "NY",
      "city": "New York",
      "address2": "Suite 403",
      "address1": "123 Example St.",
      "primary": 1,
      "inactive": 0,
      "frozen": 0
    }
  ],
  "id": "p1_mer_5a1ef5e55656a739a85da21",
  "created": "2017-11-28 01:02:57",
  "modified": "2017-11-28 01:02:57",
  "creator": "p1_log_5a1ef5e55653ed720159d53",
  "modifier": "p1_log_5a1ef5e55653ed720159d53",
  "ipCreated": "8.8.8.8",
  "ipModified": "8.8.8.8",
  "lastActivity": null,
  "dba": null,
  "new": 0,
  "established": 20101020,
  "annualCCSales": 1000000,
  "amex": null,
  "discover": null,
  "mcc": "8111",
  "status": 1,
  "boarded": null,
  "tcDate": "2017-11-28 01:02:57",
  "inactive": 0,
  "frozen": 0
}

Response Parameter

Type

entities

Array of Objects

The array of all entity information associated with the newly added Merchant.

id

string

The entity ID for the entity that boarded the Merchant.

accounts

Array of Objects

An array of [bank] Account objects added to the entity

id

string

The new merchant [bank] account ID

created

string

The date and time the account was added.

modified

string

The date and time the account was last modified.

creator

string

The Login ID for the user that originally added the bank account.

modifier

string

The Login ID for the user that last modified the bank account.

entity

string

The entity ID for the associated referrer or facilitator.

token

string

The new tokenized account number.

members

Array

Array of Merchant owner/member information.

id

string

The Member ID for the listed Merchant Member.

created

string

The date and time the Member was added.

modified

string

The date and time the Member was last modified.

creator

string

The Login ID for the user that originally added the Member.

modifier

string

The Login ID for the user that last modified the Member.

merchant

Array of Merchant entity information.

id

string

The Merchant ID for the newly created Merchant.

created

string

The date and time the Merchantwas added.

modified

string

The date and time the Merchantwas last modified.

creator

string

The Login ID for the user that originally added the Merchant.

modifier

string

The Login ID for the user that last modified the Merchant.

Each of the sections below contains a breakdown of each section of the request body above with valid values, formatting examples/restrictions, and descriptions below. Review each to know how to send the complete request properly:

Entity Information Parameters

Click here to see the isolated Entity Information request section code snippet.
CODE 
    
    "type": 2,
    "name": "MERCHANT NAME",
    "address1": "111 MERCHANT ADDRESS",
    "address2": "NULL",
    "city": "Townsville",
    "state": "BC",
    "zip": "9A9999",
    "country": "CAN",
    "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": "CAD",
    "accounts": [...]
    "orgEntities": [{...}],
    "merchant": {...}

Parameter

Type

Required

Description

Valid Values

type

integer

Required

The business jurisdiction type as shown with the CRA filing

Valid Values:

  • 0 - Sole Proprietorship

  • 1 - Corporation

  • 2 - Limited Liability Company

  • 3 - Partnership

  • 5 - Non-Profit Organization

  • 6 - Government Organization

  • 7 - C Corporation

  • 8 - S Corporation

name

string

Required

Enter the Merchant’s full legal business name (as registered with the province and/or CRA).

This field must be between 1 and 100 characters long.

dba

string

Optional

Merchant’s “doing business as” name.

If no descriptor is set then this field will display the Legal Business Name

address1

string

Required

The Merchant’s business street address.

PO Boxes & forwarding services address are not accepted.

This field must be between 1 and 100 characters long.

Warning: Please do not use the business address in this field.

address2

string

Optional

Second address line where applicable.

city

string

Required

The Merchant’s business address city.

province

string

Required

The 2-digit province abbreviations

Valid Values:

  • AB - Alberta

  • BC - British Columbia

  • MB - Manitoba

  • NB - New Brunswick

  • NL - Newfoundland and Labrador

  • NS - Nova Scotia

  • NT - Northwest Territories

  • NU - Nunavut (NU)

  • ON - Ontario

  • PE - Prince Edward Island

  • QC - Quebec

  • SK - Saskatchewan

  • YT - Yukon Territory

zip

string

Required

The 5-digit postal code for the Merchant’s business address.

country

string

Required

The 3-digit country code for the Merchant’s business address.

Valid Values:

  • CAN - Canada

phone

string

Required

The Merchant business’s customer service phone number.

fax

string

Optional

The Merchant business’s fax number.

email

string

Required

Enter the Merchant business’s email address.

This field must be between 1 and 100 characters long.

tin

The 9-digit business identification code as issued by the CRA.

If the business is a sole proprietorship - and no Business number was issued - enter the primary owner’s Social Insurance Number (SIN).

This field must be 9 characters long.

website

string

Required

The Merchant’s business website.

The valid URL for the Merchant's website.

custom

string

Optional

Use this field to enter custom text - e.g. enter your platform ID for this Merchant for internal tracking or record keeping.

This field must be between 1 and 100 characters long.

tcVersion

string

Required

The latest terms and conditions version accepted by the Merchant.

Format:

4.21

tcDate

string

Required

The date that the terms and conditions were accepted by the Merchant.

Format:

YYYY-MM-DD HH:MM:SS

Example: 2022-06-17 10:31:33

clientIp

string

Required

The client IP address from which the Entity was created.

Valid values:

  • Any IPv4 or IPv6 address.

tcAttestation

integer

Required

Whether or not the Terms and Conditions were accepted by the Merchant.

Valid Values:

  • 0 - Merchant has not yet agreed to the platform terms and conditions.

  • 1 - Merchant agreed to the platform terms and conditions.

visaDisclosure

integer

Required

Whether or not the Visa disclosure was acknowledged by the Merchant.

Valid Values:

  • 0 - Merchant has note read and accepted the Visa Disclosure.

  • 1 - Merchant has read and accepted the Visa Disclosure.

disclosureIP

string

Required

The IP address the Visa disclosure was hosted.

Can be null if not applicable.

disclosureDate

string

Required

The date that the Visa disclosure was acknowledged by the Merchant.

Format:

YYYY-MM-DD HH:MM:SS

Example: 2022-06-17 10:31:33

ndxDays

string

Required

The Non Delivery Exposure days which the Merchant is in, if applicable.

Can be null if not applicable.

merchantIp

string

Required

The IP address for Merchant’s business online.

Format Example:

11.1.11.111

currency

string

Required

The 3-digit Merchant bank account and payment transaction currency type

Valid Values:

  • CAD - Canadian Dollars

accounts

object

Required

The object containing all new Merchant bank account information.

Continued below.

orgEntities

object

Required

The object containing all groups the new Merchant will be added to.

Continued below.

merchant

object

Required

The object containing all information about the Merchant being boarded and it’s owner(s).

Continued below.

Bank Account Information Parameters

Click here to see the isolated Bank Account Information request section code snippet.
CODE 
"accounts": [
        {
            "primary": 1,
            "account": {
                "method": 8,
                "number": "123456789",
                "routing": "122000247"
            }
        }
    ],

Parameter

Type

Required

Description

Valid Values

primary

integer

Required

Indicate whether this is the Merchant’s primary bank account.

Valid Values:

  • 0 - No, not primary bank account

  • 1 - Yes, this is the Merchant’s primary bank account

accounts

object

Required

The object containing all new Merchant bank account information.

method

integer

Required

The Account Method. Indicate what type of bank account this is.

Valid Values:

  • 8 - Personal checking account

  • 9 - Personal savings account

  • 10 - Corporate checking account

  • 11 - Corporate savings account

name

string

Optional

Add an optional bank account name for your own record-keeping purposes.

This field must be between 1 and 100 characters long.

number

string

Required

Enter the bank account number without any spaces or dashes.

This field must be between 7 and 12 characters.

routing

string

Required

Enter the combined transit and institution numbers without any spaces or dashes.

This field must be exactly 8 characters long.

Formatting Example: 123 (Transit) + 45678 (Institution) = 12345678 (Routing)

Grouping Information Parameters

Click here to see the isolated Merchant Grouping Information request section code snippet.
CODE 
"orgEntities": [
    {
      "org": "p1_org_62ab92e215bc454c70xxxxx"
    }
],

Parameter

Type

Required

Description

Valid Values

orgEntities

object

Required

The object containing all groups the new Merchant will be added to.

org

string

Required

The Group ID the Merchant will be joining.

Any applicable Group ID that begins with “p1_org_”.

Merchant Information Parameters

Click here to see the isolated Merchant Information request section code snippet.
CODE 
"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": [{...}]
}

Parameter

Type

Required

Description

Valid Values

dba

string

Optional

Merchant’s “doing business as” name.

If no descriptor is set then this field will display the Legal Business Name

new

integer

Required

Whether the Merchant is new to credit card processing. By default, merchants are considered to be new.

  • 0 - Not new

  • 1 - New

mcc

string

Required

The Merchant Category Code (MCC) for this Merchant. This code is not required to create a Merchant, but it is required to successfully board a Merchant.

This field must be exactly 4 digits.

status

integer

Required

The boarding status of the Merchant.

  • 0 - Not ready. Occurs when a new Merchant is created. Unable to process payments.

  • 1 - Ready. New Merchant submitted for underwriting approval after submitting a signup form.

  • 2 - Boarded. Merchant has been approved and boarded to the platform. Payment processing now available.

  • 3 - Manual. Set internally by platform underwriting. New Merchant is pending manual verification.

  • 4 - Closed. Set internally by platform underwriting. New Merchant was declined and cannot access the platform.

  • 5 - Incomplete. Set by user boarding the merchant. Can be manually set to "save" an incomplete Merchant boarding request for a later time.

  • 6 - Pending. New Merchant was submitted for boarding, platform access pending review.

annualCCSales

string

Required

The value of the annual credit card sales of this Merchant.

This field is specified as an integer in cents.

Formatting example:

2530 = $25.30

avgTicket

string

Required

The value of the average credit card sales of this Merchant.

Formatting example:

2530 = $25.30

established

string

Required

The date on which the Merchant was established.

The date is specified as an eight digit string in YYYYMMDD format,

Formatting example: 20240120 = January 20, 2024.

merchants.ndxPercentage

string

Required

The ndx (Non Delivery Exposure) percentage to be used for the merchant, if applicable.

Can be null if not applicable.

merchants.ndxDays

string

Required

The ndx (Non Delivery Exposure) days which the Merchant is in, if applicable.

Can be null if not applicable.

disclosureIP

string

Required

The IP address the Visa disclosure was hosted.

Can be null if not applicable.

members

Array of objects

Required

An array of one or more Merchant Owner info objects.

Continued below.

Merchant Owner Information Parameters

Click here to see the isolated Merchant Owner Information request section code snippet.
CODE 
"members": [
  {
      "title": "CEO",
      "first": "NAME",
      "middle": null,
      "last": "NAME",
      "sin": 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": "Townsville",
      "state": "BC",
      "zip": "99999",
      "country": "CAN"
  }
]

Parameter

Type

Required

Description

Valid Values

members

Array of objects

Required

An array of one or more Merchant Owner info objects.

title

string

Required

Enter the primary owner’s role in the company. Sample values include: CEO, Director, Owner etc.

This field must be between 1 and 100 characters long.

first

string

Required

The primary owner’s full legal first name (as appears on their birth certificate or ID).

This field must be between 1 and 100 characters long.

middle

string

Optional

The primary owner’s full legal middle name (as appears on their birth certificate or ID).

This field must be between 1 and 100 characters long.

last

string

Required

The primary owner’s full legal last name (as appears on their birth certificate or ID).

This field must be between 1 and 100 characters long.

sin

string

Required

The primary owner’s full 9-digit Social Insurance Number with no spaces or dashes.

This field must be exactly 9 characters long.

dob

string

Required

The primary owner’s date of birth with no dashes or slashes.

This field must be exactly 8 characters long.

Format: MMDDYYYY

dl

string

Optional

Enter the owner’s drivers license number with no spaces or dashes.

This field must be between 0 and 15 characters long. See the Province Driver's License Number formatting:

  • Alberta (AB) - 999999999

  • British Columbia (BC) - 9999999

  • Manitoba (MB) - AKKKKAKXX9XX9

  • New Brunswick (NB) - 9999999

  • Newfoundland and Labrador (NL) - A999999999

  • Nova Scotia (NS) - AKKKK999999999

  • Northwest Territories (NT) - 999999999

  • Nunavut (NU) - 99999

  • Ontario (ON) - A99999999999999

  • Prince Edward Island (PE) - 99999

  • Quebec (QC) - A999999999999

  • Saskatchewan (SK) - 99999999

  • Yukon Territory (YT) - 999999

dlstate

string

Optional

If entering the owner’s license number also include the issuing province.

Only 2-digit province abbreviations are accepted:

  • AB - Alberta

  • BC - British Columbia

  • MB - Manitoba

  • NB - New Brunswick

  • NL - Newfoundland and Labrador

  • NS - Nova Scotia

  • NT - Northwest Territories

  • NU - Nunavut (NU)

  • ON - Ontario

  • PE - Prince Edward Island

  • QC - Quebec

  • SK - Saskatchewan

  • YT - Yukon Territory

ownership

string

Required

Enter the numerical percentage stake that the primary owner has in the business (expressed in basis points).

Format:

50% = 5000

100% = 10000

  • A sole primary owner should always enter 10000 for 100%

significantResponsibility

integer

Required

Is the primary owner a controlling authority for this business?

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

Valid Values:

  • 0 - No, does not have significant responsibility

  • 1 - Yes, does have significant responsibility

politicallyExposed

integer

Required

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

Valid Values:

  • 0 - Not politically exposed.

  • 1 - Politically exposed.

email

string

Required

Enter the primary owner’s personal email address.

This field must be between 1 and 100 characters long.

fax

string

Optional

Enter the primary owner’s fax number.

phone

string

Required

Submit the primary owner’s personal phone number without spaces or dashes.

This field must be between 10 and 15 characters long.

primary

integer

Required

Whether the Member is the 'primary' contact for the associated Merchant.

Only one Member associated with each Merchant can be the 'primary' Member.

Valid Values:

  • 0 - Not Primary contact.

  • 1 - Primary contact.

address1

string

Required

The owner’s personal home street address.

PO Boxes & forwarding services address are not accepted.

This field must be between 1 and 100 characters long.

Warning: Please do not use the business address in this field.

address2

string

Optional

Second address line where applicable.

city

string

Required

The owner’s personal address city.

province

string

Required

The 2-digit province abbreviations

Valid Values:

  • AB - Alberta

  • BC - British Columbia

  • MB - Manitoba

  • NB - New Brunswick

  • NL - Newfoundland and Labrador

  • NS - Nova Scotia

  • NT - Northwest Territories

  • NU - Nunavut (NU)

  • ON - Ontario

  • PE - Prince Edward Island

  • QC - Quebec

  • SK - Saskatchewan

  • YT - Yukon Territory

zip

string

Required

The 5-digit postal code for the owner’s personal address.

country

string

Required

The 3-digit country code for the owner’s personal address.

Valid Values:

  • CAN - Canada

JavaScript errors detected

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

If this problem persists, please contact our support.

Contact Support Close