Gathering Merchant Demographics

Xplor Pay collects detailed demographic information to create a comprehensive profile for each business. This helps us understand the operational structure, compliance requirements, and financial needs of the applicant.

The process includes two steps:

1. Create New Merchant Account

Create Merchant

A registered applicant must call the ‘Create Merchant’ endpoint to create new merchant accounts within the application. It validates the provided business model with essential fields such as dbaName, hierarchyNodeKey, and userName. This endpoint uses the POST method to submit and store all critical merchant information, ensuring streamlined operations throughout their lifecycle.

POST https - api/demographics/v1/Merchants

{
  "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
  }
}

Once validation is complete, the merchant is created, and the changes are queued for processing. This 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

Business Contact

The ‘Business Contact’ endpoint allows users to establish a primary point of contact for the business and ensures the total ownership adds up to 100%. By using the POST method, this endpoint enables the submission of essential details such as personal information and ownership stakes to the merchant account, ensuring accurate record-keeping of each business contact.

POST https - /api/demographics/v1/BusinessContacts/{merchantNumber}

{
  "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 assigns a physical location to the merchant account, representing the geographic site where the business operates. It uses the POST method to submit location details with specific parameters. This address must be a registered business or retail location.

POST https - /api/demographics/v1/MerchantPhysicalAddresses/{merchantNumber}

{
  "stateCode": "CA",
  "zip": "94103",
  "countryCode": 840,
  "line1": "789 Mission St",
  "line2": "Suite 400",
  "line3": "",
  "city": "San Francisco"
}

Mailing Address

The ‘Mailing Address’ endpoint assigns an address for correspondence and official communications to the merchant account. It uses the POST method to submit address details with specific parameters (similar to Physical Address). A mailing address must be provided even if it matches the physical address.

POST https - /api/demographics/v1/MerchantMailingAddresses/{merchantNumber}

{
  "stateCode": "CA",
  "zip": "94103",
  "countryCode": 840,
  "line1": "789 Mission St",
  "line2": "Suite 400",
  "line3": "",
  "city": "San Francisco"
}

Taxpayer Information

The ‘Taxpayer Information’ endpoint adds essential taxpayer details (necessary for compliance with tax regulations) to the merchant account. It uses the POST method to submit relevant taxpayer data, such as the merchant’s legal name, tax ID, state of incorporation, etc. This information is crucial to ensure proper identification and reporting for the businesses.

POST https - /api/demographics/v2/Taxpayers/{merchantNumber}

{
  "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 adds the banking details (for handling merchant transactions) to the merchant account. It uses the POST method to submit information such as deposits, fees, chargebacks, etc. for the specific merchantNumber (16-digit MID).

POST https - /api/demographics/v1/BankAccounts/{merchantNumber}

{
  "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 documents the business model, revenue streams, and sales expectations for the merchant. It adds essential sales processing information, card brand entitlements, and other merchant-specific details that are crucial for the merchant's payment processing setup. Using the POST method, this endpoint outlines the sales activities and product offerings associated with the specific merchant number.

POST https - /api/demographics/v2/SalesProfiles/{merchantNumber}

{
  "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 records on-site data for physical validation of the business. It submits information about the Sales Rep or Agent’s acknowledgment of completing due diligence during the site survey. Using the POST method, it captures key verification details such as valid identification, inventory checks, and in-person verification.

POST https - /api/demographics/v1/SiteSurveys/{merchantNumber}

{
  "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 ‘Beneficial Ownership Agreement’ endpoint confirms legal compliance by acknowledging the beneficial ownership details of members with 25% or more ownership. Using the POST method, it captures and submits the ownership information, ensuring that the necessary legal requirements are met. This process helps verify the ownership structure of the business and ensures compliance with regulations.

POST

https - /api/demographics/v1/BusinessContacts/{merchantNumber}/benificialowneragreement

{
  "allPersonsWithOverTwentyFivePercentOwnershipHaveBeenAdded": true
}

Upload Document

The ‘Upload Document’ endpoint allows users to upload required documents for a merchant account using the assigned merchantNumber. Using the POST method, it enables the submission of document files along with their document ID and category, ensuring that all necessary paperwork is properly attached to the merchant’s account for processing.

POST /api/demographics/v1/Documents/{merchantNumber}

"string"

For a detailed breakdown of the request and response fields and their descriptions, refer to the reference documentation of Merchant Demographics API.