Add merchant demographics
Collect and submit business demographic details through the Merchant Demographics. This process ensures that the merchant account includes all required information for verification and underwriting.
The process includes two steps:
Create new merchant account
Create Merchant
To collect merchant demographic information, use the Create New Merchant endpoint to create a new merchant record within the application. It validates and stores critical merchant details such as dbaName, hierarchyNodeKey, and emailAddress.
Use POST method /api/demographics/v1/Merchants to submit and store all critical merchant information, ensuring streamlined operations throughout their lifecycle. Refer to the below sample code for reference:
{
"businessID": 524398752,
"hierarchyNodeKey": "1234567800000001",
"dbaName": "Jane's Sandwiches",
"merchantNumber": "1234567891234567",
"emailAddress": "[email protected]",
"webSite": "https:/www.janessandwiches.com",
"phones": [
{
"phoneTypeCodeID": 1,
"areaCode": "415",
"phoneNumber": "5551234",
"extension": "101"
}
],
"acceptsPaperStatements": true,
"acceptsPaperTaxForms": false,
"companyTypeId": 2,
"isChainMerchant": false,
"seasonalSchedule": {
"january": true,
"february": false,
"march": true,
"april": true,
"may": true,
"june": false,
"july": true,
"august": true,
"september": false,
"october": true,
"november": true,
"december": false
},
"salesInformation": {
"salesInformationID": 1001,
"businessID": 2002,
"assignedUser": 3003,
"referralPartner": "John Doe",
"compensationType": 2
}
}The merchant will be successfully created after validation is completed and changes are queued for processing. The response includes the merchant's details, setting the foundation for adding demographic information by initiating other relevant endpoints in the subdomain.
Add merchant demographics information
When a merchant is initially created, the system pre-generates empty demographic records such as mailing address, physical address, taxpayer information, and sales profiles. These records are updated using the PUT method.
Business Contact
The Business Contact endpoint used to create a primary contact for a specific merchant. It allows you to submit key details such as the contact’s name, address, phone number, email, SSN, ownership percentage, and contact roles.
Use POST method /api/demographics/v1/BusinessContacts/{merchantNumber} to submit business contact information to create a new contact for a merchant. Refer to the below sample code for reference:
{
"phoneNumbers": [
{
"phoneTypeCodeID": 1,
"areaCode": "415",
"phoneNumber": "5555678",
"extension": "102"
}
],
"businessContactId": 1001,
"contact": {
"countryOfCitizenshipCode": 840,
"address": {
"line1": "456 Market St",
"line2": "Suite 300",
"line3": "",
"city": "San Francisco",
"countryCode": 840,
"stateCode": "CA",
"zip": "94103"
},
"ssnLastFour": "6789",
"encryptedSSN": "ENCRYPTED_VALUE",
"ssn": "123-45-6789",
"contactId": 2002,
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1985-07-22T00:00:00.000Z"
},
"ownershipAmount": 50,
"emailAddress": "[email protected]",
"title": "Managing Partner",
"contactTypes": [
{
"businessContactContactTypeID": 3003,
"businessContactID": 1001,
"contactTypeID": 2
}
],
"isCompassUser": true,
"isMerchantHomeUser": true,
"isVirtualTerminalUser": true,
"isAuthorizedToPurchase": true
}Physical Address
The Merchant Physical Address endpoint is used to assign the merchant's official business location. This address represents where the business operates, such as a store, office, or other commercial site.
Use the PUT method /api/demographics/v1/MerchantPhysicalAddresses/{merchantNumber} to update the address details. The physical address must be a valid, registered business or retail location. Refer to the below sample code for reference:
{
"stateCode": "CA",
"zip": "94103",
"countryCode": 840,
"line1": "789 Mission St",
"line2": "Suite 400",
"line3": "",
"city": "San Francisco"
}Mailing Address
The Mailing Address endpoint is used to assign the official mailing address for a merchant account. This address is used for official correspondence and official communications to the merchant account. A mailing address must be provided, even if it is the same as the physical address.
Use the PUT method /api/demographics/v1/MerchantMailingAddresses/{merchantNumber} to update a mailing address for a specific merchant. Refer to the below sample request code for reference:
{
"stateCode": "CA",
"zip": "94103",
"countryCode": 840,
"line1": "789 Mission St",
"line2": "Suite 400",
"line3": "",
"city": "San Francisco"
}Taxpayer Information
The Taxpayer Information endpoint is used to update essential taxpayer details for a specific merchant. This information is crucial for verifying the business’s tax status and ensuring compliance with financial and regulatory requirements.
Use the PUT method /api/demographics/v2/Taxpayers/{merchantNumber} to update taxpayer details. Refer to the below sample code for reference:
{
"legalFirstName": "John",
"legalLastName": "Doe",
"tin": "12-3456789",
"encryptedTIN": "ENCRYPTED_TIN_VALUE",
"tinTypeID": 3,
"businessLegalName": "Doe Enterprises LLC",
"stateIncorporatedCode": "CA"
}Banking Information
The Bank Account Information endpoint is used to add bank account details for a specific merchant. This is essential for enabling deposits, chargebacks, fees, and settlements associated with the merchant’s transactions.
Use the POST method /api/demographics/v1/BankAccounts/{merchantNumber} to create a bank account for a merchant. Refer to the below sample code for reference:
{
"bankAccountID": 1001,
"bankName": "Bank of America",
"nameOnAccount": "Doe Enterprises LLC",
"accountHolderFirstName": "John",
"accountHolderLastName": "Doe",
"bankAccountTypeID": 3,
"bankAccountNameTypeID": 1,
"aba": "091000019",
"accountNumber": "123456789012",
"lastFourAccountNumber": "9012",
"encryptedAccountNumber": "ENCRYPTED_ACCOUNT_VALUE",
"voidedCheckDocumentID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"hasFees": true,
"hasFunds": true,
"hasChargebacks": true,
"isNameSameAsLegalOrDBAName": true,
"currency": "USD",
"purpose": "Settlement",
"lastUpdatedUtc": "2024-10-15T10:18:39.702Z"
}Sales Profile
The Sales Profile endpoint is used to capture essential information about the merchant's business model, products/services, fulfillment operations, and expected transaction behaviors.
Use the PUT method /api/demographics/v2/SalesProfiles/{merchantNumber} to update sales profile details for a merchant. Refer to the below sample code for reference:
Site Survey
The Site Survey endpoint used to update site verification records for a specific merchant. This data is typically collected during a physical visit by and is used to confirm the business’s operational legitimacy.
Use the PUT method /api/demographics/v1/SiteSurveys/{merchantNumber} to update a site survey for a merchant. Refer to the below sample code for reference:
Beneficial Ownership Agreement
The Ownership Agreement endpoint is used to create an attestation that all individuals with 25% or more ownership in the merchant account have been disclosed. It helps to ensure regulatory compliance with ownership disclosure requirements.
Use the POST method /api/demographics/v1/BusinessContacts/{merchantNumber}/beneficialowneragreement to submit the agreement confirmation. Refer to the below sample code for reference:
Upload Document
The Upload Document endpoint is used to upload a document and associate it with a specific merchant account. It supports submission of document metadata such as the file name and document category, along with the actual file content.
Use the POST method /api/demographics/v1/Documents/{merchantNumber} to submit the documents. Refer to the below sample code for reference:
For detailed request and response field descriptions, refer to the Merchant Demographics API.
Last updated
Was this helpful?