Search Overlay
Searchbox clear search filters ESC
Filter PreferencesClear

No results found

Onboarding Fields

Applications API

The following table contains all fields, validations, and their descriptions.

Required fields are indicated by region columns by using the following key:

  • M = Mandatory
  • O = Optional
  • C = Conditional – Field is required only if, e.g., another optional field is included that requires this field.
  • NA = Not Applicable – Field is required, e.g., for some jurisdictions only, and is not applicable for this jurisdiction.

 

Element Type Constraints Mandatory Type Description
US CA
id UUID Response Resource NA NA Unique application Id returned in the response
type String - Enum

INITIAL_APPLICATION,

ADDITIONAL_LOCATION,

ADDITIONAL_ACCOUNT, 

ADD_SUB_ACCOUNT,

EDIT_SUB_ACCOUNT

 M M

INITIAL_APPLICATION - Use this application type for new Merchant Applications.

ADDITIONAL_LOCATION - Use this application type to request an additional location/dba/website for an existing merchant.

ADDITIONAL_ACCOUNT - Use this application type to request an additional account (currency/payment method) for an existing merchant.

ADD_SUB_ACCOUNT - Use this application type to request subaccounts under an account to split Merchant's payments settlement into different bank accounts.

EDIT_SUB_ACCOUNT - Use this application type to update the bank details of subaccounts. 
name String Length = 1 - 255 O O Application name, Optional field.
merchantRefNum String Length = 1 - 255 M M

This is the client reference number created by the client and submitted as part of the request.

It must be unique for each request from a partner.
onboardingConfigId String   M M Configuration Id shared along with the API credentials by Paysafe.
locale String - Enum

For US: en_US

For CA: en_CA(default), fr_CA

 O O Preferred language/locale for this application. Defaults to English if not provided in the request. 
acceptTermsAndConditions Boolean true/false C C Terms and Conditions acceptance indicator. Mandatory to set it to true to submit the application. 
submit Boolean   M M

true - This indicates that the application is submitted and sent to further processing.
false - This indicates that the application is still in progress and not ready for further processing.

Note: Application is locked, and updates are not allowed post submission.
termsVersion

Array of terms

 

 Max size = 1 C C

Object which contains terms version information. This information is received as part of /termsandconditions API call. 

(M - if submit is true)

(O - if submit is false)
businessLegalEntity Object   M M This object contains details of the Merchant Legal Entity

Bank Account Description

Merchant's bank account details into which their processed funds will be settled. It is a required object and can be provided at one or more of the following three levels, depending on the Merchant's requirements:

Business Legal Entity: If provided at this level, the specified bank account will be associated with all the accounts under the legal entity.

Business Details: If provided at this level, the specified bank account will be associated with all the accounts under the specified business details entity.

Account: If provided at this level, the specified bank details will be associated exclusively with the specific account.

NOTE:

  1. When you provide bank account details at multiple levels, the system will prioritize the most specific level. For example, if you provide bank details at the Business Legal Entity level, the system will override these with details given at the Business Details level, and further override them with bank details specified at the Account level.
  2. Refer to Bank Account Types for Bank Account Types & Bank Account Attributes for Bank Account Attributes.

ACH Bank Account Object for US

For ACH Schema, refer ACH schema.

Element Type Constraints Mandatory Type Description
US CA
id GUID (or UUID) Response Resource NA NA This is the unique ID returned in the response. This ID can be used for future associated requests.
accountNumber String

Min = 1

Max = 20

 M NA This is the bank account number.
routingNumber String Length = 9 M NA For USD accounts, this is the 9-digit routing number of the customer’s bank.
lastDigits String Response Resource NA NA Last 4 digits of account number sent in response.

EFT Bank Account Object for CA

For EFT Schema, refer EFT schema.

Element Type Constraints Mandatory Type Description
US CA
id GUID (or UUID) Response Resource NA NA This is the unique ID returned in the response. This ID can be used for future associated requests.
accountNumber String

Min = 1

Max = 20

 NA M This is the bank account number.
lastDigits String Response Resource NA NA Last 4 digits of account number sent in response
transitNumber String Length = 5 NA M This is the 5-digit transit number of the customer's bank branch.
institutionId String Length = 3 NA M This is the 3-digit institution ID of the customer’s bank branch.

Terms and Conditions Object

Element Type Constraints Mandatory Type Description
US CA
termsAndConditions String As received while retrieving the terms M M Global terms version as per the configuration. 
region String

US and CA are applicable values

 M M Applicable region.
ccAddendum String Applicable only when the respective addendum is configured and service is requested in an application C C ccAddendum version as per the configuration.
googlePayAddendum String Applicable only when the respective addendum is configured and service is requested in an application C C googlePayAddendum version as per the configuration.
ddAchAddendum String Applicable only when the respective addendum is configured and service is requested in an application C C ddAchAddendum version as per the configuration.

ddEftAddendum

 String Applicable only when the respective addendum is configured and service is requested in an application C C ddEftAddendem version as per the configuration.
cardPresentAddendum String Applicable only when the respective addendum is configured and service is requested in an application C C cardPresentAddendum version as per the configuration.
interacAddendum String Applicable only when the respective addendum is configured and service is requested in an application C C interacAddendum version as per the configuration.
 locale Locale - Enum  en_US (US region); en_CA, fr_CA (CA region) O O

The locale in which all applicable terms are downloaded for end user.

Default is en_US for US region, en_CA for CA region.

User Description

Provide the users who need access to the accounts via the merchant portal. A minimum of one user is mandatory in an application and can be provided at one or more of the following three levels:

Business Legal Entity: Providing users at this level grants them access to all accounts associated with the legal entity.
Business Details: Providing users at this level grants them access only to the accounts associated with the specified business details entity.
Account: Providing users at this level grants them access only to the specified account.

For applications, 'Add Location' and 'Add Account', existing users can be granted access by providing their user IDs.

User Object

For User Schema, refer User schema.

Element Type Constraints Mandatory Type Description
US CA
id  UUID Response Resource NA NA This is the unique ID returned in the response. This ID can be used for future associated requests.
email String

email pattern

 M M Email ID of the user.
fullName String Length = 1 - 255 O O Full Name of the user.
loginName String Alphanumeric  M M

Login name of the user.

Username must be all lowercase, start with a letter (alphabet) and be between 2-64 characters; you can include numbers, hyphens, and underscores. 
password String Alphanumeric with at least one upper case letter M M

Login Password

Password must contain at least: 8 characters -->1 uppercase letter, 1 lowercase letter, 1 number.

UserId Description

For 'Add Location' and 'Add Account', existing users can be granted access by providing their user IDs. Send unique UUID numbers corresponding to the users. 

Address Object

For Address Schema, refer Address schema.

Element Type Constraints Mandatory Type Description
US CA
street  String max = 50 M M This is the first line of the address.
street2 String max = 50 O O This is the second line of the address if needed (ex: nearby landmark).
city String max = 40 M M City of the provided address.
state String max = 40 M M

This is the state/province/region of the provided address.

For Canada see Province Codes. For the United States see State Codes. 
country String-Enum Alphanumeric with at least one upper case letter M M This is the 2-digit Alpha code of the Country. See Country Codes
zip String max = 10 M M This is the postal/zip code of the address.

Billing Details Object

Element Type Constraints Mandatory Type Description
US CA
street String max = 50 M M This is the first line of the Billing address of merchant for Equipment Delivery.
street2 String max = 50 O O This is the second line of the billing address if needed (ex: nearby landmark).
city String max = 40 M M City of the provided billing address.
state String max = 40 M M

This is the state/province/region of the provided billing address.

For Canada see Province Codes. For the United States see State Codes.  Other countries have no restrictions
country String-Enum 2 Alpha Code, size = 2 M M This is the 2-digit Alpha code of the Country of the provided billing address. See Country Codes
zip String max = 10 M M This is the postal/zip code of the billing address.
company String   O O  
telephone String   O O  
recipientName String   O O  

Shipping Details Object

Element Type Constraints Mandatory Type Description
US CA
carrier String   O O  
shipMethod String-Enum GROUND, OVERNIGHT M M This is the shipping method of the order. It can be GROUND or OVERNIGHT. 
GROUND - Standard Delivery
OVERNIGHT - Next Day Delivery
street String max = 50 M M This is the first line of the shipping address of Merchant for Equipment Delivery.
street2 String max = 50 O O This is the second line of the shipping address if needed (ex: nearby landmark).
city String max = 40 M M City of the provided shipping address.
state String max = 40 M M

This is the state/province/region of the provided shipping address.

For Canada see Province Codes. For the United States see State Codes.  Other countries have no restrictions.
country String-Enum 2 Alpha Code, size = 2 M M This is the 2-digit Alpha code of the Country of provided shipping Address. See Country Codes
zip String max = 10 M M This is the postal/zip code of the shipping address.
company String   M M  
telephone String   O O  
recipientName String   O O Name of the receiver of equipment delivery.

Phone Number Object

For Phone Number Schema, refer Phone Number schema.

Element Type Constraints Mandatory Type Description
US CA
countryCode String   M M Phone Country code
number Number   M M Phone Number

Date Of Birth Object

For Date of Birth Schema, refer Date of Birth schema.

Element Type Constraints Mandatory Type Description
US CA
day Integer Min=1, Max=31 M M This is the date of the month.
month Integer Min=1, Max=12 M M This is the month of the year.
year Integer Min=1800 M M This is the year

Principal Object

For Principal Schema, refer Principal schema.

Element Type Constraints Mandatory Type Description
US CA
id UUID Response Resource NA NA This is the unique principal ID returned in the response. This ID can be used for future associated requests.
isApplicant Boolean   M M Flag to indicate this person is the primary applicant for this application.
isControlProng Boolean true/false M NA Flag to indicate control prong of the legal entity. It is necessary to identify one of the business representatives as a control prong. A control prong is a single individual with significant responsibility to control, manage, or direct a legal entity customer, including (i) An executive officer or senior manager (e.g., a Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, Managing Member, General Partner, President, Vice President, or Treasurer); or (ii) Any other individual who regularly performs similar functions.
isDirector Boolean   O O Flag to indicate the Directors.
title String Mr, Ms, Mrs, O O Title.
firstName String   M M First Name of the person
lastName String   M M Last Name of the person
middleName String   O O Middle Name of the person
previousLastName String   O O Previous Last Name of the person if any
dateOfBirth Object All principals should be greater than 18 years of Age.  M M Date of Birth of the required Principal/Business Owner. For all the principals, the Age should be greater than 18 years.
SSN String size=9 M NA Social Security Number of the person. Required for US and business category other than NPCORP.
ssnLastFour String Response Resource NA NA Last four digits of SSN number that is returned in the response 
sin String size=9 NA O Social Insurance Number of the person to help better validate your identity for compliance purposes. Must be 9-digit long.
sinLastFour   Response Resource NA NA Last four digits of SIN number that is sent as part of response 
positionInCompany String   M M Position in company
type String-Enum OWNER, DIRECTOR, OWNER_DIRECTOR, TRUSTEE, PARTNER M M Designation of the person (Ex: Owner, Director, Partner, etc.)
percentageShareholding Double   O O Percentage of shareholding of the person in the company
address Object   M M Residential Address of the Principal/Business owner. Address should be provided as per Government ID proof.

 

Contact Object

For Contact Schema, refer Contact schema.

Element Type Constraints Mandatory Type Description
US CA
id GUID (or UUID) Response Resource NA NA This is the unique ID returned in the response. This ID can be used for future associated requests.
type String-Enum SALES, BUSINESS, PRIMARY, CUSTOMER_SERVICE, TECH, FINANCE M M Type of the contact for the person. Exactly one Primary contact is required. For other contact types, it is optional.
  • Primary Contact: This contact will be the main point of contact on all matters related to the Paysafe account.
  • Technical Contact: This contact will receive notifications about events that may affect technical integrations of the account.
  • Customer Service: This contact will receive communications about the account.
  • Finance: This contact will receive financial updates about the account.
title String-enum Mr, Mrs, Ms O O Title of the contact person
firstName String   M M First name of the person
lastName String   M M Last name of the person
middleName String   O O Middle name of the person
phoneNumber Object   M M Phone number of the person.
email String   M M Email of the person.

YearOfFormation Object

For YearOfFormation Schema, refer YearOfFormation schema.

Element Type Constraints Mandatory Type Description
US CA
month Integer Min = 1800, Max <= current year M M Year in which legal entity was formed.
year Integer Min = 1, Max = 12 M M Month in which legal entity was formed.

AnnualProcessingDistribution Object

Element Type Constraints Mandatory Type Description
US CA
us Integer Max = 100 O O Percentage of annual processing distribution in US region
eu Integer Max = 100 O O Percentage of annual processing distribution in EU region
latinAmerica Integer Max = 100 O O Percentage of annual processing distribution in Latin America region
restOfWorld Integer Max = 100 O O Percentage of annual processing distribution in rest of the World other than in US, EU, and Latin America regions.

StatementDescriptor Object

For StatementDescriptor Schema, refer StatementDescriptor schema.

Element Type Constraints Mandatory Type Description
US CA
descriptor String Descriptor length should be between 0-20 M M This is the description of the DBA that appears on the card statement.
phone String Size must be between 0 and 13 M M This is the phone number of the account.

SubAccount Object

Element Type Constraints Mandatory Type Description
US CA
name String Mandatory when application type is ADD_SUB_ACCOUNT C C Mandatory when application type is ADD_SUB_ACCOUNT
achBankAccount Object   M NA Description
eftBankAccount Object   NA M Description

Tier Object

Element Type Constraints Mandatory Type Description
US CA
order Long Response Resource NA NA  
start Long Response Resource NA NA  
end Long Response Resource NA NA  
price String Response Resource NA NA  
currency String Response Resource NA NA  
sellingPrice Long Response Resource NA NA  

CarrierConfigOutputResourceList

Element Type Constraints Mandatory Type Description
US CA
id UUID Response Resource NA NA  
name String Response Resource NA NA  
description String Response Resource NA NA  
carrierType String Response Resource NA NA  
shipMethod String Response Resource NA NA  
shipperAccountNumber String Response Resource NA NA  
status String Response Resource NA NA  
vendor String Response Resource NA NA  
tiers Array of tier Response Resource NA NA  

EquipmentOrderItem Object

Element Type Constraints Mandatory Type Description
US CA
id String   M M EquipmentOrderId retrieved from terminal order details endpoint.
quantity Integer   M M Quantity of terminals required for each type. Total number of terminals should not exceed 20.
name String Response Resource NA NA  
cost String Response Resource NA NA  

EquipmentOrder Object

Element Type Constraints Mandatory Type Description
US CA
cardPresentConfigId String   M M CardpresentConfigId retrieved from products config end point
equipmentOrderItems Array of equipmentOrderItem   M M You can only select a maximum of 20 terminals. Please get in touch with your Sales agent to get a quote for an order of 20+ terminals.
billingDetails Object   M M Billing Details of the Merchant while ordering equipment.
shippingDetails Object   M M If Ship to Partner is set to true, Ship Method is the only mandatory field in shippingDetails Object.
If Ships to Merchant, then Shipping address details and company are mandatory along with Shipping Method.
interacProcessing Boolean   NA O This field is set to true when merchant wants to opt for interact Processing and has to be configured in Onboarding Config.
Interact Processing is for Canada.
emailForWelcomeEmail List of Strings   M M  
interacContactFee String Response Resource NA NA  
interacContactLessFee String Response Resource NA NA  
interacFeeCurrency String Response Resource NA NA  
equipmentCost String Response Resource NA NA  
shippingCost String Response Resource NA NA  
totalCost String Response Resource NA NA  
currency String Response Resource NA NA  
carrierConfigOutputResourceList Object Response Resource NA NA  

Account Object

For Account Schema, refer Account schema.

Element Type Constraints Mandatory Type Description
US CA
id String Response Resource NA NA This is the unique ID returned in the response. This ID can be used for future associated requests.
name String   O O Name of the account holder
type String-Enum MERCHANT, PARTNER, SALES_AGENT O O Type of the person holding the account (Ex: Merchant, Partner or Sales Agent)
paymentType String-Enum CARD, DD M M Type of payment method should be selected
processDebitCards Boolean   NA O Allowing VI and MC will enable to process more card types. Fees for Visa/MC debit cards fall under the same structure as Visa/MC Credit Card fees.
currency String Supported Currency Codes by Region M M Processing currency of the selected region. It is also settlement currency if settlement currency is not given.
settlementCurrency String Supported Currency Codes by Region C C Required only if the settlement currency is not the same as the account currency.
statementDescriptor Object   M M It describes the customer's billing statement. Description of the name on the card and phone number of the account.
terminalType String-Enum MOTO, ECOM O O Optional and default to ECOM.
cardPresentEnabled Boolean Applicable only for CC payment type. O O Flag to order for equipment.
equipmentOrder Object Applicable only for CC payment type. C C Mandatory if Merchant opts for equipment to be ordered. cardPresentEnabled is true.
users Array of user   C C Description
achBankAccount Object   C NA Description
eftBankAccount Object   NA C Description
userIds Array of userId (UUID Number) Only Applicable for ADD_LOCATION and ADD_ACCOUNT application types C C Description
subAccounts Array of Subaccount Only Applicable for ADD_SUB_ACCOUNT and EDIT_SUB_ACCOUNT application types C C These subaccounts enable merchants to allocate and distribute payments across multiple accounts. For more details on Subaccounts please click here.

BusinessDetails Object

For BusinessDetails Schema, refer businessDetails schema.

Element Type Constraints Mandatory Type Description
US CA
id UUID Response Resource NA NA This is the unique ID returned in the response. This ID can be used for future associated requests.
tradeName String   M M Trade name or doing business as (DBA)
tradeAddress Object   O O Trade address of the location/website/DBA.
category String-Enum Category Codes M M Merchant Business Category of the location/DBA. Refer Merchant Category Codes for Category Code List.
mcc String Response Resource - 4-digit numeric code NA NA Merchant Category Code of 4 digit Numeral.
website String   O O Business Primary Website
additionalWebsites Array of String Maximum of 4 websites are allowed O O Business Additional Websites
phoneNumber Object   M M Customer support phone number of the business location/website/DBA.
email String Max = 240, Valid email O O Customer support email of the business location.
users Array of user   C C Description
achBankAccount Object   C NA Description
eftBankAccount Object   NA C Description
userIds Array of userId (UUID Number) Only Applicable for ADD_LOCATION and ADD_ACCOUNT application types C C Description
contacts Array of Contact   M M Contact Details of this location/website/DBA.
accounts Array of Account   M M Processing Account Details for transaction of this BD location.

BusinessLegalEntity Object

For BusinessLegalEntity Schema, refer BusinessLegalEntity schema.

Element Type Constraints Mandatory Type Description
US CA
id UUID Response Resource NA NA This is the unique ID returned in the response. This ID can be used for future associated requests.
type String-Enum CHARITY, CIC, CLUB, CORP, GOV, INDIVIDUAL, LLC, LLP, LTD, NPCORP, OTHER, PARTNERSHP, PLC, SOLEPROP, TRUST M M Type of the Merchant Legal Entity. Refer Business Type Codes for Business Type List for required region.
legalName String Max = 240 M M Registered Legal Name
taxIdentificationNumber String Length = 9 M M Company Tax Identification Number.
Business number/Employer Identification Number (EIN) is known as Tax ID and is used to identify a business entity.
The Social Insurance Number is used as the Business Number in the case of Sole Proprietorship.
registrationNumber String   O O Your Company Registration Number is a unique number specific to your registered company. This number is used to confirm your legal existence as an incorporated entity via local Company Registries
description String Length = 2-255 O O Description of Merchant's Goods and Services.
users Array of user   C C Description
achBankAccount Object   C NA Description
eftBankAccount Object   NA C Description
userIds Array of UserId (UUID Number) Only Applicable for ADD_LOCATION and ADD_ACCOUNT application types C C Description
address Object   M M Registered legal address of the Merchant.
principals Array of Principal   M M The details of all Ultimate Beneficial Owners (UBOs), having 25% or more shareholding, as well as anyone who exercises control over the applicant's business are required.
yearOfFormation Object   M M Year of formation which helps to calculate the age of the legal entity.
businessInfoCurrency String - Enum USD for US and CAD for CA M O Currency in which Business details like Annual transaction processing amount, Annual processing amount are provided.
averageTransactionAmount String   M O The average value of the transactions processed in a year rounded up to the nearest number. Ex – If average amount of transaction is 15.34 CAD, then 16.
annualProcessingAmount String Length = 1 - 13 M O Expected annual transaction processing amount.
annualProcessingDistribution Object Combined percentage value of all regions should be equivalent to 100 O O Annual transaction processing volume distribution across regions in percentages.
averageRefundDays Integer MIN = 0, MAX = 100 M O The average refund days for which refund policy is applicable after the transaction. Supported values are 0-100 days
businessDetails Array of businessDetails   M M This object array contains details of the Merchant's business by location/website/DBA.
On this Page