Merchant Onboarding Schema

This schema defines the JSON objects used when creating a merchant onboarding application via POST /merchant-onboarding/application.

InitiateOnboardingRequest

Top-level object submitted to the API.

Field	Type	Required	Description
merchantData	MerchantOnboardingRequest	Yes	Complete merchant application details.
signer	Signer	Yes	The person who will receive and sign the onboarding application.
returnUrl	string (uri)	No	Redirect URL after signing is complete.

---

Signer

Information about the individual who signs the application.

Field	Type	Required	Description
name	string	Yes	Full name of the signer.
email	string	Yes	Email address of the signer.
position	string	Yes	Role or title of the signer.

---

MerchantOnboardingRequest

Represents the merchant’s identity, registration, tax details, addresses, contacts, stakeholders, banking, and fee configuration.

Business Identity & Registration

Field	Type	Required	Notes
merchantName	string	Yes	Public-facing business name.
registeredName	string (2–80 chars)	Yes	Legal registered name.
legalEntityType	enum LegalEntityType	Yes	Corporation, LLC, Partnership, etc.
otherLegalEntity	string	Conditional	Required if legalEntityType = other.
proofOfBusinessType	enum ProofOfBusinessType	Yes	Business license, articles of incorporation, etc.
registrationDate	string (date-time)	Yes	Date of business registration.
naicsCode	string	Yes	Industry classification code.
merchantCategoryCode	string	Yes	Merchant Category Code (MCC).
additionalMerchantCategoryCode	string	No	Optional additional MCC.
businessDescription	string (≤120 chars)	Yes	Short description of the merchant’s services.
isSeasonal	boolean	No	If business operates seasonally.
operationalMonths	array<Month>	No	Months of operation if seasonal.

Tax Identification

Field	Type	Required
federalTaxIdType	enum TaxIdType	Yes
federalTaxId	string (9 digits)	Yes

---

Addresses

Field	Type	Required	Notes
registeredLegalAddress	MailingAddress	Yes	Legal registered address.
proofOfLegalAddressType	enum ProofOfAddressType	Yes	Utility bill, bank statement, or other.
sameAsRegisteredAddress	boolean	No	If business mailing address = legal address.
businessMailingAddress	MailingAddress	Conditional	Required if not same-as-registered.
proofOfBusinessMailingAddressType	enum ProofOfAddressType	Conditional	Required if mailing address provided.

MailingAddress

Field	Type	Required
address1	string	Yes
address2	string	No
city	string	Yes
region	string	Yes
country	string	Yes
postalCode	string	Yes

---

Contacts & Stakeholders

Field	Type	Required	Notes
mainPointOfContact	ShortOwnerInfo	Yes	Primary contact for the merchant.
stakeholders	OwnerInfoRequest[] (1–5)	Yes	Owners/officers required for KYB.

ShortOwnerInfo

Field	Type	Required
firstName	string	Yes
lastName	string	Yes
email	string	Yes
phoneNumber	string	Yes

OwnerInfoRequest

Detailed information about each owner/officer.

Field	Type	Required	Notes
firstName, lastName	string	Yes	Identity.
dateOfBirth	string (date-time)	Yes	Owner’s date of birth.
citizenship	string	Yes	Country of citizenship.
ownershipPercentage	int (0–100)	Yes	Ownership stake.
idType	enum IdType	Yes	Driver license, passport, national ID.
idNumber	string	Yes	Government-issued ID number.
countryOfIssuance	string	Yes	ID issuing country.
taxIdType	enum TaxIdType	Yes	EIN, SSN, ITIN.
taxIdNumber	string (9 digits)	Yes	Tax identifier.
proofOfIdentityType	enum IdType	Yes	Type of identity proof provided.
proofOfIdentityDocument	string	No	Reference to uploaded document.
proofOfAddressType	enum ProofOfAddressType	Yes	Type of address proof.
proofOfAddressDocument	string	No	Reference to uploaded document.
address	MailingAddress	Yes	Residential address.
email	string	Yes	Contact email.
phoneNumber	string	Yes	Contact phone number.
suffix, middleName	string	No	Optional.

---

Banking (Settlement)

Bank account information for settlement.

Field	Type	Required	Notes
bankName	string	Yes	Name of financial institution.
routingNumber	string (9 digits)	Yes	ACH routing number.
accountNumber	string (4–17 digits)	Yes	Bank account number.
accountType	enum BankAccountsType	Yes	Checking or savings.
bankAddress	MailingAddress	Yes	Address of the bank branch.
wireRouting	string	No	Wire routing number.
bankBranchName	string	No	Branch name (if required).
proofOfBankAccountType	enum ProofOfBankAccountType	Yes	Colorized void check, bank letter, etc.

---

Fee Configuration

Per-rail configuration for settlement and returns. Values are provided in currency base units or percentage factors.

Field	Type	Required	Description
discountRate	number	Yes	Percentage discount rate applied to transactions.
perTransactionFee	number	Yes	Fixed per-transaction fee.
monthlyFee	number	No	Monthly recurring fee.
chargebackFee	number	No	Fee applied per chargeback.
refundFee	number	No	Fee applied per refund.