Gathering Merchant Demographics

Collect and submit business demographic details through the Boarding API. This process ensures that the merchant account includes all required information for verification and underwriting.

The process includes two steps:

1. Create New Merchant Account

Create Merchant

To begin collecting merchant demographic information, use the Create 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.

2. 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 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 Putmethod /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 Banking 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:

{
  "usesFulfillmentHouse": true,
  "offersNegativeOptionBilling": false,
  "fulfillmentHouseAddress": {
    "line1": "1011 Northwest Ave",
    "line2": "Suite 223",
    "line3": "",
    "city": "Kansas City",
    "countryCode": 840,
    "stateCode": "MO",
    "zip": "64105"
  },
  "fulfillmentHousePhone": {
    "areaCode": "816",
    "phoneNumber": "5556789",
    "extension": "105",
    "phoneTypeCodeID": 3
  },
  "vendorName": "Doe Distribution Inc.",
  "dateOfIncorporation": "2018-06-15T00:00:00",
  "useExtraCnpValidation": true,
  "isECommerce": true,
  "mccCode": "5812",
  "cardPresentPercentage": 40,
  "returnRefundPolicy": "Full refunds are available within 60 days.",
  "productsSold": "Organic food and beverages.",
  "previouslyAcceptedPaymentCards": true,
  "previousProcessorId": 12,
  "previouslyTerminatedOrIdentifiedByRiskMonitoring": false,
  "reasonPreviouslyTerminatedOrIdentifiedByRisk": "",
  "currentlyOpenForBusiness": true,
  "annualVolume": 750000,
  "averageTicket": 65.50,
  "highTicket": 850,
  "ownsProduct": true,
  "ordersProduct": true,
  "sellsFirearms": false,
  "cbdSalesTypeID": 2,
  "salesProfileCBD": {
    "annualCBDRevenuePercentage": 20,
    "cbdProductInventoryPercentage": 50,
    "salesProfileCBDCategory": 2,
    "cbdCategoryID": 1
  },
  "sellsFirearmAccessories": false,
  "futureDeliveryTypeID": true,
  "otherDeliveryType": "Standard shipping",
  "otherDeliveryTypeInDays": 7,
  "futureDeliveryPercentage": 60,
  "fireArmsLicense": "",
  "cardBrands": [1, 2, 3, 4],
  "ebtNumber": "1998882",
  "amexMID": "1998882"
}

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:

{
  "siteTypeID": 4,
  "otherSiteTypeDescription": "Retail Storefront",
  "siteSurveyConductedInPerson": true,
  "merchantAcquisitionTypeID": 3,
  "validIDVerified": true,
  "inventoryMatchesProductSold": true,
  "inventoryMatchesProductSoldComments": "Inventory check completed; products match business description.",
  "agreementAccepted": true,
  "selfSignUpApplication": false
}

Beneficial Ownership Agreement

The Ownership Agreement endpoint is used to record 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 POSTmethod /api/demographics/v1/BusinessContacts/{merchantNumber}/beneficialowneragreement to submit the agreement confirmation. Refer to the below sample code for reference:

{
  "allPersonsWithOverTwentyFivePercentOwnershipHaveBeenAdded": true
}

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:

"string"

For detailed request and response field descriptions, refer to the Merchant Demographics API.