Onboarding Fields
The following table provides an overview of the mandatory and optional fields that are required for each call to the Account Management API. You can find complete details about each field in the API section. You must complete all the calls before the merchant can be submitted for activation.
Required fields are indicated by region in the CA, EU, and US 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 then requires this field.
- NA = Not Applicable – Field is required, e.g., for some jurisdictions only and is not applicable for this jurisdiction.
Name | Endpoint | Field | CA | EU | US | Notes |
---|---|---|---|---|---|---|
Create Merchant | /merchants | name | M | M | M | |
Create Merchant Account | /merchants/merchant_id/accounts | name | M | M | M | |
processingCurrency | C | C | C | The processingCurrency field is required if you are configured by Paysafe to create multicurrency merchant accounts. It cannot be included if you are not configured to create multicurrency merchant accounts. | ||
currency | M | M | M | If you are configured by Paysafe to create multicurrency accounts, the currency field specifies the settlement currency for the merchant account. If you are not configured by Paysafe to create multicurrency accounts, the currency fields specifies the processing and settlement currency for the merchant account. | ||
region | M | M | M | |||
legalEntity | M | M | M | |||
productCode | M | M | M | Paysafe provides this partner product code. You need a different productCode (and merchant account) for each payment method/currency combination you want to offer – e.g., credit card USD, Direct Debit EFT, etc. | ||
category | O | O | O | Although category is optional when you create the merchant account, you must update the merchant account to add this element at some later point before the merchant account can be activated. | ||
averageTransactionAmount | O | O | O | Although averageTransactionAmount is optional when you create the merchant account, you must update the merchant account to add this element at some later point before the merchant account can be activated. | ||
url | O | O | O | |||
phone | O | O | O | Although phone is optional when you create the merchant account, you must update the merchant account to add this element at some later point before the merchant account can be activated. | ||
O | O | O | ||||
yearlyVolumeRange | O | O | O | Although yearlyVolumeRange is optional when you create the merchant account, you must update the merchant account to add this element at some later point before the merchant account can be activated. | ||
locale | O | O | O | |||
userName | O | O | O | If a userName exists from another merchant account you have already created, you can include it here. | ||
amexMid | O | O | O | This is the merchant's American Express ID. This is your American Express ID (Merchant ID or MID number). Please find your Merchant ID on your AMEX statements. Adding a wrong AMEX id can lead to transactions being denied. | ||
externalAccountId | O | O | O | |||
The following fields are contained within the caAccountDetails, euAccountDetails, and usAccountDetails complex objects. Although this object is optional when you create the merchant account, you must update the merchant account to add this object at some later point before the merchant account can be activated. | ||||||
type | C | C | C | Required if AccountDetails object is provided. | ||
description | O | O | O | |||
isCardPresent | O | O | O | This field is not supported for Direct Debit merchant processing accounts. | ||
hasPreviouslyProcessedCards | O | O | O | This field is not supported for Direct Debit merchant processing accounts. | ||
shipsGoods | O | O | O | |||
deliveryTimeRange | C | C | C | If shipsGoods is true then deliveryTimeRange is mandatory. | ||
refundPolicy | O | O | O | |||
refundPolicyDescription | C | C | C | If refundPolicy is true then refundPolicyDescription is mandatory. | ||
federalTaxNumber | C | NA | C | Required if relevant AccountDetails object is provided. | ||
taxIdentificationNumber | NA | C | NA | Required if relevant AccountDetails object is provided. | ||
registrationNumber | NA | C | NA | Required if relevant AccountDetails object is provided. However, it is optional if type is set to TRUST, SOLEPROP, GOV, or PARTNERSHIP. | ||
additionalPaymentMethods | O | O | O | This field is not supported for Direct Debit merchant processing accounts. | ||
The following 2 fields are in the merchantDescriptor object. Although merchantDescriptor is optional when you create the merchant account, you must update the merchant account to add this object at some later point before the merchant account can be activated. | ||||||
dynamicDescriptor | C | C | C | Required if merchantDescriptor is provided. For credit card processing merchants, an extra prefix might be added, depending on the processing bank. | ||
phone | C | C | C | Required if merchantDescriptor is provided. Not supported for Direct Debit processing merchants. | ||
Create User | /accounts/account_id/users | userName | M | M | M | Use only if there is not already a user associated with the merchant account. |
password | M | M | M | |||
M | M | M | ||||
The following 2 fields are in the recoveryQuestion object. | ||||||
questionId | M | M | M | |||
answer | M | M | M | |||
Create Merchant Account Address | /accounts/account_id/addresses | street | M | M | M | |
street2 | O | O | O | |||
city | M | M | M | |||
state | M | M | M | |||
zip | M | M | M | |||
country | M | M | M | |||
Create Business Owner | /accounts/account_id/businessowners | firstName | M | M | M | Consult these tables to see requirements for adding a business owner to a merchant account. |
lastName | M | M | M | |||
ssn | O | NA | M | If the ssn is provided then it should be 9 digits and numeric. Note: The SSN parameter is not required when the type parameter in the usAccountDetails object is set to NPCORP, CHARITY or GOV. This object is included when you create a merchant account. | ||
phone | M | M | M | |||
jobTitle | M | M | M | |||
nationality | O | M | O | |||
dateOfBirth | M | M | M | |||
gender | O | M | O | |||
middleName | O | O | O | |||
previousLastName | O | O | O | |||
O | O | O | ||||
percentageOwnership | C | C | C | If you have Ultimate Beneficial Owners then the percentage ownership of each one must be provided here. | ||
isApplicant | M | M | M | You can only designate one business owner as the applicant. All US/CAN/EU partners must make it mandatory for their merchants to identify one of the business owners as the applicant. | ||
isControlProng | O | NA | M | All US partners must make it mandatory for their merchants to identify one of the business owners as the Control Prong. | ||
Create Business Owner Current Address | /businessowners/business_owner_id/currentaddresses | street | M | M | M | |
street2 | O | O | O | |||
city | M | M | M | |||
state | M | M | M | |||
zip | M | M | M | |||
country | M | M | M | |||
yearsAtAddress | M | M | O | |||
Create Business Owner Previous Address | /businessowners/business_owner_id/previousaddresses | street | M | M | O | Previous Address is required if the Business Owner is Canadian or European and has lived at their Current Address for fewer than 3 years. |
street2 | O | O | O | |||
city | M | M | M | |||
state | M | M | M | |||
zip | M | M | M | |||
country | M | M | M | |||
yearsAtAddress | M | M | O | |||
Create ACH Bank Account | accounts/account_id/bankaccounts | routingNumber | NA | NA | M | |
accountNumber | NA | NA | M | |||
Create EFT Bank Account | accounts/account_id/bankaccounts | transitNumber | M | NA | NA | |
institutionId | M | NA | NA | |||
accountNumber | M | NA | NA | |||
Create BACS Bank Account | accounts/account_id/bankaccounts | beneficiaryBankCountry | NA | M | NA | |
beneficiaryAccountName | NA | M | NA | |||
accountNumber | NA | M | NA | |||
sortCode | NA | M | NA | |||
Create SEPA Bank Account | accounts/account_id/bankaccounts | beneficiaryBankCountry | NA | M | NA | |
beneficiaryAccountName | NA | M | NA | |||
swiftNumber | NA | M | NA | |||
ibanNumber | NA | M | NA | |||
Create Wire Bank Account | accounts/account_id/bankaccounts | accountNumber | NA | M | NA | |
routingNumber | NA | O | NA | |||
sortCode | NA | O | NA | |||
swiftNumber | NA | M | NA | |||
ibanNumber | NA | C | NA | If beneficiaryBankCountry is on list of countries supported for SEPA then ibanNumber is mandatory. | ||
beneficiaryCountry | NA | M | NA | |||
beneficiaryAccountName | NA | M | NA | |||
beneficiaryAddress | NA | M | NA | |||
beneficiaryCity | NA | M | NA | |||
beneficiaryRegion | NA | M | NA | |||
beneficiaryPostCode | NA | M | NA | |||
beneficiaryBankCountry | NA | M | NA | |||
beneficiaryBankName | NA | M | NA | |||
beneficiaryBankAddress | NA | M | NA | |||
beneficiaryBankCity | NA | M | NA | |||
beneficiaryBankRegion | NA | M | NA | |||
beneficiaryBankPostCode | NA | M | NA | |||
Look Up Terms and Conditions | /accounts/account_id/ termsandconditions?version=termsandconditions_version | No fields required | ||||
Accept Terms and Conditions | /accounts/account_id/termsandconditions | version | M | M | M | |
Activate Merchant Account | /accounts/account_id/activation | No fields required |