Best Practices

Best Practices for eBoarding refer to rules that are applied to boarding applications, so that data input by the user meets minimum requirements and will be in a readable format for downstream systems.

Character Normalization

Wherever Partner API (PAPI) operations have text strings as input fields, be aware that prior to sending data to downstream Elavon systems, the following character conversion rules are applied:

Non-English characters are converted into their closest English counterpart according to the Java Normalizer of Normalizer.normalize(str, Form.NFD).replaceAll(\\p{InCombiningDiacriticalMarks}+, "");

Example: Ú gets converted to U. Additionally, characters Ł and ł are converted to L and l, respectively.

All other characters that are not a letter, number, or whitespace are removed “[^a-zA-Z0-9 ]”.

Any reports or data coming back from Elavon will reflect this character normalization.

Basic Rules

  • If primaryNationality is USA, then usPerson = true; if primaryNationality is not USA, then usPerson = false.

  • For US applications, supplementary documentaryInfo is not needed for principal.

    "documentaryInfo" : {
      "documentary" : false,
      "documentaryVerifier" : "NOT_VERIFIED"

  • For all applications with the exception of SOLE_TRADER accounts, at least one principal must be listed as a responsibleParty.

  • For all ownershipTypes except for SOLE_TRADER, verifications fields in businessInfo section need to be filled out.

    • If documentary = false, then do not send legalStatus.

    • Non-documentary types should never be sent for documentaryType (i.e SECRETARY_OF_STATE_WEBSITE, etc).

    • When documentary = true, legalStatus should be same as documentType.

    • If verification is via on-site inspection, then documentary is false and you would include sitePersonMet in the call. legalStatus is optional in this scenario:

        "verifications" : {
    "LEGAL" : {
      "documentary" : false,
      "sitePersonMet" : "Test Merchant",
      "issueDate" : { },
      "expiryDate" : { }
    }
  }

  • Positions is determined by ownershipPct with exception of SOLE_TRADER accounts. SOLE_TRADER account will always be “SOLE_PROP” : true.

    • If ownershipPct is 24 or less, then:

      "positions" : {
    "AUTHORIZED_SIGNER" : true

    • If ownershipPct is 25 or greater, then:

      "positions" : {
    "BENEFICIAL_OWNER" : true

OwnershipType Rules

Business & Legal Fields

SOLE_TRADER

  • taxID is generally copied from the principal SSN but, can be different.

  • verifications is left empty as it should not be provided for Sole Proprietorships.

  "ownershipType" : "SOLE_TRADER",
        "taxID" : "*********",
        "communicationLanguage" : "en",
        "posLanguage" : "en",
        "associationCodes" : [ ],
        "signDate" : { },
        "pciInfo" : { },
        "verifications" : { }
      },

LIMITED_COMPANY

  • LLCs must also include the taxClassType
"ownershipType" : "LIMITED_COMPANY",
        "taxID" : "*********",
        "taxClassType" : "CORPORATION",

ESTATE and CLUB (Unincorporated Association)

  • Normal rules apply for capturing businessInfo

Beneficial Owner Exemption Status

  • Normal rules apply for capturing businessInfo
  • ownerExemptionType must be captured/sent
    "ownershipType" : "CHARITY",
    "taxID" : "*********",
    "productDescription" : "TEST",
    "mccCode" : "8699D",
    "establishmentYear" : "2022",
    "currentOwnershipYears" : "0",
    "currentOwnershipMonths" : "1",
    "communicationLanguage" : "en",
    "posLanguage" : "en",
    "associationCodes" : [ ],
    "signDate" : { },
    "pciInfo" : { },
    "countryOfOrigin" : "USA",
    "ownerExemptionType" : "NON_PROFIT",
    "countryOfPrimaryOperation" : "USA",

CIP Exemption

  • Normal rules apply for capturing businessInfo
  • exemptionType must be captured/sent
    "ownershipType" : "GOVERNMENT",
    "taxID" : "*********",
    "productDescription" : "TEST",
    "mccCode" : "9399B",
    "establishmentYear" : "2022",
    "currentOwnershipYears" : "0",
    "currentOwnershipMonths" : "1",
    "communicationLanguage" : "en",
    "posLanguage" : "en",
    "associationCodes" : [ ],
    "signDate" : { },
    "pciInfo" : { },
    "countryOfOrigin" : "USA",
    "exemptionType" : "US_STATE_DEPARTMENT",
    "countryOfPrimaryOperation" : "USA",

Principal Fields

SOLE_TRADER

  • titleType should be PROPRIETOR_OR_OWNER when ownershipType is SOLE_TRADER
  • signingPersonalGuarantee : true, should be defaulted for all SOLE_TRADER accounts.
  • responsibleParty line item is not captured or sent for SOLE_TRADER accounts.
"positions" : {
    "SOLE_PROP" : true
    },
    "ownershipPct" : "100",
    "ids" : [ {
      "idType" : "ID_CARD",
      "idNumber" : "*********",
      "expiryDate" : { }
    } ],
    "titleType" : "PROPRIETOR_OR_OWNER",
    "signingPersonalGuarantee" : true,
    "residingCountry" : "USA",
    "primaryNationality" : "USA",
    "documentaryInfo" : {
      "documentary" : false,
      "documentaryVerifier" : "NOT_VERIFIED"
    },
    "alternateAddressInfo" : {
      "documentNeeded" : false
    },
    "usPerson" : true  
    },

LIMITED_COMPANY

  • Normal rules apply for capturing/sending Principal info.

ESTATE and CLUB(Unincorporated Association)

  • ESTATE and CLUB ownershipType are exempt from providing Ids fields. Ids fields are not required to be captured.
  • responsibleParty is defaulted to true.
  • dob is still required
        "dob" : {
          "year" : 1977,
          "month" : "FEB",
          "day" : 20
        },
        "positions" : {
          "AUTHORIZED_SIGNER" : true
        },
        "ownershipPct" : "0",
        "ids" : [ ],
        "titleType" : "DIRECTOR",
        "signingPersonalGuarantee" : false,
        "responsibleParty" : true,
        "residingCountry" : "USA",
        "primaryNationality" : "USA",
        "alternateAddressInfo" : {
          "documentNeeded" : false
        },
        "usPerson" : true

Beneficial Owner Exemption Status

  • ownershipPct should be defaulted to 0. SSN is still required for eSignature (EID Quiz).
        "positions" : {
          "AUTHORIZED_SIGNER" : true
        },
        "ownershipPct" : "0",
        "ids" : [ {
          "idType" : "ID_CARD",
          "idNumber" : "*********",
          "expiryDate" : { }
        } ],
        "titleType" : "DIRECTOR",
        "signingPersonalGuarantee" : false,
        "responsibleParty" : true,
        "residingCountry" : "USA",
        "primaryNationality" : "USA",
        "alternateAddressInfo" : {
          "documentNeeded" : false
        },
        "usPerson" : true

CIP Exemption

  • ownershipPct should be defaulted to 0.
  • responsibleParty is not captured/sent
        "positions" : {
          "AUTHORIZED_SIGNER" : true
        },
        "ownershipPct" : "0",
        "ids" : [ {
          "idType" : "ID_CARD",
          "idNumber" : "*********",
          "expiryDate" : { }
        } ],
        "titleType" : "DIRECTOR",
        "signingPersonalGuarantee" : false,
        "residingCountry" : "USA",
        "primaryNationality" : "USA",
        "alternateAddressInfo" : {
          "documentNeeded" : false
        },
        "usPerson" : true