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
isUSA
, then usPerson = true; ifprimaryNationality
is notUSA
, 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 aresponsibleParty
.For all
ownershipTypes
except forSOLE_TRADER
, verifications fields inbusinessInfo
section need to be filled out.If documentary = false, then do not send
legalStatus
.Non-documentary types should never be sent for
documentaryType
(i.eSECRETARY_OF_STATE_WEBSITE
, etc).When documentary = true,
legalStatus
should be same asdocumentType
.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 ofSOLE_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 bePROPRIETOR_OR_OWNER
whenownershipType
isSOLE_TRADER
signingPersonalGuarantee
: true, should be defaulted for allSOLE_TRADER
accounts.responsibleParty
line item is not captured or sent forSOLE_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