PayFac API Reference Guide Vantiv Pay Fac APIV13.0 V2.1

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 254 [warning: Documents this large are best viewed by clicking the View PDF Link!]

PayFac™ API Reference Guide

PayFac™ API Reference Guide

January 2018

API Release: 13.0

Document Version: 2.1

PayFac API Reference Guide Document Version: 2.1

All information whether text or graphics, contained in this manual is confidential and proprietary information of Vantiv, LLC and is

provided to you solely for the purpose of assisting you in using a Vantiv, LLC product. All such information is protected by copyright laws

and international treaties. No part of this manual may be reproduced or transmitted in any form or by any means, electronic, mechanical or

otherwise for any purpose without the express written permission of Vantiv, LLC. The possession, viewing, or use of the information

contained in this manual does not transfer any intellectual property rights or grant a license to use this information or any software

application referred to herein for any purpose other than that for which it was provided. Information in this manual is presented "as is" and

neither Vantiv, LLC or any other party assumes responsibility for typographical errors, technical errors, or other inaccuracies contained in

this document. This manual is subject to change without notice and does not represent a commitment on the part Vantiv, LLC or any other

party. Vantiv, LLC does not warrant that the information contained herein is accurate or complete.

All trademarks are the property of their respective owners and all parties herein have consented to their trademarks appearing in this

manual. Any use by you of the trademarks included herein must have express written permission of the respective owner.

Document Version: 2.1 — API Release: 13.0 iii

CONTENTS

About This Guide

Intended Audience............................................................................................................ix

Revision History................................................................................................................ix

Document Structure........................................................................................................ xiii

Documentation Set ......................................................................................................... xiii

Typographical Conventions ............................................................................................xiv

Contact Information..........................................................................................................xv

Chapter 1 Introduction

Legal Entity Processing .................................................................................................... 3

API Summary.................................................................................................................... 5

Header Information ........................................................................................................... 7

Chapter 2 PayFac API Certification Tests

Testing Legal Entity Transactions................................................................................... 10

Creating Legal Entities.............................................................................................. 10

Creating Canadian Legal Entities.............................................................................. 11

Updating Legal Entities ............................................................................................. 12

Updating Canadian Legal Entities............................................................................. 14

Retrieving Legal Entity Information ........................................................................... 15

Retrieving Canadian Legal Entity Information........................................................... 16

Testing Sub-Merchant Transactions............................................................................... 18

Creating Sub-Merchants ........................................................................................... 18

Creating Canadian Sub-merchants........................................................................... 19

Updating Sub-Merchant information ......................................................................... 21

Updating Canadian Sub-Merchant Information......................................................... 22

Retrieving Sub-Merchant Information ....................................................................... 24

Retrieving Canadian Sub-Merchant Information....................................................... 25

Retrieve Allowed MCC List ....................................................................................... 25

Chapter 3 PayFac API Transaction Examples

Create Legal Entity Agreement....................................................................................... 28

Create Legal Entity Agreement Request Message................................................... 28

Create Legal Entity Agreement Response Message ................................................ 29

Legal Entity Agreement Retrieval Request..................................................................... 30

Legal Entity Agreement Retrieval Response ............................................................ 30

Create Legal Entity ......................................................................................................... 33

Notes About Background Checks ............................................................................. 33

PayFac API Reference Guide Contents

iv Document Version: 2.1 — API Release: 13.0

Notes About Required Fields .................................................................................... 34

Create Legal Entity Request Message...................................................................... 35

Create Legal Entity Response Message................................................................... 36

Update Legal Entity......................................................................................................... 43

Update Legal Entity Request .................................................................................... 44

Update Legal Entity Response.................................................................................. 45

Retrieve Legal Entity....................................................................................................... 49

Retrieve Legal Entity Response................................................................................ 49

Create a Principal ........................................................................................................... 54

Principal Create Request .......................................................................................... 54

Principal Create Response ....................................................................................... 55

Delete a Principal............................................................................................................ 58

Delete a Principal Response..................................................................................... 58

Create Sub-Merchant...................................................................................................... 60

Create Sub-Merchant Request ................................................................................. 60

Create Sub-Merchant Response............................................................................... 64

Update Sub-Merchant..................................................................................................... 67

Update a Sub-Merchant............................................................................................ 68

Update a Sub-Merchant Response........................................................................... 69

Retrieve Sub-Merchant................................................................................................... 70

Retrieve Sub-Merchant Response............................................................................ 70

Retrieve Allowed MCC List ............................................................................................. 74

Retrieve MCC List Response.................................................................................... 74

Status Codes and Error Messages ................................................................................. 76

Error Response Message ......................................................................................... 76

Chapter 4 PayFac API XML Elements

acceptanceDateTime ...................................................................................................... 80

address ........................................................................................................................... 81

addressVerified ............................................................................................................... 82

agreements..................................................................................................................... 83

agreementVersion........................................................................................................... 84

amexAcquired ................................................................................................................. 85

amexMid .........................................................................................................................86

amexSellerId ................................................................................................................... 87

annualCreditCardSalesVolume....................................................................................... 88

approvedMcc .................................................................................................................. 89

approvedMccResponse .................................................................................................. 90

approvedMccs................................................................................................................. 91

backgroundCheckDecisionNotes.................................................................................... 92

backgroundCheckFields ................................................................................................. 93

PayFac API Reference Guide Contents

Document Version: 2.1 — API Release: 13.0 v

backgroundCheckResults ............................................................................................... 94

bankAccountNumber ...................................................................................................... 95

bankRoutingNumber ....................................................................................................... 96

bankruptcyCount............................................................................................................. 97

bankruptcyData............................................................................................................... 98

bankruptcyType .............................................................................................................. 99

business........................................................................................................................100

businessToPrincipalAssociation ................................................................................... 102

city................................................................................................................................. 103

cityVerified ....................................................................................................................104

code .............................................................................................................................. 105

companyName.............................................................................................................. 112

contactPhone................................................................................................................ 113

countryCode.................................................................................................................. 114

createCredentials.......................................................................................................... 115

credentials.....................................................................................................................116

customerServiceNumber .............................................................................................. 117

dateOfBirth.................................................................................................................... 118

decisionDate ................................................................................................................. 119

description.....................................................................................................................120

disable........................................................................................................................... 121

disabled......................................................................................................................... 122

discoverConveyedMid................................................................................................... 123

dobVerified.................................................................................................................... 124

doingBusinessAs .......................................................................................................... 125

driversLicense............................................................................................................... 126

driversLicenseState ...................................................................................................... 127

eCheck..........................................................................................................................128

eCheckBillingDescriptor................................................................................................ 129

eCheckCompanyName................................................................................................. 130

emailAddress ................................................................................................................ 131

error .............................................................................................................................. 132

errorResponse .............................................................................................................. 133

errors............................................................................................................................. 134

feeProfile....................................................................................................................... 135

filingDate ....................................................................................................................... 136

firstName.......................................................................................................................137

fraud.............................................................................................................................. 138

fundingSubmerchantId.................................................................................................. 139

hardCodedBillingDescriptor .......................................................................................... 140

hasAcceptedCreditCards.............................................................................................. 141

PayFac API Reference Guide Contents

vi Document Version: 2.1 — API Release: 13.0

lastName....................................................................................................................... 142

legalEntityAgreement.................................................................................................... 143

legalEntityAgreementCreateRequest............................................................................ 144

legalEntityAgreementCreateResponse......................................................................... 145

legalEntityAgreementRetrievalResponse ..................................................................... 146

legalEntityAgreementType............................................................................................ 147

legalEntityCreateRequest ............................................................................................. 148

legalEntityCreateResponse .......................................................................................... 149

legalEntityId .................................................................................................................. 150

legalEntityName............................................................................................................ 151

legalEntityOwnershipType ............................................................................................ 152

legalEntityPrincipalCreateRequest ............................................................................... 153

legalEntityPrincipalCreateResponse............................................................................. 154

legalEntityPrincipalDeleteResponse ............................................................................. 155

legalEntityPrincipalUpdatable ....................................................................................... 156

legalEntityResponse ..................................................................................................... 157

legalEntityRetrievalResponse ....................................................................................... 158

legalEntityType ............................................................................................................. 159

legalEntityUpdateRequest ............................................................................................ 160

lienResult ......................................................................................................................161

lienType ........................................................................................................................162

manuallyEntered........................................................................................................... 163

maxTransactionAmount ................................................................................................ 164

merchantCategoryCode................................................................................................ 165

merchantIdentString...................................................................................................... 166

merchantName ............................................................................................................. 167

nameAddressPhoneAssociation ................................................................................... 168

nameAddressSsnAssociation ....................................................................................... 169

nameAddressTaxIdAssociation .................................................................................... 170

nameVerified................................................................................................................. 171

originalLegalEntityId...................................................................................................... 172

originalLegalEntityStatus .............................................................................................. 173

originalSubMerchant ..................................................................................................... 174

overallScore.................................................................................................................. 175

password....................................................................................................................... 176

passwordExpirationDate ............................................................................................... 177

paypageCredential........................................................................................................ 178

paypageCredentials...................................................................................................... 179

paypageId ..................................................................................................................... 180

phone............................................................................................................................ 181

phoneVerified................................................................................................................ 182

PayFac API Reference Guide Contents

Document Version: 2.1 — API Release: 13.0 vii

postalCode.................................................................................................................... 183

primaryContact.............................................................................................................. 184

principal......................................................................................................................... 185

principalId...................................................................................................................... 190

pspMerchantId .............................................................................................................. 191

purchaseCurrency......................................................................................................... 192

releasedCount............................................................................................................... 193

response ....................................................................................................................... 194

responseCode............................................................................................................... 195

responseDescription ..................................................................................................... 196

riskIndicator...................................................................................................................197

riskIndicators................................................................................................................. 198

score ............................................................................................................................. 199

settlementCurrency....................................................................................................... 201

ssn ................................................................................................................................ 202

ssnVerified .................................................................................................................... 203

stakePercent................................................................................................................. 204

state .............................................................................................................................. 205

stateVerified.................................................................................................................. 206

stateProvince ................................................................................................................ 207

streetAddress1, streetAddress2.................................................................................... 208

subMerchantCreateRequest ......................................................................................... 209

subMerchantCreateResponse ...................................................................................... 210

subMerchantFunding .................................................................................................... 211

subMerchantId .............................................................................................................. 212

sub_merchant_processing_status ................................................................................ 213

subMerchantRetrievalResponse................................................................................... 214

subMerchantUpdateRequest ........................................................................................ 215

taxAuthority................................................................................................................... 216

taxAuthorityState........................................................................................................... 217

taxId .............................................................................................................................. 218

taxIdVerified.................................................................................................................. 219

tinValidationStatus ........................................................................................................ 220

title ................................................................................................................................ 221

transactionId ................................................................................................................. 222

unreleasedCount........................................................................................................... 223

updateDate ................................................................................................................... 224

url.................................................................................................................................. 225

userFullName................................................................................................................ 226

userIPAddress .............................................................................................................. 227

userName ..................................................................................................................... 228

PayFac API Reference Guide Contents

viii Document Version: 2.1 — API Release: 13.0

userSystemName ......................................................................................................... 229

verificationIndicators ..................................................................................................... 230

verificationResult........................................................................................................... 232

yearsInBusiness............................................................................................................ 235

zip ................................................................................................................................. 236

zip4 ............................................................................................................................... 237

zipVerified .....................................................................................................................238

Document Version: 2.1 ix

ABOUT THIS GUIDE

This manual serves as a reference to the PayFac Merchant Provisioner API. The guide provides

information about the transaction formats used to create, update, and retrieve (information about)

Legal Entities and Sub-Merchants. It also explains how to perform PayFac API certification

testing with us.

Intended Audience

This document is intended for technical personnel creating code to interface with the Vantiv

eCommerce Merchant Provisioner API.

Revision History

This document has been revised as follows:

TABLE 1 Document Revision History

Doc.

Version Description Location(s)

1.0 Initial Release of Document

Note: This guide replaces the PSP On-boarding API Quick

Reference Guide and the PSP On-boarding API Certification

Tests Guide.

N/A

1.1 Updated for schema version 3.0.

Added text to clarify some points raised by merchants and

fixed errors in version 1.0.

Added info about new pspMerchantId element.

All

1.2 Added / to calls in Table 1-1 and added section/flow chart

about Legal Entity processing.

Fixed typos in examples.

Chapter 1

Chapter 3

About This Guide Revision History

xDocument Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

1.3 Book name change - Merchant Provisioner to PayFac.

Added information about behavior when duplicate Create

Legal Entity and Create Sub-merchant transactions are

submitted. Also added information about new elements added

for duplicate behavior.

All

1.4 Added note about error in schema - username vs. userName Chapters 3 & 4

1.5 Updated document to reflect Version 5 of the schema. All

1.6 Changed Flow charts in section 1.1.

Minor corrections in various locations.

Chapter 1

All

1.7 Updated for Schema Version 6.0 Chapters 2, 3

and 4

1.8 Added Note/text to hardCodedBillingDescriptor and

amount element definition to provide additional details.

Also, fixed missing cross-reference for purchaseCurrency

from subMerchantretrievalResponse.

Chapter 4.

1.9 Updated document for schema V7.0 - Removed PCI element

and children; added eCheck element. Chapters 3 & 4

1.10 Updated document for schema V8.0 - Added elements to

designate the Fee Profile for PayFacs that use Sub-merchant

Funding feature.

Chapter 4

1.11 Removed <PCI> section from one updateLegalEntity

example. Chapter 3

1.12 Removed reference to using DELETE method (to disable a

Sub-merchant) from Table 1-1

Corrected definition of primaryContact element and its child

elements.

Chapter 1

Chapter 4

1.13 Updated document to reflect schema V9.0 changes. All

1.14 Updated document to reflect schema V10.0 changes.

Added Canadian PayFac Cert test information.

All

Chapter 2

1.15 Removed all references to the legalEntityPrincipalUpdatable

transaction type. This should have been removed in V1.13.

Removed erroneous steps shown for testing retrieving Legal

Entity Cert tests.

Chapters 1, 2,

3, and 4

Chapter 2

TABLE 1 Document Revision History

Doc.

Version Description Location(s)

Revision History About This Guide

Document Version: 2.1 — API Release: 13.0 xi

PayFac API Reference Guide

1.16 Updated doc for V10.1.

Replaced Update Sub-merchant Response example.

Fixed error in Update Legal Entity Request example.

Fixed error in when taxId element is required.

Re-branded document.

Chapters 3 & 4

Chapter 3

Chapters 3 & 4

All

1.17 Added text to clarify use of taxId and ssn elements. Chapter3 & 4

1.18 Corrected note on use of fundingSubmerchantId element. Chapter 4

1.19 Updated doc for schema V11. Chapters 3 & 4

1.20 Miscellaneous updates and corrections. Chapters 3 & 4

1.21 Added information about 2 new transaction types.

Corrected LE updatable items list.

Corrected an XML tag in the Update Legal Entity Response

example.

Chapters 3 & 4

Chapter 2

Chapter 3

1.22 Removed references to Funds In/Out report

Renamed Instruction-Based Dynamic Payout to Dynamic

Payout and Profile-Based Dynamic Payout to Managed

Payout.

All

1.23 Clarified use/origin of fundingSubmerchantId element.

Corrected errors (missing elements) in

subMerchantRetrievalResponse structure and examples.

Chapter 4

Chapters 3 & 4

1.24 Added Note about the minimum wait time (two minutes)

between creating a Sub-merchant and the ability for that

Sub-merchant to process transactions.

Chapters 3 & 4

1.25 Miscellaneous corrections to text and examples. All

1.26 Added element to support use of AmEx Opt Blue. Chapters 3 & 4

1.27 Corrected structure/example of createLegalEntityRequest Chapter 3

1.28 Added information and elements associated with V12 of the

API. This version allows provisioning of multiple principals for

a Legal Entity.

All

1.29 Fixed an error in the Notes about Required Fields section of

Chapter 3. Chapter 3

1.30 Fixed error in legalEntityRetrievalResponse example. Chapter 3

TABLE 1 Document Revision History

Doc.

Version Description Location(s)

About This Guide Revision History

xii Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

1.31 Fixed error in the structure of <legalEntityResponse>.

Fixed error in the definition of <merchantIdentString>. It was

defined as Type = Long, but should have been Type = String.

Chapter 3

Chapter 4

1.32 Fixed miscellaneous typos in examples and definitions. Chapters 3 & 4

1.33 Fixed Create and Update Legal Entity examples, as well as

Legal Entity Retrieval example. All errors associated with the

yearsInBusiness element.

Chapter 3

1.34 Changed response message for Test #10.

Added Tests #2a and #2b

Added Create Sub-merchant examples for DP and MP.

Changed url element from required to optional.

Update for V12.1, including new elements for MCC 9311.

Chapter 2

Chapter 3

Chapter 4

Chapters 3 & 4

1.35 Added Note to title element - required if using AmEx Opt

Blue. Chapter 4

1.36 Create Sub-merchant examples were missing closing tag for

</submerchantFunding> Chapter 3

1.37 Replace LitleXML with cnpAPI. All

2.0 Update for V13.0 of schema, which changes the namespace,

as well as the Content-Type and Accept information in the

HTTPS headers.

Chapters 1, 3,

and 4

2.1 Added Notes specifying that you must designate the

controlling Principal when creating a Legal Entity, and also

that you must create additional Principals for owners with a

10% or greater interest in the Legal Entity.

Chapters 3 and

TABLE 1 Document Revision History

Doc.

Version Description Location(s)

Document Structure About This Guide

Document Version: 2.1 — API Release: 13.0 xiii

PayFac API Reference Guide

Document Structure

This manual contains the following sections:

Chapter 1, "Introduction"

This chapter provides an overview of PayFac Merchant Provisioner API functionality.

Chapter 2, "PayFac API Certification Tests"

This chapter guides you through testing and certification process required prior to using the

PayFac Merchant Provisioner API in the production environment.

Chapter 3, "PayFac API Transaction Examples"

This chapter provides information concerning the required XML structure, as well as example of

the available PayFac Merchant Provisioner API transaction messages.

Chapter 4, "PayFac API XML Elements"

The chapter provides definitions of each element available in the PayFac Merchant Provisioner

API.

Documentation Set

Our documentation set also include the items listed below, as well as many other InfoSheets and

FAQ documents. Please refer to the appropriate guide for information concerning other product

offerings.

•Vantiv PayFac™ Portal User Guide

•Vantiv cnpAPI Reference Guide

•Vantiv iQ Reporting and Analytics User Guide

•Vantiv PayFac™ Integration Overview (eComm)

•Vantiv PayPal Integration Guide

•Vantiv Chargeback API Reference Guide

•Vantiv Chargeback Process Guide

•Vantiv eProtect™ Integration Guide

•Vantiv Enterprise eProtect™ Integration Guide

•Vantiv cnpAPI Differences Guide

•Vantiv Scheduled Secure Reports Reference Guide

•Vantiv Account Updater Implementation and Operations Guide (Legacy)

About This Guide Typographical Conventions

xiv Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

Typographical Conventions

Table 2 describes the conventions used in this guide.

TABLE 2 Typographical Conventions

Convention Meaning

Vertical ellipsis points in an example mean that information not directly

related to the example has been omitted.

. . . Horizontal ellipsis points in statements or commands mean that parts of

the statement or command not directly related to the example have been

omitted.

< > Angle brackets are used in the following situations:

•user-supplied values (variables)

•XML elements

[ ] Brackets enclose optional clauses from which you can choose one or

more option.

bold text Bold text indicates emphasis.

Italicized text Italic type in text indicates a term defined in the text, the glossary, or in

both locations.

blue text Blue text indicates a hypertext link.

Contact Information About This Guide

Document Version: 2.1 — API Release: 13.0 xv

PayFac API Reference Guide

Contact Information

This section provides contact information for organizations within Vantiv.

Implementation - For technical assistance to resolve issues encountered during the on-boarding

process, including certification testing.

Chargebacks - For business-related issues and questions regarding financial transactions and

documentation associated with chargeback cases, contact the Chargebacks Department.

Technical Support - For technical issues such as file transmission errors, email Technical

Support. A Technical Support Representative will contact you within 15 minutes to resolve the

problem.

Relationship Management/Customer Service - For non-technical issues, including questions

concerning iQ Reporting and Analytics, help with passwords, modifying merchant details, and

changes to user account permissions, contact the Relationship Management/Customer Service

Department. If you are a Payment Facilitator (PayFac), refer to the second table.

Implementation Contact Information

E-mail implementation@vantiv.com

Hours Available Monday – Friday, 8:30 A.M.– 5:30 P.M. EST

Chargebacks Department Contact Information

Telephone 1-844-843-6111 (option 4)

E-mail chargebacks@vantiv.com

Hours Available Monday – Friday, 7:30 A.M.– 5:00 P.M. EST

Technical Support Contact Information

E-mail eCommerceSupport@vantiv.com

Hours Available 24/7 (seven days a week, 24 hours a day)

Relationship Management/Customer Service Contact Information - Merchants

Telephone 1-844-843-6111 (Option 3)

E-mail ecc@vantiv.com

Hours Available Monday – Friday, 8:00 A.M.– 6:00 P.M. EST

About This Guide Contact Information

xvi Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

Technical Publications - For questions or comments about this document, please address your

feedback to the Technical Publications Department. All comments are welcome.

Relationship Management/Customer Service Contact Information - Payment Facilitators

Telephone 1-844-843-6111 (Option 5)

E-mail PayFacEComm@vantiv.com

Hours Available Monday – Friday, 8:00 A.M.– 5:00 P.M. EST

Technical Publications Contact Information

E-mail TechPubs@vantiv.com

Document Version: 2.1 — API Release: 13.0 1

INTRODUCTION

This document provides an overview of the PayFac API. This is an XML based, RESTful API

that allows you to create and update Legal Entities and Sub-merchants, as well as retrieve

information about existing Legal Entities and Sub-merchants in near real-time. Additionally, you

can disable Sub-merchants should the need arise.

As shown in Figure 1-1, before you can begin processing payment transactions for a

Sub-merchant, you must first create the Legal Entity. A Legal Entity describes the parent of one

or more Sub-merchants. After the successful creation of a Legal Entity, you create Sub-merchants

under that Legal Entity.

Introduction

2Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

FIGURE 1-1 Legal Entity and Sub-merchant Creation Flow

PayFac submits Legal entity

Information (via

legalEntityCreateRequest)

Vantiv performs

background and MATCH

checks

Vantiv performs manual

review

PayFac submits Sub-

Merchant information (via

subMerchantCreateRequest)

to create Sub-merchants

under approved Legal

Entities

Vantiv creates Sub-

merchant(s)

PayFac retrieves results of

manual review process after

48 hours (via HTTP GET)

Manual review

Retry

Declined

Approved Approved

PayFac can begin to submit

payment transactions for

Sub-merchant

Declined

The PayFac should re-

submit transactions returned

with a Retry code using

additional information as

required.

In some cases, transaction

returned as Declined can

also be re-submitted with

new information.

Legal Entity Processing Introduction

Document Version: 2.1 — API Release: 13.0 3

PayFac API Reference Guide

1.1 Legal Entity Processing

When you use the PayFac API to create a Legal Entity, add a Principal to a Legal Entity, and/or

create a Sub-merchant, the system performs a series of background checks. The extent and type of

check performed depend upon your needs and contract. There are three levels of service

available: Basic, Premium, and Premium Plus.

As illustrated in Figure 1-2 and Figure 1-3, depending upon your service level, the result of the

background checks, and subsequent analysis if necessary, there are three possible outcomes:

Accept, Decline, or Soft Decline/Retry

FIGURE 1-2 Legal Entity Acceptance Flow - Basic and Premium

Legal Entity on

MATCH or watch

lists?

MANUAL REVIEW

YES

Legal Entity on

Match/Watch

list confirmed?

ACCEPT DECLINE

YES

Write notes for

declining

Introduction Legal Entity Processing

4Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

FIGURE 1-3 Legal Entity Acceptance Flow - Premium Plus

Legal Entity on

MATCH or watch

lists?

Legal Entity

Verified?

YES

MANUAL REVIEW

YES

Legal Entity on

Match/Watch

list confirmed?

Legal Entity

Verified?

YES

RETRY DECLINE

YES

Write notes for

decline

Write notes for

Soft decline

API Summary Introduction

Document Version: 2.1 — API Release: 13.0 5

PayFac API Reference Guide

1.2 API Summary

You use the following methods to create, retrieve, update, or disable Sub-merchants, as well as

list Merchant Category Codes (MCC). The associated data is submitted in various XML

messages, the structure of which is defined in the other sections of this document.

NOTE:When creating a URI for a particular method, replace any Id object with the

value returned in the create response XML message. For example, if you

were updating a Legal Entity and the legalEntityId = 3 (from the

legalEntityCreateResponse message), the update call would be: PUT

/legalentity/3

TABLE 1-1 API Methods Summary (replace bold items with values)

Resource Description

POST /legalentity/legalEntityId/agreement Request to designate the version of the agreement

along with information about the agreeing party. (See

Create Legal Entity Agreement on page 28)

GET /legalentity/legalEntityId/agreement Request to retrieve all agreements associated with a

specified Legal Entity. (See Legal Entity Agreement

Retrieval Request on page 30)

POST /legalentity Request to create a new Legal Entity. (See Create

Legal Entity on page 33)

PUT /legalentity/legalEntityId Request to update data associated with the

designated Legal Entity. (See Update Legal Entity on

page 43)

GET /legalentity/legalEntityId Request for information and/or status of the

designated Legal Entity. Typically this is use to check

status of a Legal Entity in Manual Review. (See

Retrieve Legal Entity on page 49)

POST /legalentity/legalEntityId/principal Request to create a new Principal associated with a

Legal Entity. (See Create a Principal on page 54)

DELETE

/legalentity/legalEntityId/principal/principalId Request to delete a Principal associated with a Legal

Entity. (See Delete a Principal on page 58)

POST /legalentity/legalEntityId/submerchant Request to create a Sub-merchant associated with the

designated Legal Entity. (See Create Sub-Merchant

on page 60)

PUT

/legalentity/legalEntityId/submerchant/subM

erchantId

Request to update data associated with the

designated Sub-merchant. (See Update

Sub-Merchant on page 67)

Introduction API Summary

6Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

GET

/legalentity/legalEntityId/submerchant/subM

erchantId

Request to retrieve information about the designated

Sub-merchant. (See Retrieve Sub-Merchant on page

70)

GET /mcc Returns the list of merchant category codes that are

currently approved for the Payment Service Provider.

(See Retrieve Allowed MCC List on page 74)

TABLE 1-1 API Methods Summary (replace bold items with values)

Resource Description

Header Information Introduction

Document Version: 2.1 — API Release: 13.0 7

PayFac API Reference Guide

1.3 Header Information

To authenticate, you will need a merchant ID (merchant identity), username and password. We

uses an HTTP Basic Authentication scheme in combination with SSL to guarantee the protection

of your authentication information. You must include your username and password in the HTTP

header according to the HTTP Basic Authentication (i.e. base-64 encoding) on every API method

invocation. The tables below contains additional information concerning the header.

Example: HTTP Header Example - Create Sub-merchant

POST /legalentity/1/submerchant

Host: example_only.vantiv.com

Authorization: Basic bWVyY2hhbnQxOnBhc3N3b3Jk=

Content-Type: application/com.vantivcnp.payfac-v13+xml

Accept: application/com.vantivcnp.payfac-v13+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

TABLE 1-2 HTTP Request Header

Authorization Basic (with user name and password)

Content-Type application/com.vantivcnp.payfac-v13+xml

Accept application/com.vantivcnp.payfac-v13+xml

IMPORTANT:The Content-Type and Accept may not be required for all methods. When

included, the version number in Content-Type and Accept should always

reflect the API version you use. For example, if you use API V14, use

application/com.vantivcnp.payfac-v14+xml for Content-Type and Accept.

TABLE 1-3 Header Information

Description Example/Info Comments

Authorization username:password = merchant1:password

Base-64 encoded =

bWVyY2hhbnQxOnBhc3N3b3Jk

Required for authentication

purpose.

Introduction Header Information

8Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

Document Version: 2.1 — API Release: 13.0 9

PAYFAC API CERTIFICATION TESTS

You must complete a number of certification tests prior to submitting transactions to the Merchant

Provisioning system. This testing process allows you to verify that your system not only submits

correctly formatted transaction data, but also correctly parses the data returned to you in the

response messages. To facilitate the certification process, we have established a certification

environment that simulates the production environment.

During certification testing, an Implementation Consultant will guide you through each required

test scenario. For each transaction type, specific data is supplied that you must use in your

transactions. Use of this data allows the validation of your transaction structure/syntax, as well as

the return of a response file containing known data. Please refer to Chapter 4, "PayFac API XML

Elements" for element definitions and XML message structure.

IMPORTANT:The test data supplied does not account for all data fields/xml elements

in a particular request. Where data is not supplied, you should provide

appropriate information. You should never override your own system to

enter supplied data. If you cannot enter the supplied data without

overriding your system, please consult your Implementation Consultant

concerning the test and how to proceed.

PayFac API Certification Tests Testing Legal Entity Transactions

10 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

2.1 Testing Legal Entity Transactions

The following sections provide information used to test the creation and updating of Legal

Entities, as well as the retrieval of information for already existing Legal Entities.

2.1.1 Creating Legal Entities

You must create a Legal entity prior to creating Sub-merchants. Each Legal entity can have one or

more associated Sub-Merchants.

To test the creation of Legal Entities:

1. Verify that your Create Legal Entity template is coded correctly (see Create Legal Entity on

page 33).

2. Submit legalEntityCreateRequest transaction using the data provided for Test # 1, 2,

and 3. You must provide the data for all other required elements (see Notes About Required

Fields on page 34). The response of the simulator for these test cases is tied to the contents of

the streetAddress1 element.

3. Verify that your system parses the response file correctly and that the value are those shown

in the Key Response Elements of the table.

4. Wait a minimum of two hours after submitting Test #2 and submit a Legal Entity Retrieval

(see Retrieve Legal Entity on page 49), using the leagalEntityId returned in Test #2.

5. Follow the instructions returned in the Retrieval response and submit an Update Legal Entity

request. Verify the approval of the Legal Entity.

NOTE:For Canadian Legal Entity tests see section Creating Canadian Legal

Entities on page 11.

TABLE 2-1 Create Legal Entity Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

1 <legalEntityType>

INDIVIDUAL_SOLE_

PROPRIETORSHIP

900 Chelmsford St

Note: For this

legalEntityType you

must include the ssn

element.

HTTP Status Code:

XML Response:

201

Approved

Testing Legal Entity Transactions PayFac API Certification Tests

Document Version: 2.1 — API Release: 13.0 11

PayFac API Reference Guide

2.1.2 Creating Canadian Legal Entities

To test the creation of Legal Entities for Canada:

6. Verify that your Create Legal Entity template is coded correctly (see Create Legal Entity on

page 33).

7. Submit legalEntityCreateRequest transaction using the data provided for Test # C.1.1,

C.1.2, and C.1.3. You must provide the data for all other required elements (see Notes About

Required Fields on page 34). The response of the simulator for these test cases is tied to the

contents of the streetAddress1 element.

8. Verify that your system parses the response file correctly and that the value are those shown

in the Key Response Elements of the table.

2 <legalEntityType>

INDIVIDUAL_SOLE_

PROPRIETORSHIP

912 Chelmsford St

Note: For this

legalEntityType you

must include the ssn

element.

HTTP Status Code:

XML Response:

201

Manual Review

2a legalEntityId Value from in Test #2. <backgroundCheckDecisio

nNotes> Notes for

resubmission.

2b legalEntityId Value from in Test #2. HTTP Status Code:

XML Response:

201

Approved

3 <legalEntityType>

LIMITED_LIABILITY_

COMPANY

914 Chelmsford St

Note: For this

legalEntityType you

must include the

taxId element.

HTTP Status Code:

XML Response:

201

Approved

TABLE 2-1 Create Legal Entity Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

PayFac API Certification Tests Testing Legal Entity Transactions

12 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

2.1.3 Updating Legal Entities

You can update the several items associated with a Legal Entity. To update information associated

with a Legal Entity, you use a PUT method with the appropriate legalEntityId along with a

legalEntityUpdateRequest message containing the updated information.

You can update the following items:

TABLE 2-2 Create Canadian Legal Entity Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

C.1.1 <legalEntityType>

CORPORATION

Canada Cert Test

Legal Entity A

900 Chelmsford St

HTTP Status Code:

XML Response:

201

Approved

C.1.2 <legalEntityType>

INDIVIDUAL_SOLE_

PROPRIETORSHIP

900 Chelmsford St

Note: For this

legalEntityType you

must include the ssn

element.

HTTP Status Code:

XML Response:

201

Approved

C.1.3 <legalEntityType>

GENERAL_PARTNE

RSHIP

912 Chelmsford St

Note: For this

legalEntityType you

must include the

taxId element.

HTTP Status Code:

XML Response:

201

Manual Review

NOTE:For Canadian Legal Entity updating tests see section Updating Canadian

Legal Entities on page 14.

Testing Legal Entity Transactions PayFac API Certification Tests

Document Version: 2.1 — API Release: 13.0 13

PayFac API Reference Guide

To test the legalEntityUpdateRequest transaction:

1. Verify that your Update Legal Entity template is coded correctly (see Update Legal Entity on

page 43).

2. Submit legalEntityUpdateRequest transaction using the data provided for Test # 4 and

5. You must provide the data for all other required elements.

3. Verify that your system parses the response file correctly and that the value are those shown

in the Key Response Elements of the table.

•streetAddress1 (entity and/or principal) •firstName (principal)

•streetAddress2 (entity and/or principal) •lastName (principal)

•city (entity and/or principal) •ssn (principal)

•stateProvince (entity and/or principal) •dateOfBirth (principal)

•postalCode (entity and/or principal) •driversLicense (principal)

•doingBusinessAs •driversLicenseState (principal)

•annualCreditCardSalesVolume •legalEntityName

•hasAcceptedCreditCards •legalEntityType

•contactPhone (entity and/or principal) •taxId

•title (principal) •yearsInBusiness

•emailAddress (principal)

TABLE 2-3 Update Legal Entity Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

4 legalEntityId Use the value

returned in the

response message

from Test #1.

HTTP Status Code: 200

5 legalEntityId Submit any invalid

value HTTP Status Code:

XML Response:

<error>

400

Error in request:

Could not find

requested object.

PayFac API Certification Tests Testing Legal Entity Transactions

14 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

2.1.4 Updating Canadian Legal Entities

To test the legalEntityUpdateRequest transaction:

1. Verify that your Update Legal Entity template is coded correctly (see Update Legal Entity on

page 43).

2. Submit legalEntityUpdateRequest transaction using the data provided in Table 2-4. You

must provide the data for all other required elements.

3. Verify that your system parses the response file correctly and that the value are those shown

in the Key Response Elements of the table.

TABLE 2-4 Update Canadian Legal Entity Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

C2.2.1 legalEntityId

Use the value

returned in the

response message

from Test #C.1.1.

Canada A

HTTP Status Code: 200

C2.2.2 legalEntityId

Use the value

returned in the

response message

from Test #C.1.1.

HTTP Status Code:

XML Response:

<error>

400

Legal Entity Principal

stateProvince: “XX”

is not valid for Legal

Entity Principal

country.

C2.2.3 legalEntityId

Use the value

returned in the

response message

from Test #C.1.1.

01730

HTTP Status Code:

XML Response:

<error>

400

Postal Code is not

valid for country

“CAN”.

C2.2.4 legalEntityId

Use the value

returned in the

response message

from Test #C.1.3.

01730

HTTP Status Code:

XML Response:

<error>

400

Postal Code “01730”

is not valid for

country “CAN”.

Testing Legal Entity Transactions PayFac API Certification Tests

Document Version: 2.1 — API Release: 13.0 15

PayFac API Reference Guide

2.1.5 Retrieving Legal Entity Information

If you need to retrieve the on-boarding information related to a Legal Entity for verification

purposes or to check the status of cases requiring manual intervention, you must perform a GET

operation specifying the legalEntityId.

To test the retrieval of Legal Entity information use the information supplied in Table 2-5.

Verify that your system parses the response file correctly and that the value are those shown in the

Key Response Elements of the table.

C2.2.5 legalEntityId

Use the value

returned in the

response message

from Test #C.1.1.

Canada Cert Test C -

Update

HTTP Status Code:

XML Response:

<error>

200

Due to its current

status, requested

Legal Entity is not

updatable

C2.2.6 legalEntityId

<backgroundCheckF

ields>

<taxId>

Use the value

returned in the

response message

from Test #C.1.1.

123456789

HTTP Status Code:

XML Response:

<error>

400

Background check

fields cannot be

updated after

background check.

NOTE:For Canadian Legal Entity updating tests see section Retrieving Canadian

Legal Entity Information on page 16.

TABLE 2-4 Update Canadian Legal Entity Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

PayFac API Certification Tests Testing Legal Entity Transactions

16 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

2.1.6 Retrieving Canadian Legal Entity Information

To test the retrieval of Canadian Legal Entity information use the information supplied in

Table 2-6.

Verify that your system parses the response file correctly and that the values returned are those

shown in the Key Response Elements of the table.

TABLE 2-5 Retrieve Legal Entity Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

6 legalEntityId Use the value

returned in the

response message

from Test #2.

HTTP Status Code:

XML Response:

200

Manual Review

Note: Response

message will include

other Legal Entity

information

submitted with Test

#2.

7 legalEntityId Submit any invalid

value HTTP Status Code:

XML Response:

<error>

400

Error in request:

Could not find

requested object.

Testing Legal Entity Transactions PayFac API Certification Tests

Document Version: 2.1 — API Release: 13.0 17

PayFac API Reference Guide

TABLE 2-6 Retrieve Legal Entity Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

C.3.1 legalEntityId Use the value

returned in the

response message

from Test #C.1.2.

HTTP Status Code:

XML Response:

200

Approved

Note: Response

message will include

other Legal Entity

information

submitted with Test

#C.1.2.

C.3.2 legalEntityId Submit any invalid

value HTTP Status Code:

XML Response:

<error>

400

Error in request:

Could not find

requested object.

PayFac API Certification Tests Testing Sub-Merchant Transactions

18 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

2.2 Testing Sub-Merchant Transactions

The following sections provide information used to test the creation and updating of

Sub-merchants, as well as the retrieval of information for already existing Sub-merchants.

2.2.1 Creating Sub-Merchants

After creating a Legal Entity, you can create one or more Sub-merchants associated with the

Legal Entity. Create transactions that succeed return a subMerchantCreateResponse

message, while transactions that fail return an errorResponse message.

To test the creation of Sub-merchants:

1. Verify that your Create Sub-merchant template is coded correctly (see Create Sub-Merchant

on page 60).

2. Submit subMerchantCreateRequest transaction using the data provided for Test # 8, 9,

and 10. You must provide the data for all other required elements.

3. Verify that your system parses the response file correctly and that the value are those shown

in the Key Response Elements of the table.

NOTE:For Canadian Sub-merchant creation tests see section Creating Canadian

Sub-merchants on page 19.

TABLE 2-7 Create Sub-merchant Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

8 legalEntityId Use the value

returned in the

response message

from Test #1.

HTTP Status Code: 201

9 legalEntityId Submit any invalid

value HTTP Status Code:

XML Response:

<error>

400

Error in request:

Could not find

requested object.

Testing Sub-Merchant Transactions PayFac API Certification Tests

Document Version: 2.1 — API Release: 13.0 19

PayFac API Reference Guide

2.2.2 Creating Canadian Sub-merchants

To test the creation of Canadian Sub-merchants:

1. Verify that your Create Sub-merchant template is coded correctly (see Create Sub-Merchant

on page 60).

2. Submit subMerchantCreateRequest transaction using the data provided in Table 2-8. You

must provide the data for all other required elements.

3. Verify that your system parses the response file correctly and that the value are those shown

in the Key Response Elements of the table.

10 legalEntityId Use the value

returned in the

response message

from Test #2.

HTTP Status Code:

XML Response:

<error>

400

Error in request:

Legal entity

[legalEntityName] is

in inactive state. You

cannot add/update a

submerchant.

TABLE 2-8 Create Canadian Sub-merchant Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

C.4.1 legalEntityId Use the value

returned in the

response message

from Test #C.1.1.

HTTP Status Code: 201

TABLE 2-7 Create Sub-merchant Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

PayFac API Certification Tests Testing Sub-Merchant Transactions

20 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

C.4.2 legalEntityId

Use the value

returned in the

response message

from Test #C.1.1.

USD

CAD

HTTP Status Code:

XML Response:

<error>

400

Error in request: No

processing group

defined with

purchaseCurrencyCo

de <840> and

settlementCurrencyC

ode <124>

C.4.3 legalEntityId

Use the value

returned in the

response message

from Test #C.1.1.

USA

HTTP Status Code:

XML Response:

<error>

400

Error in request:

Submerchant

country code “USA”

does not match

Legal Entity country

code “CAN”

C.4.4 legalEntityId Use the value

returned in the

response message

from Test #C.1.3.

HTTP Status Code:

XML Response:

<error>

400

Error in request:

Legal Entity “Legal

Entity Name” has not

been approved

C.4.5 legalEntityId

Use the value

returned in the

response message

from Test #C.1.1.

01970

HTTP Status Code:

XML Response:

<error>

400

Postal Code “01970”

is not valid for

country “CAN”.

TABLE 2-8 Create Canadian Sub-merchant Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

Testing Sub-Merchant Transactions PayFac API Certification Tests

Document Version: 2.1 — API Release: 13.0 21

PayFac API Reference Guide

2.2.3 Updating Sub-Merchant information

You can update the several items associated with a Sub-Merchant. To update information

associated with a Sub-merchant, you use a PUT method with the appropriate legalEntityId,

subMerchantId, and a subMerchantUpdatable message containing the information to be

updated.

You can update the following items:

To test the subMerchantUpdatable transaction:

1. Verify that your Update Sub-Merchant template is coded correctly (see Update Sub-Merchant

on page 67).

2. Submit subMerchantUpdatable transaction using the data provided for Test # 11, 12, and

13. You must to provide the data for all other required elements.

3. Verify that your system parses the response file correctly and that the value are those shown

in the Key Response Elements of the table.

NOTE:For Canadian Sub-merchant update tests see section Updating Canadian

Sub-Merchant Information on page 22.

•url •streetAddress1

•customerServiceNumber •streetAddress2

•hardCodedBillingDescriptor •city

•maxTransactionAmount •stateProvince

•bankRoutingNumber •postalCode

•bankAccountNumber

PayFac API Certification Tests Testing Sub-Merchant Transactions

22 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

2.2.4 Updating Canadian Sub-Merchant Information

To test the subMerchantUpdatable transaction:

1. Verify that your Update Sub-Merchant template is coded correctly (see Update Sub-Merchant

on page 67).

2. Submit subMerchantUpdatable transaction using the data provided in Table 2-10. You

must to provide the data for all other required elements.

3. Verify that your system parses the response file correctly and that the value are those shown

in the Key Response Elements of the table.

TABLE 2-9 Update Sub-merchant Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

11 legalEntityId

subMerchantId

Use the value

returned in the

response message

from Test # 1.

Use the value

returned in the

response message

from Test # 8.

HTTP Status Code: 200

12 legalEntityId

subMerchantId

Submit any invalid

value

Submit any valid or

invalid value.

HTTP Status Code:

XML Response:

<error>

400

Error in request:

Could not find

requested object.

13 legalEntityId

subMerchantId

Use the value

returned in the

response message

from Test #1.

Submit any invalid

value.

HTTP Status Code:

XML Response:

<error>

400

Error in request:

Could not find

requested object.

Testing Sub-Merchant Transactions PayFac API Certification Tests

Document Version: 2.1 — API Release: 13.0 23

PayFac API Reference Guide

TABLE 2-10 Update Canadian Sub-merchant Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

C.5.1 legalEntityId

subMerchantId

Use the value

returned in the

response message

from Test # C.1.1.

Use the value

returned in the

response message

from Test # C.4.1.

HTTP Status Code: 200

C.5.2 legalEntityId

subMerchantId

Submit any invalid

value

Submit any valid or

invalid value.

HTTP Status Code:

XML Response:

<error>

400

Error in request:

Could not find

requested object.

C.5.3 legalEntityId

subMerchantId

Use the value

returned in the

response message

from Test #C.1.1.

Submit any invalid

value.

HTTP Status Code:

XML Response:

<error>

400

Error in request:

Could not find

requested object.

PayFac API Certification Tests Testing Sub-Merchant Transactions

24 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

2.2.5 Retrieving Sub-Merchant Information

If you need to retrieve the on-boarding information related to a Sub-merchant for verification

purposes, you must perform a GET operation specifying the legalEntityId and

subMerchantId.

To test the retrieval of Sub-merchant information use the information supplied in Table 2-11.

TABLE 2-11 Retrieve Sub-merchant Information Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

14 legalEntityId

subMerchantId

Use the value

returned in the

response message

from Test # 1.

Use the value

returned in the

response message

from Test # 8.

HTTP Status Code: 200

15 legalEntityId

subMerchantId

Submit any invalid

value

Submit any valid or

invalid value.

HTTP Status Code:

XML Response:

<error>

400

Error in request:

Could not find

requested object.

16 legalEntityId

subMerchantId

Use the value

returned in the

response message

from Test #1.

Submit any invalid

value.

HTTP Status Code:

XML Response:

<error>

400

Error in request:

Could not find

requested object.

Testing Sub-Merchant Transactions PayFac API Certification Tests

Document Version: 2.1 — API Release: 13.0 25

PayFac API Reference Guide

2.2.6 Retrieving Canadian Sub-Merchant Information

To test the retrieval of Canadian Sub-merchant information use the information supplied in

Table 2-12.

2.2.7 Retrieve Allowed MCC List

When on-boarding a new Sub-merchant, a Payment Service Provider should only use one of the

approved MCCs. To retrieve the allowed MCC list perform a GET operation with the parameter

mcc (GET/mcc).

Verify that you correctly parse the list returned. Please refer to Retrieve MCC List Response on

page 74 for an example of the structure of the response message.

TABLE 2-12 Retrieve Canadian Sub-merchant Information Test Data

Test #

Supplied Data Elements Key Response Elements

Element Value Element Value

14 legalEntityId

subMerchantId

Use the value

returned in the

response message

from Test # C.1.1.

Use the value

returned in the

response message

from Test # C.4.1.

HTTP Status Code: 200

PayFac API Certification Tests Testing Sub-Merchant Transactions

26 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

Document Version: 2.1 — API Release: 13.0 27

PAYFAC API TRANSACTION EXAMPLES

This chapter contains examples showing the message structure used by the PayFac Merchant

Provisioner API. For each message type, the chapter provides a high level overview of the

message structure followed by one or more examples of request and response messages.

Examples of Error messages are also provided. The following message types are discussed:

•Create Legal Entity Agreement

•Legal Entity Agreement Retrieval Request

•Create Legal Entity

•Update Legal Entity

•Retrieve Legal Entity

•Create a Principal

•Delete a Principal

•Create Sub-Merchant

•Update Sub-Merchant

•Retrieve Sub-Merchant

•Retrieve Allowed MCC List

•Status Codes and Error Messages

NOTE:Each high-level structural example shows the message parent element

and its children (one element down). The parent and each child element

links to the element definition page in Chapter 4. Where there is additional

structure under the child element, the element definition page includes

structural examples.

PayFac API Transaction Examples Create Legal Entity Agreement

28 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

3.1 Create Legal Entity Agreement

You use the Create Legal Entity Agreement request transaction to designate the version of the

agreement along with information about the agreeing party. You should use this transaction type

only if your PayFac Account Manager directs you to do so.

To create a Legal Entity Agreement use an HTTP POST method to submit the

legalEntityAgreementCreateRequest message.

3.1.1 Create Legal Entity Agreement Request Message

You must structure a Create Legal Entity Agreement request as shown in the following examples.

<legalEntityAgreementType>MERCHANT_AGREEMENT</legalEntityAgreementType>

<agreementVersion>Agreement Version Number</agreementVersion>

<userFullName>Full Name of Signer</userFullName>

<userSystemName>User Name of Signer of PayFac System</userSystemName>

<userIPAddress>IP Address of Signer’s system</userIPAdress>

<manuallyEntered>true or false</manuallyEntered>

<acceptanceDateTime>Date and Time Agreement Signed</acceptanceDateTime>

</legalEntityAgreement>

</legalEntityAgreementCreateRequest>

TABLE 3-1 Resource Information

HTTP Method POST

Call /legalentity/legalEntityId/agreement

Request Format XML

Response Format XML

Rate Limited No

TABLE 3-2 POST Parameters

Parameter Required or Optional Description

legalEntityId Required The Id of the Legal Entity

Create Legal Entity Agreement PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 29

PayFac API Reference Guide

Example: Create Legal Entity Agreement Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<legalEntityAgreementCreateRequest

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

<legalEntityAgreementType>MERCHANT_AGREEMENT</legalEntityAgreementType>

<agreementVersion>agreementVersion1</agreementVersion>

<userFullName>userFullName</userFullName>

<userSystemName>systemUserName</userSystemName>

<manuallyEntered>false</manuallyEntered>

</legalEntityAgreement>

</legalEntityAgreementCreateRequest>

3.1.2 Create Legal Entity Agreement Response Message

The structure for the response to a Create Legal Entity Agreement request has the following

structure.

</legalEntityAgreementCreateResponse>

NOTE:If the value for the <manuallyEntered> element is false, you must

include the <userIPAddress> element. If the value for the

<manuallyEntered> element is true, you can omit the <userIPAddress>

element.

NOTE:If the create request is a duplicate, the response message includes a

duplicate=”true” attribute.

If the request fails, the system returns an error response. See Status

Codes and Error Messages on page 76.

PayFac API Transaction Examples Legal Entity Agreement Retrieval Request

30 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

3.2 Legal Entity Agreement Retrieval Request

You use the Legal Entity Agreement Retrieval request to retrieve all agreements associated with a

specified Legal Entity.

To retrieve a all agreements associated with a Legal Entity use an HTTP GET method to submit

the legalEntityAgreementCreateRequest message.

3.2.1 Legal Entity Agreement Retrieval Response

The structure of the response message is as follows:

<legalEntityAgreementType>MERCHANT_AGREEMENT</legalEntityAgreementType>

<agreementVersion>Agreement Version Number</agreementVersion>

<userFullName>Full Name of Signer</userFullName>

<userSystemName>User Name of Signer of PayFac System</userSystemName>

<userIPAddress>IP Address of Signer’s system</userIPAdress>

TABLE 3-3 Resource Information

HTTP Method GET

Call /legalentity/legalEntityId/agreement

Request Format XML

Response Format XML

Rate Limited No

TABLE 3-4 GET Parameters

Parameter Required or Optional Description

legalEntityId Required The Id of the Legal Entity

NOTE:If there are more than one agreements associated with the Legal Entity,

the Retrieval Response message will have an agreements element

containing a legalEntityArgeement child for each agreement.

Legal Entity Agreement Retrieval Request PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 31

PayFac API Reference Guide

<manuallyEntered>true or false</manuallyEntered>

<acceptanceDateTime>Date and Time Agreement Signed</acceptanceDateTime>

</legalEntityAgreement>

</agreements>

</legalEntityAgreementRetrievalResponse>

Example: Legal Entity Agreement Response (no agreements)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<legalEntityAgreementRetrievalResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

</legalEntityAgreementRetrievalResponse>

Example: Legal Entity Agreement Response (with agreements)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<legalEntityAgreementRetrievalResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

<legalEntityAgreementType>MERCHANT_AGREEMENT</legalEntityAgreementType>

<agreementVersion>agreementVersion1</agreementVersion>

<userFullName>userFullName</userFullName>

<userSystemName>systemUserName</userSystemName>

<manuallyEntered>false</manuallyEntered>

</legalEntityAgreement>

<legalEntityAgreementType>MERCHANT_AGREEMENT</legalEntityAgreementType>

<agreementVersion>agreementVersion4</agreementVersion>

<userFullName>userFullNameFour</userFullName>

<userSystemName>systemUserNameFour</userSystemName>

<manuallyEntered>false</manuallyEntered>

</legalEntityAgreement>

PayFac API Transaction Examples Legal Entity Agreement Retrieval Request

32 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<legalEntityAgreementType>MERCHANT_AGREEMENT</legalEntityAgreementType>

<agreementVersion>agreementVersion3</agreementVersion>

<userFullName>userFullNameThree</userFullName>

<userSystemName>systemUserNameThree</userSystemName>

<manuallyEntered>false</manuallyEntered>

</legalEntityAgreement>

<legalEntityAgreementType>MERCHANT_AGREEMENT</legalEntityAgreementType>

<agreementVersion>agreementVersion2</agreementVersion>

<userFullName>userFullNameTwo</userFullName>

<userSystemName>systemUserNameTwo</userSystemName>

</legalEntityAgreement>

</agreements>

</legalEntityAgreementRetrievalResponse>

Create Legal Entity PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 33

PayFac API Reference Guide

3.3 Create Legal Entity

Prior to creating new Sub-merchants, a PayFac (Payment Facilitator) must establish the Legal

Entity. The Legal Entity is the business or taxable entity (for example, corporation, or LLC)

controlling the Sub-merchant within the system. You create the Legal Entity using the

legalEntityCreateRequest message.

To create a Legal Entity use an HTTP POST method to submit the

legalEntityCreateRequest message.

3.3.1 Notes About Background Checks

As part of the Legal Entity creation process, Vantiv performs background and MasterCard

MATCH checks as part of Risk Analysis and/or underwriting the Legal Entity. Depending upon

the level of service configured for the Background Check operation (see Legal Entity Processing

on page 3), different verification operations occur and the system returns different results in the

response file.

Only when the MasterCard MATCH and/or other background checks have a positive outcome, or

the Legal Entity was reviewed by a Vantiv risk analyst and approved, will you be able to register

one or more Sub-merchants for the Legal Entity. You create and assign the sub-merchant through

the use of the subMerchantCreateRequest (see Create Sub-Merchant on page 60) using the

legalEntityId returned in the create legal entity response (see Create Legal Entity Response

Message on page 36)

TABLE 3-5 Resource Information

HTTP Method POST

Call /legalentity

Request Format XML

Response Format XML

Rate Limited No

PayFac API Transaction Examples Create Legal Entity

34 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

3.3.2 Notes About Required Fields

In order to create the Legal Entity and perform the background checks, there are a number of

required fields in the legalEntityCreateRequest message. Please note, the required fields

vary according to the legalEntityType designation or if you process as part of the Vantiv

PayFac Assurance program.

The following fields are required for all Legal Entity Types:

•legalEntityName

•legalEntityType

•taxId (EIN for Canada)

•firstName (principal)

•lastName (principal)

•streetAddress1 (Legal Entity)

•stateProvince (Legal Entity)

•city (Legal Entity)

•postalCode (Legal Entity)

•countryCode (Legal Entity)

•annualCreditCardSalesVolume

•hasAcceptedCreditCards

•dateOfBirth (Principal)

•stakePercent (Principal)

•title (Principal) (Required only if using AmEx Opt Blue)

•legalEntityOwnershipType

If the value for the legalEntityType element is INDIVIDUAL_SOLE_PROPRIETORSHIP,

in addition to the fields listed above, you must also include the following fields:

NOTE:When creating a Legal Entity, you must define the controlling Principal of

the Legal Entity. Use the legalEntityPrincipalCreateRequest (see

Create Create a Principal on page 54) to add all other Principal with a 10%

or greater ownership of the Legal Entity.

NOTE:In addition to the required fields listed above, Vantiv recommends that

you also include the contact phone number (contactPhone element) of

the principal, as well as the business phone number of the Legal Entity

and the DBA name (doingBusinessAs field).

Create Legal Entity PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 35

PayFac API Reference Guide

•streetAddress1 (Principal)

•stateProvince (Principal)

•city (Principal)

•postalCode (Principal)

•countryCode (Principal)

If you process as part of the Vantiv PayFac Assurance program, in addition to the fields listed

above, you must also include the following fields:

•title (Principal)

•yearsInBusiness (Legal Entity)

•url (Sub-merchant)

3.3.3 Create Legal Entity Request Message

You must structure a Create Legal Entity request as shown in the following examples.

<legalEntityName>Name of Legal Entity</legalEntityName>

<legalEntityType>Type of Legal Entity</legalEntityType>

<legalEntityOwnershipType>PUBLIC or PRIVATE</legalEntityOwnershipType>

<doingBusinessAs>Alternate Name</doingBusinessAs>

<contactPhone>Legal Entity Contact Number</contactPhone>

<annualCreditCardSalesVolume>Annual Visa Sales</annualCreditCardSalesVolume>

<hasAcceptedCreditCards>true or false</hasAcceptedCreditCards>

<yearsInBusiness>Number of Years in Business</yearsInBusiness>

</legalEntityCreateRequest>

Example: Create Legal Entity Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<legalEntityCreateRequest

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

<legalEntityName>Legal Entity Name</legalEntityName>

<legalEntityType>CORPORATION</legalEntityType>

<legalEntityOwnershipType>PUBLIC</legalEntityOwnershipType>

<doingBusinessAs>Alternate Business Name</doingBusinessAs>

PayFac API Transaction Examples Create Legal Entity

36 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<streetAddress1>Street Address 1</streetAddress1>

<streetAddress2>Street Address 2</streetAddress2>

</address>

<title>Chief Financial Officer</title>

<firstName>p first</firstName>

<emailAddress>emailAddress</emailAddress>

<streetAddress1>p street address 1</streetAddress1>

<streetAddress2>p street address 2</streetAddress2>

<city>Boston</city>

</address>

</principal>

</legalEntityCreateRequest>

3.3.4 Create Legal Entity Response Message

The structure for the response to a Create Legal Entity message varies slightly depending upon if

it is an original request, a duplicate request with all data matching (true duplicate), or a duplicate

with data that does not entirely match, as well as the state of the original request, if the new

request is a duplicate. The response message has the following structure with exceptions as noted:

Create Legal Entity PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 37

PayFac API Reference Guide

<legalEntityId>ID assigned to Legal Entity</legalEntityId>(appears if first

request)

<responseCode>Response Code</responseCode>

<responseDescription>Description of Response Code</responseDescription>

<originalLegalEntityId>Original ID assigned to Legal

Entity</originalLegalEntityId> (appears if dupe)

<originalLegalEntityStatus>Original Status of Legal

Entity</originalLegalEntityStatus> (appears if dupe)

<backgroundCheckResults> (part of originalLegalEntity if present; otherwise,

at this level)

</legalEntityCreateResponse>

Example: Create Legal Entity Response - for original

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<legalEntityResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

<responseDescription>Approved</responseDescription>

<firstName>p first</firstName>

</principal>

<score>Overall results for Business</score>

<description>Text Description of Score</description>

</overallScore>

<code>Name_Address_TIN_info</code>

<description>Text Description of Code</description>

</nameAddressTaxIdAssociation>

NOTE:If you receive a Response Code 30 - Retry, the decision notes will contain

additional details about the information that you should provide/correct

on the retry.

PayFac API Transaction Examples Create Legal Entity

38 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<code>Name_Address_Phone_info</code>

<description>Text Description of Code</description>

</nameAddressPhoneAssociation>

<nameVerified>true or false</nameVerified>

<addressVerified>true or false</addressVerified>

<cityVerified>true or false</cityVerified>

<zipVerified>true or false</zipVerified>

<phoneVerified>true or false</phoneVerified>

<taxIdVerified>true or false</taxIdVerified>

</verificationIndicators>

<code>Risk Indicator Info</code>

<description>Text Description of Code</description>

</riskIndicator>

</riskIndicators>

</verificationResult>

</business>

<score>Overall Results for Principal</score>

<description>Text Description of Score</description>

</overallScore>

<code>Name_Address_SSN_info</code>

<description>Text Description of Code</description>

</nameAddressSsnAssociation>

<code>Name_Address_Phone_info</code>

<description>Text Description of Code</description>

</nameAddressPhoneAssociation>

<nameVerified>true or false</nameVerified>

<addressVerified>true or false</addressVerified>

<phoneVerified>true or false</phoneVerified>

<ssnVerified>true or false</ssnVerified>

<dobVerified>true or false</dobVerified>

</verificationIndicators>

Create Legal Entity PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 39

PayFac API Reference Guide

<code>Risk Indicator results</code>

<description>Text Description of Code</description>

</riskIndicator>

</riskIndicators>

</verificationResult>

</principal>

<score>Business_To_Principal_info</score>

<description>Text Description of Score</description>

</businessToPrincipalAssociation>

<backgroundCheckDecisionNotes>Additional Info About

Decision</backgroundCheckDecisionNotes>

<bankruptcyType>Sub-category of bankruptcy</bankruptcyType>

<companyName>Company Name</companyName>

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 2</streetAddress2>

<city>Boston</city>

</bankruptcyData>

<lienType>Subtype of Lien</lienType>

<companyName>Company Name</companyName>

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 2</streetAddress2>

<city>Boston</city>

</lienResult>

</backgroundCheckResults>

</legalEntityResponse>

PayFac API Transaction Examples Create Legal Entity

40 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

Example: Create Legal Entity Response - for duplicate

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<legalEntityCreateResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard" duplicate="true">

<responseDescription>Duplicate</responseDescription>

<originalLegalEntityStatus>Approved</originalLegalEntityStatus>

<description>Business is verified on multiple sources with no

contradictory findings</description>

</overallScore>

<nameVerified>false</nameVerified>

<addressVerified>false</addressVerified>

<cityVerified>false</cityVerified>

<stateVerified>false</stateVerified>

<zipVerified>false</zipVerified>

<phoneVerified>false</phoneVerified>

<taxIdVerified>false</taxIdVerified>

</verificationIndicators>

<code>ADDRESS_MATCHES_PRISON</code>

<description>The input address matches a prison

address</description>

</riskIndicator>

</riskIndicators>

</verificationResult>

</business>

<description>Full name, address, phone, SSN verified</description>

Create Legal Entity PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 41

PayFac API Reference Guide

</overallScore>

<nameVerified>false</nameVerified>

<addressVerified>false</addressVerified>

<phoneVerified>false</phoneVerified>

<ssnVerified>false</ssnVerified>

<dobVerified>false</dobVerified>

</verificationIndicators>

<code>ADDRESS_MATCHES_PRISON</code>

<description>The input address matches a prison

address</description>

</riskIndicator>

</riskIndicators>

</verificationResult>

</principal>

<description>Association found between the person and the company in

the Company Contacts data</description>

</businessToPrincipalAssociation>

<bankruptcyType>Sub-category of bankruptcy</bankruptcyType>

<companyName>Company Name</companyName>

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 2</streetAddress2>

<city>Boston</city>

</bankruptcyData>

<lienType>Subtype of Lien</lienType>

<companyName>Company Name</companyName>

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 2</streetAddress2>

PayFac API Transaction Examples Create Legal Entity

42 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<city>Boston</city>

</lienResult>

</backgroundCheckResults>

</legalEntityCreateResponse>

NOTE:If the Legal Entity is in Manual Review the response would be identical to

the above response except the responseCode element would have a

value of 35 (instead of 36) and the responseDescription would be:

Manual review - Duplicate.

Update Legal Entity PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 43

PayFac API Reference Guide

3.4 Update Legal Entity

You can update the several items associated with a Legal Entity, including information about a

Principal. To update information associated with a Legal Entity, you submit a

legalEntityUpdateRequest message with the appropriate legalEntityId and the updated

information.

You can update the following items:

•streetAddress1 (entity and/or principal) •firstName (principal)

•streetAddress2 (entity and/or principal) •lastName (principal)

•city (entity and/or principal) •ssn (principal)

•stateProvince (entity and/or principal) •dateOfBirth (principal)

•postalCode (entity and/or principal) •driversLicense (principal)

•doingBusinessAs •driversLicenseState (principal)

•annualCreditCardSalesVolume •legalEntityName

•hasAcceptedCreditCards •legalEntityType

•contactPhone (entity and/or principal) •taxId

•title (principal) •yearsInBusiness

•emailAddress (principal)

NOTE:If the Legal Entity is approved and the TIN validation status is either

approved or not required, you can not update the following elements:

legalEntityName, legalEntityType, taxId, firstName, lastName,

ssn, dateOfBirth, driversLicense, driversLicenseState.

Prior to the TIN validation, updating any of these elements triggers a

background check.

TABLE 3-6 Resource Information

HTTP Methods PUT

Call /legalentity/legalEntityId

Request Format XML

Response Format XML

PayFac API Transaction Examples Update Legal Entity

44 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

3.4.1 Update Legal Entity Request

You must structure an Update Legal Entity request as shown in the following examples.

<legalEntityOwnershipType>PUBLIC</legalEntityOwnershipType>

</legalEntityUpdateRequest>

Example: Update Legal Entity Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<legalEntityUpdateRequest

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

<streetAddress1>LE Street Address 1</streetAddress1>

<streetAddress2>LE Street Address 2</streetAddress2>

</address>

<doingBusinessAs>Other Name Co.</doingBusinessAs>

Rate Limited Yes

TABLE 3-7 PUT Parameters

Parameter Required or Optional Description

legalEntityId Required The Id of the Legal Entity

TABLE 3-6 Resource Information

Update Legal Entity PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 45

PayFac API Reference Guide

<streetAddress1>p street address 1</streetAddress1>

<streetAddress2>p street address 2</streetAddress2>

<city>Boston</city>

</address>

<firstName>p first</firstName>

</backgroundCheckFields>

</principal>

<legalEntityName>Company Name</legalEntityName>

</backgroundCheckFields>

<legalEntityOwnershipType>PUBLIC</legalEntityOwnershipType>

</legalEntityUpdateRequest>

3.4.2 Update Legal Entity Response

The system replies to an Update Legal Entity request with a generic response message. The

structure of the response message is as follows:

<legalEntityId> (appears if first request of dupe with all matching data)

PayFac API Transaction Examples Update Legal Entity

46 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<backgroundCheckResults> (appears if background check triggered by update)

</legalEntityResponse>

Example: Update Legal Entity Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<legalEntityResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

<responseDescription>Approved</responseDescription>

<firstName>p first</firstName>

</principal>

<score>Overall results for Business</score>

<description>Text Description of Score</description>

</overallScore>

<code>Name_Address_TIN_info</code>

<description>Text Description of Code</description>

</nameAddressTaxIdAssociation>

<code>Name_Address_Phone_info</code>

<description>Text Description of Code</description>

</nameAddressPhoneAssociation>

<nameVerified>true or false</nameVerified>

<addressVerified>true or false</addressVerified>

<cityVerified>true or false</cityVerified>

<zipVerified>true or false</zipVerified>

<phoneVerified>true or false</phoneVerified>

<taxIdVerified>true or false</taxIdVerified>

</verificationIndicators>

Update Legal Entity PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 47

PayFac API Reference Guide

<code>Risk Indicator Info</code>

<description>Text Description of Code</description>

</riskIndicator>

</riskIndicators>

</verificationResult>

</business>

<score>Overall Results for Principal</score>

<description>Text Description of Score</description>

</overallScore>

<code>Name_Address_SSN_info</code>

<description>Text Description of Code</description>

</nameAddressSsnAssociation>

<code>Name_Address_Phone_info</code>

<description>Text Description of Code</description>

</nameAddressPhoneAssociation>

<nameVerified>true or false</nameVerified>

<addressVerified>true or false</addressVerified>

<phoneVerified>true or false</phoneVerified>

<ssnVerified>true or false</ssnVerified>

<dobVerified>true or false</dobVerified>

</verificationIndicators>

<code>Risk Indicator results</code>

<description>Text Description of Code</description>

</riskIndicator>

</riskIndicators>

</verificationResult>

</principal>

<score>Business_To_Principal_info</score>

<description>Text Description of Score</description>

</businessToPrincipalAssociation>

<backgroundCheckDecisionNotes>Additional Info About

Decision</backgroundCheckDecisionNotes>

PayFac API Transaction Examples Update Legal Entity

48 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<bankruptcyType>Sub-category of bankruptcy</bankruptcyType>

<companyName>Company Name</companyName>

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 2</streetAddress2>

<city>Boston</city>

</bankruptcyData>

<lienType>Subtype of Lien</lienType>

<companyName>Company Name</companyName>

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 2</streetAddress2>

<city>Boston</city>

</lienResult>

</backgroundCheckResults>

</legalEntityResponse>

Retrieve Legal Entity PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 49

PayFac API Reference Guide

3.5 Retrieve Legal Entity

If you need to retrieve the latest information on file related to a Legal Entity for verification

purposes or to check the status of cases requiring manual intervention, you must perform a GET

operation specifying the legalEntityId. In the case of a retrieval request, the system does not

require an accompanying XML message.

3.5.1 Retrieve Legal Entity Response

The legalEntityRetrieveResponse message has the following format:

<legalEntityName>Name of Legal Entity</legalEntityName>

<legalEntityType>Type of Legal Entity</legalEntityType>

<doingBusinessAs>Alternate Name</doingBusinessAs>

<contactPhone>Legal Entity Contact Number</contactPhone>

<annualCreditCardSalesVolume>Annual Visa Sales</annualCreditCardSalesVolume>

<hasAcceptedCreditCards>true or false</hasAcceptedCrreditCards>

NOTE:Vantiv makes the final results for the manual review of Legal entity

information available within 2 business days of the initial response to the

create request.

TABLE 3-8 Resource Information

HTTP Methods GET

Call /legalentity/legalEntityId

Request Format XML

Response Format XML

Rate Limited Yes

TABLE 3-9 GET Parameters

Parameter Required or Optional Description

legalEntityId Required The Id of the legalEntity

PayFac API Transaction Examples Retrieve Legal Entity

50 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<responseCode>3-digit Code</responseCode>

<responseDescription>Description of Response Code</responseDescription>

<updateDate>YYYY-MM-DDTHH:MM:SS+/-HH:MM</updateDate>

<decisionDate>YYYY-MM-DDTHH:MM:SS+/-HH:MM</decisionDate>

<tinValidationStatus>Pending</tinValidationStatus>

<sub_merchant_processing_status>true or false</sub_merchant_processing_status>

</legalEntityRetrievalResponse>

Example: Legal Entity Retrieval Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<legalEntityRetrievalResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard"

overallStatus="Approved">

<legalEntityName>Legal Entity Name</legalEntityName>

<legalEntityType>CORPORATION</legalEntityType>

<doingBusinessAs>Alternate Name</doingBusinessAs>

<streetAddress1>12 Norton St</streetAddress1>

</address>

<firstName>p first</firstName>

<emailAddress>emailAddress</emailAddress>

<ssn>XXXXX-9876</ssn>

Retrieve Legal Entity PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 51

PayFac API Reference Guide

<driversLicense>XXXXXXXX-9832</driversLicense>

<streetAddress1>p street address 1</streetAddress1>

<streetAddress2>p street address 2</streetAddress2>

<city>Boston</city>

</address>

</principal>

<responseDescription>Approved</responseDescription>

<score>Overall results for Business</score>

<description>Text Description of Score</description>

</overallScores>

<code>Name_Address_TIN_info</code>

<description>Text Description of Code</description>

</nameAddressTaxIdAssociation>

<code>Name_Address_Phone_info</code>

<description>Text Description of Code</description>

</nameAddressPhoneAssociation>

<nameVerified>true or false</nameVerified>

<addressVerified>true or false</addressVerified>

<cityVerified>true or false</cityVerified>

<zipVerified>true or false</zipVerified>

<phoneVerified>true or false</phoneVerified>

<taxIdVerified>true or false</taxIdVerified>

</verificationIndicators>

<code>Risk Indicator Info</code>

<description>Text Description of Code</description>

PayFac API Transaction Examples Retrieve Legal Entity

52 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

</riskIndicator>

</riskIndicators>

</verificationResult>

</business>

<score>Overall Results for Principal</score>

<description>Text Description of Score</description>

</overallScores>

<code>Name_Address_SSN_info</code>

<description>Text Description of Code</description>

</nameAddressSsnAssociation>

<code>Name_Address_Phone_info</code>

<description>Text Description of Code</description>

</nameAddressPhoneAssociation>

<nameVerified>true or false</nameVerified>

<addressVerified>true or false</addressVerified>

<phoneVerified>true or false</phoneVerified>

<ssnVerified>true or false</ssnVerified>

<dobVerified>true or false</dobVerified>

</verificationIndicators>

<code>Risk Indicator results</code>

<description>Text Description of Code</description>

</riskIndicator>

</riskIndicators>

</verificationResult>

</principal>

<score>Business_To_Principal_info</score>

<description>Text Description of Score</description>

</businessToPrincipalAssociation>

<backgroundCheckDecisionNotes>Additional Info About

Decision</backgroundCheckDecisionNotes>

<bankruptcyType>Sub-category of bankruptcy</bankruptcyType>

<companyName>Company Name</companyName>

Retrieve Legal Entity PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 53

PayFac API Reference Guide

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 2</streetAddress2>

<city>Boston</city>

</bankruptcyData>

<lienType>Subtype of Lien</lienType>

<companyName>Company Name</companyName>

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 2</streetAddress2>

<city>Boston</city>

</lienResult>

</backgroundCheckResults>

<tinValidationStatus>Status of TIN Validation</tinValidationStatus>

<sub_merchant_processing_status>true</sub_merchant_processing_status>

</legalEntityRetrievalResponse>

PayFac API Transaction Examples Create a Principal

54 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

3.6 Create a Principal

When you create a Legal Entity, you also create a Principal. You must create a Principal for each

person that owns 10% or more of the Legal Entity. To create additional Principals associated with

the Legal Entity you use a legalEntityPrincipalCreateRequest.

3.6.1 Principal Create Request

You must structure an Principal Create request as shown in the following examples.

</legalEntityPrincipalCreateRequest>

Example: Create Principal Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<legalEntityPrincipalCreateRequest

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

TABLE 3-10 Resource Information

HTTP Methods POST

Call /legalentity/legalEntityId/principal

Request Format XML

Response Format XML

Rate Limited Yes

TABLE 3-11 POST Parameters

Parameter Required or Optional Description

legalEntityId Required The Id of the Legal Entity.

NOTE:If the legalEntityType is SOLE_PROPRIETORSHIP, you cannot delete

or add Principals. The only Principal allowed is the one created with the

Legal Entity. Also, if you already defined multiple Principals, the system

does not allow you to change the legalEntityType to

SOLE_PROPRIETORSHIP until you delete all but one of the Principals.

Create a Principal PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 55

PayFac API Reference Guide

<firstName>First</firstName>

<emailAddress>abc@gmail.com</emailAddress>

<streetAddress1>p2 street address 1</streetAddress1>

<streetAddress2>p2 street address 2</streetAddress2>

<city>Boston2</city>

</address>

</principal>

</legalEntityPrincipalCreateRequest>

3.6.2 Principal Create Response

The structure of the response message is as follows:

<transactionId>Transaction ID</transactionId>

<principalId>ID of New Principal</principalId>

<firstName>First Name of Principal</firstName>

<lastName>Last Name of Principal</lastName>

<responseCode>Response Code</responseCode>

<responseDescription>Response Description</responseDescription>

<backgroundCheckResults>Background Checks Results</background Check Results>

</legalEntityPrincipalCreateResponse>

Example: Create Principal Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<principalCreateResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

<firstName>Princ First</firstName>

<lastName>Princ Last</lastName>

PayFac API Transaction Examples Create a Principal

56 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<responseDescription>Approved</responseDescription>

<description>Business is verified on multiple sources with no

contradictory findings</description>

</overallScore>

<nameVerified>false</nameVerified>

<addressVerified>false</addressVerified>

<cityVerified>false</cityVerified>

<stateVerified>false</stateVerified>

<zipVerified>false</zipVerified>

<phoneVerified>false</phoneVerified>

<taxIdVerified>false</taxIdVerified>

</verificationIndicators>

</verificationResult>

</business>

<description>Full name, address, phone , SSN verified</description>

</overallScore>

<nameVerified>false</nameVerified>

<addressVerified>false</addressVerified>

<phoneVerified>false</phoneVerified>

<ssnVerified>false</ssnVerified>

<dobVerified>false</dobVerified>

</verificationIndicators>

</verificationResult>

</principal>

Create a Principal PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 57

PayFac API Reference Guide

<description>Association found between the person and the company in

the Company Contacts data</description>

</businessToPrincipalAssociation>

<bankruptcyType>btype</bankruptcyType>

<companyName>testCompanyName</companyName>

<streetAddress1>testStreetAddress1</streetAddress1>

<streetAddress2>testStreetAddress2</streetAddress2>

<city>testCity</city>

</bankruptcyData>

<lienType>ltype</lienType>

<companyName>testLienCompanyName</companyName>

<streetAddress1>testLienStreetAddress1</streetAddress1>

<streetAddress2>testLienStreetAddress2</streetAddress2>

<city>testLienCity</city>

</lienResult>

</backgroundCheckResults>

</principalCreateResponse>

PayFac API Transaction Examples Delete a Principal

58 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

3.7 Delete a Principal

You can create and associate as many as four Principals with a Legal Entity. In the event that the

Principals change and you need to remove one or more from association with the Legal Entity,

you must delete a Principal. To delete a Principal perform a DELETE operation, specifying the

legalEntityId with the parameter principal and the principalId. The system does not

require an accompanying XML message.

3.7.1 Delete a Principal Response

The structure of the response message is as follows:

82820200338801014</transactionId>

<legalEntityId>ID of Legal entity</legalEntityId>

<principalId>Id of Deleted Principal</principalId>

<responseDescription>Description of Response</responseDescription>

</legalEntityPrincipalDeleteResponse>

NOTE:If the legalEntityType is SOLE_PROPRIETORSHIP, you cannot add or

delete Principals.

TABLE 3-12 Resource Information

HTTP Methods DELETE

Call /legalentity/legalEntityId/principal/principalId

Request Format XML

Response Format XML

Rate Limited Yes

TABLE 3-13 POST Parameters

Parameter Required or Optional Description

legalEntityId Required The Id of the Legal Entity.

principalId Required The Id of the Principal to be

deleted.

Delete a Principal PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 59

PayFac API Reference Guide

Example: Delete a Principal Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<legalEntityPrincipalDeleteResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

<responseDescription>Legal Entity Principal successfully

deleted</responseDescription>

</legalEntityPrincipalDeleteResponse>

PayFac API Transaction Examples Create Sub-Merchant

60 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

3.8 Create Sub-Merchant

Once you have established a Legal Entity, you can create one or more associated Sub-merchants.

For example, if the Legal Entity controlled three different business at different locations, you

would establish three Sub-merchants under the Legal Entity. You create new Sub-merchants by

submitting a subMerchantCreateRequest message.

3.8.1 Create Sub-Merchant Request

You must structure a Create Sub-merchant request as shown in the following examples.

<merchantName>My Company Name</merchantName>

<amexMid>Amex Merchant Id</amexMid>

<discoverConveyedMid>Discover Merchant Id</discoverConveyedMid>

<url>MyCompany.com</url>

<hardCodedBillingDescriptor>Default Descriptor<hardCodedBillingDescriptor>

TABLE 3-14 Resource Information

HTTP Methods POST

Call /legalentity/legalEntityId/submerchant

Request Format XML

Response Format XML

Rate Limited Yes

TABLE 3-15 POST Parameters

Parameter Required or Optional Description

legalEntityId Required The Id of the Legal Entity.

NOTE:After the creation of a Sub-merchant, wait a minimum of two minutes

before attempting to process transactions for the Sub-merchant. This is

the minimum amount of time required for information about the newly

created Sub-merchant to propagate through our system. Attempts to

process transactions for a new Sub-merchant sooner than two minutes

will result in system errors.

Create Sub-Merchant PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 61

PayFac API Reference Guide

<merchantCategoryCode>MCC Number</merchantCategoryCode>

<taxAuthority>Name of Tax Authority</taxAuthority> (MCC 9311 only)

<taxAuthorityState>State of Tax Authority</taxAuthorityState> (MCC 9311 only)

<fraud>

</subMerchantCreateRequest>

Example: Create Sub-merchant Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<subMerchantCreateRequest

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

<merchantName>Merchant Name</merchantName>

<url>http://merchantUrl</url>

<hardCodedBillingDescriptor>billing

Descriptor</hardCodedBillingDescriptor>

<streetAddress1>Street Address 1</streetAddress1>

PayFac API Transaction Examples Create Sub-Merchant

62 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<streetAddress2>Street Address 2</streetAddress2>

</address>

<emailAddress>John.Doe@company.com</emailAddress>

</primaryContact>

<eCheckCompanyName>Your Company Name</eCheckCompanyName>

</eCheck>

</subMerchantCreateRequest>

Example: Create Sub-merchant Request with Dynamic Payout

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<subMerchantCreateRequest

xmlns="http://psp.vantivcnp.com/api/merchant/onboard">

<merchantName>Merchant Name</merchantName>

<url>http://merchantUrl</url>

<hardCodedBillingDescriptor>billing

Descriptor</hardCodedBillingDescriptor>

<streetAddress1>Street Address 1</streetAddress1>

Create Sub-Merchant PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 63

PayFac API Reference Guide

<streetAddress2>Street Address 2</streetAddress2>

</address>

<emailAddress>John.Doe@company.com</emailAddress>

</primaryContact>

<eCheckCompanyName>Your Company Name</eCheckCompanyName>

</eCheck>

<fundingSubmerchantId>Unique Identifier</fundingSubmerchantId>

</subMerchantFunding>

</subMerchantCreateRequest>

Example: Create Sub-merchant Request with Managed Payout

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<subMerchantCreateRequest

xmlns="http://psp.vantivcnp.com/api/merchant/onboard">

<merchantName>Merchant Name</merchantName>

<url>http://merchantUrl</url>

<hardCodedBillingDescriptor>billing

Descriptor</hardCodedBillingDescriptor>

PayFac API Transaction Examples Create Sub-Merchant

64 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<streetAddress1>Street Address 1</streetAddress1>

<streetAddress2>Street Address 2</streetAddress2>

</address>

<emailAddress>John.Doe@company.com</emailAddress>

</primaryContact>

<eCheckCompanyName>Your Company Name</eCheckCompanyName>

</eCheck>

<feeProfile>Fee Profile Id</feeProfile>

</subMerchantFunding>

</subMerchantCreateRequest>

3.8.2 Create Sub-Merchant Response

The response message to the Create Sub-merchant request has the following structure:

<originalSubMerchant> (included only in some dulpicate cases)

<credentials> (included only if credentials requested)

<paypageCredentials> (only if credentials requested and PayPage enabled)

</subMerchantCreateResponse>

Create Sub-Merchant PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 65

PayFac API Reference Guide

Example: Create Sub-merchant Response with Credentials

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<subMerchantCreateResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

<password>MyPassword</password>

</credentials>

</paypageCredential>

</paypageCredentials>

</subMerchantCreateResponse>

Example: Create Sub-merchant Response - Duplicate with All Data Matching

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<subMerchantCreateResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard" duplicate="true">

</subMerchantCreateResponse>

Example: Create Sub-merchant Response - Duplicate with Data Not Matching

<subMerchantCreateResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard" duplicate="true">

NOTE:If the submission is a duplicate with changed data, the submerchantId

and merchantIdentString elements appear as children of the

originalSubmerchant element.

PayFac API Transaction Examples Create Sub-Merchant

66 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<merchantName>Merchant Name</merchantName>

<url>http://merchantUrl</url>

<hardCodedBillingDescriptor>billing

Descriptor</hardCodedBillingDescriptor>

<streetAddress1>Street Address 1</streetAddress1>

<streetAddress2>Street Address 2</streetAddress2>

</address>

<emailAddress>John.Doe@company.com</emailAddress>

</primaryContact>

</originalSubMerchant>

</subMerchantCreateResponse>

Update Sub-Merchant PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 67

PayFac API Reference Guide

3.9 Update Sub-Merchant

You can update the several items associated with a Sub-merchant. To update information

associated with a Sub-merchant, you submit a subMerchantUpdateRequest message with the

appropriate legalEntityId, subMerchantId, and the updated information.

You can update the following items:

NOTE:If/when the bank account and routing number of the Sub-merchant

changes, it is important that you notify us as soon as possible, so that our

required records are always up to date.

Also, please consult your Implementation Consultant before updating the

American Express Merchant Id (amexMid element) or the Discover

Merchant Id (discoverConveyedMid element), since this information has

direct impact on transaction processing.

•url •streetAddress1

•customerServiceNumber •streetAddress2

•hardCodedBillingDescriptor •city

•maxTransactionAmount •stateProvince

•bankRoutingNumber •postalCode

•bankAccountNumber •amexMid

•discoverConveyedMid •eCheckBillingDescriptor

•eCheckCompanyName

TABLE 3-16 Resource Information

HTTP Methods PUT

Call /legalentity/legalEntityId/submerchant/subMerchantId

Request Format XML

Response Format XML

Rate Limited Yes

PayFac API Transaction Examples Update Sub-Merchant

68 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

3.9.1 Update a Sub-Merchant

You must structure an Update Sub-merchant message as shown in the following examples:

<amexMid>Amex Merchant Id</amexMid>

<discoverConveyedMid>Discover Merchant Id</discoverConveyedMid>

<url>MyCompany.com</url>

<hardCodedBillingDescriptor>Default Descriptor</hardCodedBillingDescriptor>

<address>My Company Name</address>

<disable>true or false</disable>

<fraud>

<taxAuthority>Name of Tax Authority</taxAuthority> (MCC 9311 only)

<taxAuthorityState>State of Tax Authority</taxAuthorityState> (MCC 9311 only)

</subMerchantUpdateRequest>

Example: Update a Sub-Merchant Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<subMerchantUpdateRequest

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

TABLE 3-17 PUT Parameters

Parameter Required or Optional Description

legalEntityId Required The Id of the Legal Entity

subMerchantId Required The Id of the Sub-merchant

Update Sub-Merchant PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 69

PayFac API Reference Guide

<url>http://merchantUrl</url>

<hardCodedBillingDescriptor>Descriptor</hardCodedBillingDescriptor>

<streetAddress1>Street Address 1</streetAddress1>

<streetAddress2>Street Address 2</streetAddress2>

</address>

<emailAddress>John.Doe@company.com</emailAddress>

</primaryContact>

<eCheckCompanyName>Your Company Name</eCheckCompanyName>

</eCheck>

</subMerchantUpdateRequest>

3.9.2 Update a Sub-Merchant Response

The system replies to an Update Sub-merchant request with a generic response message. The

structure of the response message is as follows:

</response>

PayFac API Transaction Examples Retrieve Sub-Merchant

70 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

Example: Update Sub-Merchant Response

<?xml version="1.0" encoding="UTF-8" standalone="true"?>

</response>

3.10 Retrieve Sub-Merchant

If you need to retrieve the latest information on file related to a Sub-merchant for verification

purposes, you must perform a GET operation specifying the legalEntityId and

subMerchantId. A retrieval request does not require an accompanying XML message.

3.10.1 Retrieve Sub-Merchant Response

The retrieve Sub-merchant response message has the following structure:

NOTE:If you are processing transactions only on the Vantiv eCommerce platform

and using Dynamic Payout, after creating a Sub-merchant using a value of

AUTO_GENERATE for the fundingSubmerchantId, retrieve the

assigned fundingSubmerchantId value by submitting a Sub-merchant

Retrieval Request.

TABLE 3-18 Resource Information

HTTP Methods GET

Call /legalentity/legalEntityId/submerchant/subMerchantId

Request Format XML

Response Format XML

Rate Limited Yes

TABLE 3-19 GET Parameters

Parameter Required or Optional Description

legalEntityId Required The Id of the Legal Entity

subMerchantId Required The Id of the Sub-merchant

Retrieve Sub-Merchant PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 71

PayFac API Reference Guide

<merchantName>My Company Name</merchantName>

<amexMid>Amex Merchant Id</amexMid>

<discoverConveyedMid>Discover Merchant Id</discoverConveyedMid>

<url>MyCompany.com</url>

<hardCodedBillingDescriptor>Default Descriptor<hardCodedBillingDescriptor>

<merchantCategoryCode>MCC Number</merchantCategoryCode>

<bankAccountNumber>XXXXX-1234</bankAccountNumber>

<fraud>

<disabled>true or false</disabled>

2013-04-30T11:18:23.127-04:00</updateDate>

</subMerchantretrievalResponse>

Example: Retrieval Sub-Merchant Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<subMerchantRetrievalResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

<merchantName>Merchant Name</merchantName>

PayFac API Transaction Examples Retrieve Sub-Merchant

72 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<url>http://merchantUrl.com</url>

<hardCodedBillingDescriptor>billing

Descriptor</hardCodedBillingDescriptor>

<bankAccountNumber>XXXXX-3124</bankAccountNumber>

<streetAddress1>Street Address 1</streetAddress1>

<streetAddress2>Street Address 2</streetAddress2>

</address>

<emailAddress>John.Doe@company.com</emailAddress>

</primaryContact>

<eCheckCompanyName>Your Company Name</eCheckCompanyName>

</eCheck>

</subMerchantFunding>

<disabled>true or false</disabled>

<userName>UserName</userName>

<password>Password</password>

<passwordExpirationDate>2017-10-03T11:18:23.127-04:00</passwordExpirationD

Retrieve Sub-Merchant PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 73

PayFac API Reference Guide

ate>

</credentials>

<userName>PSPxm1V8</userName>

</paypageCredential>

<userName>PSPxm1V8Two</userName>

<paypageId>odzhgcbQX3e3EaKV</paypageId>

</paypageCredential>

<userName>PSPxm1V8Three</userName>

<paypageId>qmnpUBM6G47YJAcq</paypageId>

</paypageCredential>

</paypageCredentials>

</subMerchantRetrievalResponse>

PayFac API Transaction Examples Retrieve Allowed MCC List

74 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

3.11 Retrieve Allowed MCC List

You can retrieve the list of Merchant Category Codes, which are pre-approved for your use. When

on-boarding a new Sub-merchant, a Payment Service Provider should only use one of the

approved MCCs, appropriate to the Sub-merchant. To retrieve the allowed MCC list perform a

GET operation, specifying the legalEntityId with the parameter mcc. In the case of a request

to retrieve the allowed MCC list, the system does not require an accompanying XML message.

3.11.1 Retrieve MCC List Response

The structure of the response message is as follows:

<approvedMcc>Merchant Category Code</approvedMcc>

</approvedMCCResponse>

Example: Retrieve MCC List Response

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<approvedMccResponse

xmlns="http://payfac.vantivcnp.com/api/merchant/onboard">

NOTE:Should you anticipate the need for new or different MCCs beyond those

approved, please contact your Customer Experience Manager or our

Underwriting team for additional information.

TABLE 3-20 Resource Information

HTTP Methods GET

Call /mcc

Request Format XML

Response Format XML

Rate Limited Yes

Retrieve Allowed MCC List PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 75

PayFac API Reference Guide

...

</approvedMccs>

</approvedMccResponse>

PayFac API Transaction Examples Status Codes and Error Messages

76 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

3.12 Status Codes and Error Messages

The HTTP Status Codes provide information about the success or failure or a transaction. In the

case of a failure, an errorResponse message will contain additional information.

3.12.1 Error Response Message

The structure of the Error response message is as follows:

<error>Error Message</error>

</errors>

</errorresponse>

Example: Error Response - Status Code 400

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

TABLE 3-21 HTTP Status Codes

Code Description

200 Update/Retrieval/Disable is successful

201 Create call is successful

400 Invalid Request. For example:

•requested legal entity/sub merchant doesn't exist

•invalid field data (data is too long, required data is not sent)

•extra fields found in request

•attempt to create sub merchant for unapproved legal entity

The response message will contain more details.

401 Failed Authentication

500 Internal error. Vantiv is investigating the issue. Please contact Vantiv Customer

Support for additional information.

503 Returns for a soft decline or if the background checking service is unavailable.

For a soft decline, please verify the submitted information and retry. If the service

was unavailable, the Retry-After header contains a suggested retry time.

Status Codes and Error Messages PayFac API Transaction Examples

Document Version: 2.1 — API Release: 13.0 77

PayFac API Reference Guide

<error>Error in Request:Legal Entity [Entity Name] has not been

approved</error>

</errors>

</errorResponse>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<error>Error of [may not be null] on

[subMerchantCreateRequest.merchantCategoryCode]</error>

<error>Error of [size must be between 1 and 50] on

[subMerchantCreateRequest.merchantName]</error>

</errors>

</errorResponse>

Example: Error Response - Status Code 401

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<error>You are not authorized to access this resource. Please check your

credentials.</error>

</errors>

</errorResponse>

Example: error Response - Status Code 500

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<error>Internal Error. This error has already been escalated to Vantiv

for resolution. Please contact support with questions.</error>

</errors>

</errorResponse>

PayFac API Transaction Examples Status Codes and Error Messages

78 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

Document Version: 2.1 — API Release: 13.0 79

PAYFAC API XML ELEMENTS

This chapter provides definitions for the elements used in PayFac API. This information is

intended to assist you as you build the code necessary to submit messages creating and updating

Legal Entities and Sub-merchants. Each section defines a particular element, its relationship to

other elements (parents and children), as well as any attributes associated with the element.

For additional information on the structure of requests and responses using these elements, as

well as XML examples, please refer to Chapter 3, "PayFac API Transaction Examples".

The XML elements defined in this chapter appear alphabetically.

PayFac API XML Elements acceptanceDateTime

80 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.1 acceptanceDateTime

The acceptanceDateTime element is a required child of the legalEntityAgreement

element and defines date and time the party signing agreed to the Legal Entity Agreement.

Type = dateTime; Format = YYYY-MM-DDTHH:MM:SS+/-HH:MM

Parent Elements:

legalEntityAgreement

Attributes:

None

Child Elements:

None

NOTE:The +/-HH:MM portion of the dateTime format represents the offset from

UTC time. For example, for Boston the value would be -05:00, meaning

five hours behind UTC time.

address PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 81

PayFac API Reference Guide

4.2 address

The parent element of several address related child elements.

Parent Elements:

legalEntityCreateRequest, legalEntityUpdateRequest, principal, legalEntityRetrievalResponse,

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

streetAddress1, streetAddress2, city, stateProvince, postalCode, countryCode

Example: Address Structure

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 400</streetAddress2>

<city>Lowell</city>

</address>

NOTE:When you include the address element in a

legalEntityUpdateRequest message, you can not update the

countryCode child element.

PayFac API XML Elements addressVerified

82 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.3 addressVerified

The addressVerified element is an optional child of the verificationIndicators

element. A value of true indicates that the address was verified, while a value of false indicates

that the address could not be verified.

Type = Boolean; Allowed values = true or false

Parent Elements:

verificationIndicators

Attributes:

None

Child Elements:

None

agreements PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 83

PayFac API Reference Guide

4.4 agreements

The agreements element is an optional child of the

legalEntityAgreementRetrievalResponse message and contains a child element that

define the agreements associated with the Legal Entity designated in the request. If this element is

not returned in the response or is empty, the Legal Entity does not yet have any associated

agreements. If the Legal Entity has multiple associated agreements, there will be multiple

legalEntityAgreement child elements, one for each agreement.

Parent Elements:

legalEntityAgreementRetrievalResponse

Attributes:

None

Child Elements:

legalEntityAgreement

Example: agreements Structure

<legalEntityAgreementType>MERCHANT_AGREEMENT</legalEntityAgreementType>

<agreementVersion>Agreement Version Number</agreementVersion>

<userFullName>Full Name of Signer</userFullName>

<userSystemName>User Name of Signer of PayFac System</userSystemName>

<userIPAddress>IP Address of Signer’s system</userIPAdress>

<manuallyEntered>true or false</manuallyEntered>

<acceptanceDateTime>Date and Time Agreement Signed</acceptanceDateTime>

</legalEntityAgreement>

</agreements>

PayFac API XML Elements agreementVersion

84 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.5 agreementVersion

The agreementVersion element is a required child of the legalEntityAgreement element

and defines the version of Legal Entity Agreement.

Type = String; minLength = 1; maxLength = 50

Parent Elements:

legalEntityAgreement

Attributes:

None

Child Elements:

None

amexAcquired PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 85

PayFac API Reference Guide

4.6 amexAcquired

The amexAcquired element is an optional child of the subMerchantCreateRequest and

contains an attribute that indicates if the Sub-merchant is using the American Express Opt Blue

program. The element is also a child of the subMerchantUpdateRequest and the

subMerchantRetrievalResponse structures.

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

Child Elements:

None

Attribute Name Type Required? Description

enabled Boolean Yes Defines if Amex Opt Blue processing is enabled for

this sub-merchant. Valid values are either true or

false.

PayFac API XML Elements amexMid

86 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.7 amexMid

The amexMid element is an optional child of the subMerchantCreateRequest element and

specifies the American Express Merchant Id of the Sub-merchant. If you accept American

Express transactions, you must submit the Merchant Id provided by American Express.

Type = String; minLength = 1; maxLength = 15

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

NOTE:You must supply an American Express Merchant Id if you plan to process

American express payments.

amexSellerId PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 87

PayFac API Reference Guide

4.8 amexSellerId

The amexSellerId element is an optional child of the subMerchantCreateResponse and the

subMerchantRetrievalResponse elements. This value is the American Express Seller Id

assigned to the Sub-merchant. We return this value to you for your use when you communicate

Sub-merchant profile information to American Express. We also includes this information in

AmEx transactions, when we submit them for approval.

Type = String; minLength = N/A; maxLength = 32

Parent Elements:

subMerchantCreateResponse, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

NOTE:Use of the American Express Seller Id becomes mandatory in October of

2014.

PayFac API XML Elements annualCreditCardSalesVolume

88 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.9 annualCreditCardSalesVolume

The annualCreditCardSalesVolume element is a required child of the

legalEntityCreateRequest element and defines the approximate annual credit card sales

expected to be processed under this Legal Entity, in USD.

Type = Integer; minLength = 1; maxLength = 23

Parent Elements:

legalEntityCreateRequest, legalEntityRetrievalResponse, legalEntityUpdateRequest

Attributes:

None

Child Elements:

None

approvedMcc PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 89

PayFac API Reference Guide

4.10 approvedMcc

The approvedMcc element is a child of the approvedMccs element a defines an approved

Merchant Category Code for a Legal Entity/Sub-merchant.

Parent Elements:

approvedMccs

Attributes:

None

Child Elements:

None

PayFac API XML Elements approvedMccResponse

90 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.11 approvedMccResponse

The approvedMccResponse element is the parent element for the XML message returned by

the platform in response to a Approved MCC List retrieval request.

Parent Elements:

None

Attributes:

Child Elements:

transactionId, approvedMccs

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

approvedMccs PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 91

PayFac API Reference Guide

4.12 approvedMccs

The approvedMccs element is a required child of the approvedMccResponse message and

contains a child element that define the list of Merchant Category Codes approved for use with

Legal Entity/Sub-merchant.

Parent Elements:

approvedMccResponse

Attributes:

None

Child Elements:

approvedMcc

Example: approvedMccs Structure

...

</approvedMccs>

PayFac API XML Elements backgroundCheckDecisionNotes

92 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.13 backgroundCheckDecisionNotes

The backgroundCheckDecisionNotes element is an optional child of the

backgroundCheckResults element and provides additional information about the background

check preformed by us.

Type = String; minLength = N/A; maxLength = 2000

Parent Elements:

backgroundCheckResults

Attributes:

None

Child Elements:

None

NOTE:If the Legal Entity was declined after a manual review, this element will

contain information relating to the reason for the decline.

backgroundCheckFields PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 93

PayFac API Reference Guide

4.14 backgroundCheckFields

The backgroundCheckFields element has multiple uses in the schema. This element is an

optional child of the legalEntityUpdateRequest element, where it designates information

about the Legal Entity. The element is also an optional child of the principal element, where it

designates information about the Principal of the Legal Entity.

Parent Elements:

legalEntityResponse, principal

Attributes:

None

Child Elements (when used in legalEntityUpdateRequest):

All Optional: legalEntityName, legalEntityType, taxId

Example: backgroundCheckFields Structure when used in

legalEntityUpdateRequest

<legalEntityType>LIMITED_LIABILITY_COMPANY</legalEntityType>

</backgroundCheckFields>

Child Elements (when used in principal):

All Optional: firstName, lastName, ssn, dateOfBirth, driversLicense, driversLicenseState,

Example: backgroundCheckFields Structure when used in principal

</backgroundCheckFields>

PayFac API XML Elements backgroundCheckResults

94 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.15 backgroundCheckResults

The backgroundCheckResults element is an optional child of both the

legalEntityCreateResponse message and the legalEntityRetrievalResponse

message. It contains child elements that provide scores and other information from the

background checks performed by us.

Parent Elements:

legalEntityResponse, legalEntityRetrievalResponse

Attributes:

None

Child Elements:

business, principal, businessToPrincipalAssociation, backgroundCheckDecisionNotes,

bankruptcyData, lienResult

bankAccountNumber PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 95

PayFac API Reference Guide

4.16 bankAccountNumber

The bankAccountNumber element is a required child of the subMerchantCreateRequest

element and the subMerchantRetrievalResponse, where it specifies the account number of

the merchant account used to fund the Sub-merchant. The element is also an optional child of the

subMerchantUpdateRequest element.

Type = String; minLength = 1; maxLength = 50

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

NOTE:When returned in the submerchantRetrievalResponse, Vantiv masks

the first five characters of the bankAccountNumber, as shown in the

example below.

<bankAccountNumber>XXXXX-1234</bankAccountNumber>

PayFac API XML Elements bankRoutingNumber

96 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.17 bankRoutingNumber

The bankRoutingNumber element is a required child of the subMerchantCreateRequest

element and specifies the routing number of the merchant account used to fund the Sub-merchant.

The element is also an optional child of the subMerchantUpdateRequest element.

Type = String; minLength = 1; maxLength = 50

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

bankruptcyCount PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 97

PayFac API Reference Guide

4.18 bankruptcyCount

The bankruptcyCount element is an optional child of the bankruptcyData element and

specifies the count of bankruptcy records found.

Type = int; totalDigits = N/A

Parent Elements:

bankruptcyData

Attributes:

None

Child Elements:

None

PayFac API XML Elements bankruptcyData

98 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.19 bankruptcyData

The bankruptcyData element is an optional child of the backgroundCheckResults element.

It contains child elements that provides information about bankruptcy history of the company

from the background checks performed by us.

Parent Elements:

backgroundCheckResults

Attributes:

None

Child Elements:

bankruptcyType, bankruptcyCount, companyName, streetAddress1, streetAddress2, city, state,

zip, zip4, filingDate

Example: bankruptcyData Structure

<bankruptcyType>Sub-category of bankruptcy</bankruptcyType>

<companyName>Company Name</companyName>

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 2</streetAddress2>

<city>Boston</city>

</bankruptcyData>

bankruptcyType PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 99

PayFac API Reference Guide

4.20 bankruptcyType

The bankruptcyType element is an optional child of the bankruptcyData element and

specifies the sub-type of bankruptcy discovered during the background check process.

Type = String; minLength = N/A; maxLength = 50

Parent Elements:

bankruptcyData

Attributes:

None

Child Elements:

None

PayFac API XML Elements business

100 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.21 business

The business element is a child of the backgroundCheckResults element and contains

child elements providing the results of background checks performed on the Legal Entity.

Parent Elements:

backgroundCheckResults

Attributes:

None

Child Elements:

verificationResult

Example: business Structure

<score>Overall results for Business</score>

<description>Text Description of Score</description>

</overallScores>

<code>Name_Address_TIN_info</code>

<description>Text Description of Code</description>

</nameAddressTaxIdAssociation>

<code>Name_Address_Phone_info</code>

<description>Text Description of Code</description>

</nameAddressPhoneAssociation>

<nameVerified>true or false</nameVerified>

<addressVerified>true or false</addressVerified>

<cityVerified>true or false</cityVerified>

<zipVerified>true or false</zipVerified>

<phoneVerified>true or false</phoneVerified>

<taxIdVerified>true or false</taxIdVerified>

business PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 101

PayFac API Reference Guide

</verificationIndicators>

<code>Risk Indicator Info</code>

<description>Text Description of Code</description>

</riskIndicator>

</riskIndicators>

</verificationResult>

</business>

PayFac API XML Elements businessToPrincipalAssociation

102 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.22 businessToPrincipalAssociation

The businessToPrincipalAssociation element is an optional child of the

verificationResult element and contains child elements providing background check

information about how tightly coupled the principal is to the Legal Entity.

Parent Elements:

backgroundCheckResults

Attributes:

None

Child Elements:

score, description

Example: businessToPrincipalAssociation Structure

<score>Results for Business to Principal</score>

<description>Text Description of Score</description>

</businessToPrincipalAssociation>

city PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 103

PayFac API Reference Guide

4.23 city

The city element defines the city of either the Legal Entity, principal, or Sub-merchant. This

element is always required for a Legal Entity and is also required for a principal if the

legalEntityType is Sole Proprietorship. It is optional for all other legalEntityType values

and for Sub-merchants.

The city element is also an optional child of both the bankrupcyData and lienResults

elements, where it specifies the city of the company with bankruptcy or lien information.

Type = String; minLength = 1; maxLength = 20 (for address)

Type = String; minLength = 1; maxLength = 30 (for bankruptcyData or lienResult)

Parent Elements:

address, bankruptcyData, lienResult

Attributes:

None

Child Elements:

None

PayFac API XML Elements cityVerified

104 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.24 cityVerified

The cityVerified element is an optional child of the verificationIndicators element,

when verificationIndicators is a descendant of the business element. A value of true

indicates that the city (of the business) was verified, while a value of false indicates that the city

could not be verified.

Type = Boolean; Allowed values = true or false

Parent Elements:

verificationIndicators

Attributes:

None

Child Elements:

None

code PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 105

PayFac API Reference Guide

4.25 code

The code element is used in several locations and its meaning depends upon the parent element.

In each case the element value is selected from a set of enumerated values.

Type = String (Enum); minLength = N/A; maxLength = N/A

Parent Elements:

nameAddressPhoneAssociation, nameAddressTaxIdAssociation, riskIndicator,

nameAddressSsnAssociation,

Attributes:

None

Child Elements:

None

Enumerations (as a child of nameAddressTaxIdAssociation):

Enumerations (as a child of (business) nameAddressPhoneAssociation):

Enumeration Description

NOT_VERIFIED Supplied information could not be not verified.

WRONG_TAX_ID Supplied Tax Id is wrong.

NAME_OR_ADDRESS The name or the address is verified.

BAD_NAME The name as submitted can not be verified.

BAD_ADDRESS The address as submitted can not be verified.

MISSING_ADDRESS The address information is missing from the submitted

data.

NAME_AND_ADDRESS_BAD_TAX_ID Name and address verified; bad Tax Id

NAME_AND_ADDRESS_NO_TAX_ID Name and address verified; no Tax Id information

NAME_ADDRESS_TAX_ID Name, address, and Tax Id verified.

Enumeration Description

NOT_VERIFIED Supplied information could not be not verified.

PayFac API XML Elements code

106 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

Enumerations (as a child of nameAddressSsnAssociation):

WRONG_PHONE Supplied Phone number is wrong.

NAME_OR_ADDRESS The name or the address is verified.

BAD_NAME The name, as submitted, can not be verified.

BAD_ADDRESS The address, as submitted, can not be verified.

MISSING_ADDRESS The address information is missing from the submitted

data.

NAME_AND_ADDRESS_BAD_PHONE Name and address verified; bad phone number

NAME_AND_ADDRESS_NO_PHONE Name and address verified; no phone number submitted

NAME_ADDRESS_PHONE Name, address, and phone verified.

Enumeration Description

NOTHING Supplied information could not be not verified.

WRONG_SSN Supplied SSN is wrong.

FIRST_LAST First and last name verified

FIRST_ADDRESS First name and address.

FIRST_SSN First name and SSN verified.

LAST_ADDRESS Last name and address verified.

ADDRESS_SSN Address and SSN verified.

LAST_SSN Last name and SSN verified.

FIRST_LAST_ADDRESS First name, last name, and address verified.

FIRST_LAST_SSN First name, last name, and SSN verified.

FIRST_ADDRESS_SSN First name, address, and SSN verified.

LAST_ADDRESS_SSN Last name, address, and SSN verified.

FIRST_LAST_ADDRESS_SSN First name, last name, address, and SSN verified.

Enumeration Description

code PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 107

PayFac API Reference Guide

Enumerations (as a child of (principal) nameAddressPhoneAssociation):

Enumerations (as a child of riskIndicator):

Enumeration Description

NOTHING Supplied information could not be not verified.

WRONG_PHONE Supplied phone number is wrong.

FIRST_LAST First and last name verified

FIRST_ADDRESS First name and address.

FIRST_PHONE First name and phone number verified.

LAST_ADDRESS Last name and address verified.

ADDRESS_PHONE Address and phone number verified.

LAST_PHONE Last name and phone number verified.

FIRST_LAST_ADDRESS First name, last name, and address verified.

FIRST_LAST_PHONE First name, last name, and phone number verified.

FIRST_ADDRESS_PHONE First name, address, and phone number verified.

LAST_ADDRESS_PHONE Last name, address, and phone number verified.

FIRST_LAST_ADDRESS_PHONE First name, last name, address, and phone number

verified.

Enumeration Description

UNKNOWN Supplied information could not be not verified.

SSN_DECEASED The submitted SSN is reported as deceased.

SSN_PRIOR_TO_DOB The submitted SSN was issued prior the submitted DOB.

SSN_ADDRESS_PHONE_NOT_MATC

HThe submitted name and SSN have been verified, but the

address and phone do not match.

SSN_INVALID The submitted SSN is invalid.

PHONE_NUMBER_DISCONNECTED The submitted phone number may be disconnected.

PHONE_NUMBER_INVALID The submitted phone number is invalid.

PHONE_NUMBER_PAGER The submitted phone number is a pager number.

PHONE_NUMBER_MOBILE The submitted phone number is a mobile number.

PayFac API XML Elements code

108 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

ADDRESS_INVALID The submitted address may be invalid according to postal

specifications.

ZIP_BELONGS_POST_OFFICE The submitted zip code belongs to a post office box.

ADDRESS_INVALID_APARTMENT_D

ESIGNATION The submitted address has an invalid apartment designation.

ADDRESS_COMMERCIAL The submitted address is a transient commercial or

institutional address.

PHONE_NUMBER_COMMERCIAL The submitted phone number matches a transient

commercial or institutional address.

PHONE_NUMBER_ZIP_INVALID The submitted phone number and zip code combination is

invalid.

UNABLE_TO_VERIFY_NAS Unable to verify name, address, and SSN.

UNABLE_TO_VERIFY_ADDRESS Unable to verify address.

UNABLE_TO_VERIFY_SSN Unable to verify SSN.

UNABLE_TO_VERIFY_PHONE Unable to verify the phone number.

UNABLE_TO_VERIFY_DOB Unable to verify the date of birth.

SSN_MISKEYED The submitted SSN may have been miskeyed.

ADDRESS_MISKEYED The submitted address may have been miskeyed.

PHONE_NUMBER_MISKEYED The submitted phone number may have been miskeyed.

NUMBER_MATCHES_OFAC The submitted name matches the Office of Foreign Assets

Control (OFAC) file.

UNABLE_TO_VERIFY_NAME Unable to verify name.

SSN_MATCHES_MULTI_NAMES The SSN is associated with multiple last names.

SSN_RECENTLY_ISSUED The SSN is recently issued.

ZIP_CORPORATE_MILITARY The submitted zip code is a corporate-only, military zip code.

DLL_INVALID The submitted driver’s license number is invalid for the

submitted state.

NAME_ADDRESS_MATCH_BANKRU

PTCY The submitted name and address match a bankruptcy.

PHONE_AREA_CODE_CHANGING The submitted phone number area code is changing.

WORK_PHONE_PAGER The submitted work phone is a pager number.

UNABLE_TO_VERIFY_FIRST_NAME Unable to verify the first name.

Enumeration Description

code PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 109

PayFac API Reference Guide

PHONE_ADDRESS_DISTANT The submitted phone number and address are physically

distant (>10 miles).

ADDRESS_MATCHES_PRISON The submitted address match a prison address.

SSN_LAST_NAME_NO_MATCH The submitted last name does not associate with the

submitted SSN.

SSN_FIRST_NAME_NO_MATCH The submitted first name does not associate with the

submitted SSN.

WORK_HOME_PHONE_DISTANT The submitted home phone number and work phone number

are physically distant (>100 miles)

NAME_ADDRESS_TIN_MISMATCH The submitted business name and address match a Tax

Identification Number (TIN) different than the submitted TIN.

WORK_PHONE_INVALID The submitted work phone is potentially invalid.

WORK_PHONE_DISCONNECTED The submitted work phone is potentially disconnected.

WORK_PHONE_MOBILE The submitted work phone is a mobile number.

ADDRESS_RETURNS_DIFF_PHONE The submitted address returns a different phone number.

SSN_LNAME_NOT_MATCHED_FNAM

E_MATCHED The submitted SSN is associated with the same first name,

but a different last name.

PHONE_RESIDENTIAL_LISTING The submitted phone number is associated with a residential

listing.

SINGLE_FAMILY_DWELLING The submitted business address may be a residential

address (single-family dwelling).

SSN_NOT_FOUND The submitted SSN is not found in the public record.

SSN_BELONGS_TO_DIFF_NAME_AD

DRESS The submitted SSN is associated with a different name and

address.

PHONE_BELONGS_TO_DIFF_NAME

_ADDRESS The submitted phone number is associated with a different

name and address.

NAME_ADDRESS_UNLISTED The submitted name and address are associated with an

unlisted phone number.

NAME_MISKEYED The submitted name may have been miskeyed.

NAME_MISSING The name was missing.

ADDRESS_MISSING The address was missing.

SSN_MISSING The SSN was missing.

PHONE_NUMBER_MISSING The phone number was missing.

DOB_MISSING The date of birth was missing.

Enumeration Description

PayFac API XML Elements code

110 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

NAME_ADDRESS_RETURN_DIFF_P

HONE The submitted name and address return a different phone

number.

DOB_MISKEYED The submitted date of birthday have been miskeyed.

SSN_NON_US_CITIZEN The submitted SSN was issued to a non-US citizen.

ALTERNATE_BUSINESS_NAME_FOU

ND The submitted business name not found; alternate business

name found

DBA_MATCH_PUBLIC_RECORDS DBA name matched public records

SSN_RECENT The submitted SSN was issued in the last three years.

SSN_TOO_OLD The submitted SSN was issued after age five (post-1990).

TIN_NAME_ADDRESS_MISMATCH The submitted Tax Identification Number (TIN) is associated

with a different business name and address.

BUSINESS_NOT_IN_GOOD_STANDI

NG The submitted business is not in good standing per the

Secretary of State.

NAME_ADDRESS_MATCH_JUDGME

NT The submitted name and address match a judgement and/or

lien filing.

BUSINESS_INACTIVE The submitted business is inactive per the Secretary of

State.

NO_UPDATE_IN_LAST_THREE_YEA

RS No update to the business record in the last three years.

SSN_NOT_PRIMARY The submitted SSN is not the primary SSN for the submitted

identity.

ZIP_CORP_ONLY The submitted zip code is a corporate only zip code.

ADDRESS_MISMATCH The is an address mismatch between city/state and zip code.

DL_DIFFERENT A different driver’s license number was found for the

submitted applicant.

DL_NOT_FOUND The submitted driver’s license number was not found.

DL_MISKEYED The submitted driver’s license number may have been

miskeyed.

UNABLE_TO_VERIFY_DL Unable to verify the submitted driver’s license number.

SSN_INVALID_SSA The submitted SSN is possibly randomly issued by the SSA,

but invalid when first associated with the submitted identity.

SSN_IS_ITIN The submitted SSN is an Individual Taxpayer Identification

Number (ITIN).

SSN_MULTI_IDENTITY Multiple SSNs reported for applicant

Enumeration Description

code PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 111

PayFac API Reference Guide

ZIP_MILITARY The submitted zip code is a military only zip code.

MULTIPLE_SSN_FOUND Multiple SSNs reported for the applicant.

ADDRESS_DISCREPANCY Potential address discrepancy - the submitted address may

be a previous address.

ADDRESS_PO_BOX The primary submitted address is a P.O. Box.

SSN_RANDOM_SSA The submitted SSN is possibly randomly issued by the SSA.

ADDRESS_MISMATCH_SECONDARY Address mismatch on secondary address range.

NAME_MATCHES_NON_OFAC The submitted name matches one or more of the non-OFAC

global watchlist.

UNABLE_TO_VERIFY_ZIP_CODE Unable to verify zip code.

IP_ADDRESS_UNKNOWN The submitted IP Address is unknown.

IP_ADDRESS_DIFFERENT_STATE The submitted IP Address is assigned to a different State

than the Bill-To state.

IP_ADDRESS_DIFFERENT_ZIP The submitted IP Address is assigned to a different zip code

than the Bill-To zip code.

IP_ADDRESS_DIFFERENT_PHONE The submitted IP Address is assigned to a different area

code than the Bill-To phone number.

IP_ADDRESS_DOMAIN_UNKNOWN The submitted IP Address second level domain is unknown.

IP_ADDRESS_NOT_ASSIGNED_TO_

USA The submitted IP Address is not assigned to the United

States.

IP_ADDRESS_NON_ROUTABLE The submitted IP Address is non-routable over the internet.

Enumeration Description

PayFac API XML Elements companyName

112 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.26 companyName

The companyName element is an optional child of both the lienResult and bankruptcyData

elements and specifies the name of the company to which the lien or bankruptcy information

applies.

Type = String; minLength = 1; maxLength = 120

Parent Elements:

bankruptcyData, lienResult

Attributes:

None

Child Elements:

None

contactPhone PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 113

PayFac API Reference Guide

4.27 contactPhone

The contactPhone element is an optional child of the legalEntityCreateRequest,

legalEntityUpdateRequest, and the principal elements, as well as the

legalEntityRetrievalResponse. It defines the contact phone number for the parent

element.

Type = String; minLength = 1; maxLength = 10

Parent Elements:

legalEntityCreateRequest, principal, legalEntityUpdateRequest, legalEntityRetrievalResponse

Attributes:

None

Child Elements:

None

PayFac API XML Elements countryCode

114 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.28 countryCode

The countryCode element is a required child of the address element that defines the country

of either the Legal Entity, the principal, or Sub-merchant.

Type = String; minLength = 2; maxLength = 3

Parent Elements:

address

Attributes:

None

Child Elements:

None

createCredentials PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 115

PayFac API Reference Guide

4.29 createCredentials

The createCredentials element is an optional child of the submerchantCreateRequest

element and indicates if the system should create login credentials (username, password, and

paypageId, if necessary) for this Sub-merchant. Submit a value of true with each

subMerchantCreateRequest, only if each Sub-merchant requires individual credentials for

transaction submission.

Type = Boolean; Possible Values = true or false

Parent Elements:

subMerchantCreateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

PayFac API XML Elements credentials

116 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.30 credentials

The credentials element is an optional child of the subMerchantCreateResponse element

and contains child elements that define the username and password for use by the

sub-merchant, as well as the expiration date of the password.

Parent Elements:

subMerchantCreateResponse, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

userName, password, passwordExpirationDate

Example: credentials

<userName>UserName</userName>

<password>Password</password>

<passwordExpirationDate>YYYY-MM-DDTHH:MM:SS+/-HH:MM</passwordExpirationDate>

</credentials>

customerServiceNumber PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 117

PayFac API Reference Guide

4.31 customerServiceNumber

The customerServiceNumber element is a required child of the

subMerchantCreateRequest element and specifies the customer service phone number of the

Sub-merchant. It is also a child of the subMerchantUpdateRequest and the

subMerchantRetrievalResponse.

Type = String; minLength = 1; maxLength = 13

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

PayFac API XML Elements dateOfBirth

118 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.32 dateOfBirth

The dateOfBirth element is a required child of the principal element and specifies the date

of birth of the principal.

Type = Date; Format = yyyy-mm-dd

Parent Elements:

principal

Attributes:

None

Child Elements:

None

decisionDate PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 119

PayFac API Reference Guide

4.33 decisionDate

The decisionDate element is and optional child of the legalEntityRetrievalResponse

element. The value represents the date/time a decision was made for a Legal Entity that was in

manual review. This element is returned only for Legal Entities that underwent manual review.

Type = dateTime; Format = YYYY-MM-DDTHH:MM:SS+/-HH:MM

Parent Elements:

legalEntityRetrievalResponse

Attributes:

None

Child Elements:

None

NOTE:The +/-HH:MM portion of the dateTime format represents the offset from

UTC time. For example, for Boston the value would be -05:00 (or -04:00

depending upon daylight savings time), meaning five hours behind UTC

time.

PayFac API XML Elements description

120 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.34 description

The description element is a child of multiple elements and provides a text description of the

accompanying code or score.

Type = String; minLength = N/A; maxLength = varies from 60 to 200 depending upon parent

Parent Elements:

overallScore, nameAddressTaxIdAssociation, nameAddressPhoneAssociation, riskIndicator,

nameAddressSsnAssociation, businessToPrincipalAssociation

Attributes:

None

Child Elements:

None

disable PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 121

PayFac API Reference Guide

4.35 disable

The disable element is an optional child of the subMerchantUpdateRequest element and

allows you to disable an existing Sub-merchant. A value of true indicates that you want to

changes the status of the Sub-merchant to disabled. The default value is false.

Type = Boolean; Allowed values = true or false

Parent Elements:

subMerchantUpdateRequest

Attributes:

None

Child Elements:

None

PayFac API XML Elements disabled

122 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.36 disabled

The disabled element is an optional child of the subMerchantRetrievalResponse element

and indicates the status of the Sub-merchant. A value of true indicates that the Sub-merchant is

currently disabled, while a value of false indicates that the Sub-merchant is enabled.

Type = Boolean; Allowed values = true or false

Parent Elements:

subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

discoverConveyedMid PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 123

PayFac API Reference Guide

4.37 discoverConveyedMid

The discoverConveyedMid element is an optional child of the

subMerchantCreateRequest element and specifies the Discover Merchant Id of the

Sub-merchant.

Type = String; minLength = 1; maxLength = 15

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

NOTE:If you have a direct relationship and are funded by Discover for Discover

transaction, then you are a Discover conveyed merchant and for proper

processing, must supply the merchant ID assigned to you by Discover.

PayFac API XML Elements dobVerified

124 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.38 dobVerified

The dobVerified element is an optional child of the verificationIndicators element,

when verificationIndicator is a descendant of the principal element. A value of true

indicates that the Date of Birth of the principal was verified, while a value of false indicates that

the DOB could not be verified.

Type = Boolean; Allowed values = true or false

Parent Elements:

verificationIndicators

Attributes:

None

Child Elements:

None

doingBusinessAs PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 125

PayFac API Reference Guide

4.39 doingBusinessAs

The doingBusinessAs element is an optional child of the legalEntityCreateRequest

element and specifies an alternate name of the Legal Entity.

Type = String; minLength = 1; maxLength = 60

Parent Elements:

legalEntityCreateRequest, legalEntityUpdateRequest

Attributes:

None

Child Elements:

None

PayFac API XML Elements driversLicense

126 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.40 driversLicense

The driversLicense element is an optional child of the principal element and specifies the

driver’s license number of the principal.

Type = String; minLength = 1; maxLength = 25

Parent Elements:

principal

Attributes:

None

Child Elements:

None

driversLicenseState PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 127

PayFac API Reference Guide

4.41 driversLicenseState

The driversLicenseState element is an optional child of the principal element and

specifies the state that issued the driver’s license of the principal.

Type = String; minLength = 1; maxLength = 2

Parent Elements:

principal

Attributes:

None

Child Elements:

None

PayFac API XML Elements eCheck

128 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.42 eCheck

The eCheck element is an optional child of the subMerchantCreateRequest and contains

child elements that define the eCheckCompanyName and eCheckBillingDescriptor.

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

Child Elements:

eCheckBillingDescriptor, eCheckCompanyName

Example: eCheck Structure

<eCheckCompanyName>ABA Company</eCheckCompanyName>

</eCheck>

Attribute Name Type Required? Description

enabled Boolean Yes Defines if eCheck processing is enabled for this

merchant. Valid values are either true or false.

eCheckBillingDescriptor PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 129

PayFac API Reference Guide

4.43 eCheckBillingDescriptor

The eCheckBillingDescriptor element is an optional child of the

subMerchantCreateRequest, and the subMerchantUpdateRequest elements. It specifies

the Billing Descriptor used for eCheck Transaction. You should specify this element when the

Sub-Merchant is enabled for eCheck transaction.

Type = String; minLength = 1; maxLength = 10

Parent Elements:

eCheck

Attributes:

None

Child Elements:

None

NOTE:Typically, you use this field to submit the company phone number. You

use the eCheckCompanyName field to submit the company name, which

is the equivalent of a Billing Descriptor on a credit card transaction.

PayFac API XML Elements eCheckCompanyName

130 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.44 eCheckCompanyName

The eCheckCompanyName element is an optional child of the subMerchantCreateRequest

and the subMerchantUpdateRequest elements. It specifies the Company Name used for

eCheck Transaction. You should specify this element when the Sub-Merchant is enabled for

eCheck transaction.

Type = String; minLength = 1; maxLength = 16

Parent Elements:

eCheck

Attributes:

None

Child Elements:

None

emailAddress PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 131

PayFac API Reference Guide

4.45 emailAddress

The emailAddress element is an optional child of both the principal and

legalEntityPrincipalUpdatable elements, where it specifies the email address of the

principal, and a required child of the primaryContact element, where it specifies the email

address of the Sub-merchant’s primary contact.

Type = String; minLength = 1; maxLength = 100

Parent Elements:

principal, primaryContact

Attributes:

None

Child Elements:

None

PayFac API XML Elements error

132 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.46 error

The error element is a child of the errors element and is a text description of the error

preventing the processing of the transaction.

Type = String; minLength = N/A; maxLength = 512

Parent Elements:

errors

Attributes:

None

Child Elements:

None

errorResponse PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 133

PayFac API Reference Guide

4.47 errorResponse

The errorResponse element is the parent element for the XML message returned by the

platform for a transaction that the system cannot process due to a validation, authentication, or

communication error.

Parent Elements:

None

Attributes:

Child Elements:

transactionId, errors

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

PayFac API XML Elements errors

134 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.48 errors

The errors element is a child of the errorResponse element and through its child, error,

provides a text description of the error preventing the processing of the transaction.

Parent Elements:

errorResponse

Attributes:

None

Child Elements:

error

feeProfile PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 135

PayFac API Reference Guide

4.49 feeProfile

The feeProfile element is an optional child of the subMerchantFunding element and

defines the Fee Profile used for Sub-merchant fund disbursements using Managed Payout.

Type = String; minLength = 1; maxLength = 150

Parent Elements:

subMerchantFunding

Attributes:

None

Child Elements:

None

NOTE:You must create the Fee Profiles using the PayFac Portal.

PayFac API XML Elements filingDate

136 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.50 filingDate

The filingDate element is an optional child of both the bankruptcyData element and the

lienResult element. It specifies the date of either the most recent lien or most recent

bankruptcy filing, depending upon where used.

Type = Date; Format = yyyy-mm-dd

Parent Elements:

bankruptcyData, lienResult

Attributes:

None

Child Elements:

None

firstName PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 137

PayFac API Reference Guide

4.51 firstName

The firstName element is a required child of both the principal element, where it specifies

the first name of the principal, and the primaryContact element, where it specifies the first

name of the Sub-merchant’s primary contact.

Type = String; minLength = 1; maxLength = 20

Parent Elements:

principal, primaryContact, legalEntityPrincipalCreateResponse

Attributes:

None

Child Elements:

None

PayFac API XML Elements fraud

138 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.52 fraud

The fraud element is an optional child of both the subMerchantCreateRequest and the

subMerchantUpdateRequest. It defines whether fraud filters are enabled for the

Sub-merchant.

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

Child Elements:

None

Attribute Name Type Required? Description

enabled Boolean Yes Defines if fraud Filters are enabled for this

Sub-merchant. Valid values are either true or false.

fundingSubmerchantId PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 139

PayFac API Reference Guide

4.53 fundingSubmerchantId

The fundingSubmerchantId element is an optional child of the subMerchantFunding

element (required if you use Dynamic Payout) and specifies the funding Id used to identify the

Sub-merchant in funding instructions. (Also see, Retrieve Sub-Merchant on page 70)

Type = String; minLength = 1; maxLength = 32

Parent Elements:

subMerchantFunding

Attributes:

None

Child Elements:

None

IMPORTANT:If you are processing transactions on both the Vantiv Core and Vantiv

eCommerce platforms, submit the Sub-merchant Id provided for use on

the Vantiv Core platform.

If you are processing transactions only on the Vantiv eCommerce

platform, submit a value of AUTO_GENERATE. To retrieve the

fundingSubmerchantId value for use in Funding Instructions, submit a

Sub-merchant Retrieval Request. (Please refer to the Vantiv cnpAPI

Reference Guide for additional information about Funding Instructions.)

PayFac API XML Elements hardCodedBillingDescriptor

140 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.54 hardCodedBillingDescriptor

The hardCodedBillingDescriptor element is a required child of the

subMerchantCreateRequest element and specifies the Billing descriptor that will be

hard-coded into the profile of the Sub-merchant. This default value appears on the customer’s

billing statement unless overridden by the submission of a soft billing descriptor in the

Authorization/Sale transaction.

Type = String; minLength = 1; maxLength = 25

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

IMPORTANT:If the PayFac is configured with a forced prefix, the

hardCodedBillingDescriptor value you submit for the Sub-merchant

must include the prefix.

hasAcceptedCreditCards PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 141

PayFac API Reference Guide

4.55 hasAcceptedCreditCards

The hasAcceptedCreditCards element is a required child of the

legalEntityCreateRequest element and indicates if this Legal Entity has accepted credit

cards in the past.

Type = Boolean; Possible Values = true or false

Parent Elements:

legalEntityCreateRequest, legalEntityRetrievalResponse, legalEntityUpdateRequest

Attributes:

None

Child Elements:

None

PayFac API XML Elements lastName

142 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.56 lastName

The lastName element is a required child of both the principal element, where it specifies the

last name (surname) of the principal, and the primaryContact element, where it specifies the

last name (surname) of the Sub-merchant’s primary contact.

Type = String; minLength = 1; maxLength = 20

Parent Elements:

principal, primaryContact, legalEntityPrincipalCreateResponse

Attributes:

None

Child Elements:

None

legalEntityAgreement PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 143

PayFac API Reference Guide

4.57 legalEntityAgreement

The legalEntityAgreement element is a required child of the

legalEntityAgreementCreateRequest and contains child elements that provide

information about the Legal Entity Agreement. It is also an optional child of the agreements

element, where it provides information about agreements associated with the designated Legal

Entity in a Legal Entity Agreement Retrieval request. You should use this transaction type only if

your PayFac Account Manager directs you to do so.

Parent Elements:

legalEntityAgreementCreateRequest, agreements

Attributes:

None

Child Elements:

Required: legalEntityAgreementType, agreementVersion, userFullName, userSystemName,

acceptanceDateTime

Optional: userIPAddress, manuallyEntered,

Example: legalEntityAgreement Structure

<legalEntityAgreementType>MERCHANT_AGREEMENT</legalEntityAgreementType>

<agreementVersion>Agreement Version Number</agreementVersion>

<userFullName>Full Name of Signer</userFullName>

<userSystemName>User Name of Signer of PayFac System</userSystemName>

<userIPAddress>IP Address of Signer’s system</userIPAdress>

<manuallyEntered>true or false</manuallyEntered>

<acceptanceDateTime>Date and Time Agreement Signed</acceptanceDateTime>

</legalEntityAgreement>

PayFac API XML Elements legalEntityAgreementCreateRequest

144 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.58 legalEntityAgreementCreateRequest

The legalEntityAgreementCreateRequest element is the parent element for the XML

message used to create a Legal Entity Agreement. You should use this transaction type only if

your PayFac Account Manager directs you to do so.

Parent Elements:

None

Attributes:

Child Elements:

Required: legalEntityAgreement

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

legalEntityAgreementCreateResponse PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 145

PayFac API Reference Guide

4.59 legalEntityAgreementCreateResponse

The legalEntityAgreementCreateResponse element is the parent element for the XML

message returned by the platform in response to a successful (or duplicate)

legalEntityAgreementCreateRequest message.

Parent Elements:

None

Attributes:

Child Elements:

Required: transactionId

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

duplicate Boolean No Appears in the response message only if the

legalEntityAgreementCreateRequest was a

duplicate request.

Allowed values = true or false

PayFac API XML Elements legalEntityAgreementRetrievalResponse

146 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.60 legalEntityAgreementRetrievalResponse

The legalEntityAgreementRetrievalResponse element is the parent element for the

XML message returned by the platform in response to a Legal Entity Agreement Retrieval

request.

Parent Elements:

None

Attributes:

Child Elements:

legalEntityId, transactionId, agreements

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

legalEntityAgreementType PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 147

PayFac API Reference Guide

4.61 legalEntityAgreementType

The legalEntityAgreementType element is a required child of the

legalEntityAgreement element and defines the type of Legal Entity Agreement. At this

time, the only valid value is MERCHANT_AGREEMENT.

Type = String (Enum); minLength = N/A; maxLength = N/A

Parent Elements:

legalEntityAgreement

Attributes:

None

Child Elements:

None

PayFac API XML Elements legalEntityCreateRequest

148 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.62 legalEntityCreateRequest

The legalEntityCreateRequest element is the parent element for the XML message used to

create a Legal Entity. You must create a Legal Entity prior to adding Sub-merchants controlled by

the entity.

Parent Elements:

None

Attributes:

Child Elements:

Always Required: legalEntityName, legalEntityType, taxId, annualCreditCardSalesVolume,

hasAcceptedCreditCards, address (some child elements may be optional), principal

Required/Optional (depending upon if using PayFac Assurance model): yearsInBusiness

Optional: doingBusinessAs, contactPhone

NOTE:When creating a Legal Entity, you must define the controlling Principal of

the Legal Entity. Use the legalEntityPrincipalCreateRequest (see

Create Create a Principal on page 54) to add all other Principal with a 10%

or greater ownership of the Legal Entity.

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

legalEntityCreateResponse PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 149

PayFac API Reference Guide

4.63 legalEntityCreateResponse

The legalEntityResponse element is the parent element for the XML message returned by

the platform in response to a legalEntityCreateRequest message.

Parent Elements:

None

Attributes:

Child Elements:

Always Required: transactionId

Optional: legalEntityId, pspMerchantId, responseCode, responseDescription,

backgroundCheckResults, originalSubMerchant

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

duplicate Boolean No Appears in the response message only if the

legalEntityCreateRequest was a duplicate

request.

Allowed values = true or false

PayFac API XML Elements legalEntityId

150 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.64 legalEntityId

The legalEntityId element is a required child of the legalEntityResponse element and is

a system generated identifier for the Legal Entity.

Type = String; minLength = 1; maxLength = 19

Parent Elements:

legalEntityResponse, legalEntityRetrievalResponse, legalEntityResponse

Attributes:

None

Child Elements:

None

legalEntityName PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 151

PayFac API Reference Guide

4.65 legalEntityName

The legalEntityName element is a required child of the legalEntityCreateRequest

element and defines the name of the Legal Entity controlling the Sub-merchants.

Type = String; minLength = 1; maxLength = 60

Parent Elements:

legalEntityCreateRequest, legalEntityRetrievalResponse

Attributes:

None

Child Elements:

None

PayFac API XML Elements legalEntityOwnershipType

152 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.66 legalEntityOwnershipType

The legalEntityOwnershipType element is a required child of the

legalEntityCreateRequest and the legalEntityUpdateRequest where it defines

whether the Legal Entity is Public or Private.

Type = String (Enum); Valid Values = PUBLIC or PRIVATE

Parent Elements:

legalEntityCreateRequest, legalEntityUpdateRequest

Attributes:

None

Child Elements:

None

NOTE:If the legalEntityType is either TAX_EXEMPT_ORGANIZATION or

GOVERNMENT_AGENCY, you must set the legalEntityOwnershipType

to PUBLIC.

legalEntityPrincipalCreateRequest PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 153

PayFac API Reference Guide

4.67 legalEntityPrincipalCreateRequest

The legalEntityPrincipalCreateRequest element is the parent element for the XML

message used to create a Legal Entity Principal. You must create a Principal record for each

individual holding a 10% or greater stake in the Legal Entity.

Parent Elements:

None

Attributes:

Child Elements:

Required: principal

NOTE:When creating a Legal Entity, you must define the controlling Principal of

the Legal Entity.

If the legalEntityType is SOLE_PROPRIETORSHIP, you cannot add or

delete Principals.

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

PayFac API XML Elements legalEntityPrincipalCreateResponse

154 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.68 legalEntityPrincipalCreateResponse

The legalEntityPrincipalCreateResponse element is the parent element for the XML

message returned by the platform in response to a Legal Entity Principal Create Request.

Parent Elements:

None

Attributes:

Child Elements:

transactionId, principalId, firstName, lastName, backgroundCheckResults

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

duplicate String No Appears in the response message only if the

legalEntityUpdateRequest was a duplicate

request.

Allowed values = true or false

legalEntityPrincipalDeleteResponse PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 155

PayFac API Reference Guide

4.69 legalEntityPrincipalDeleteResponse

The legalEntityPrincipalDeleteResponse is the parent element for the XML message returned by

the platform in response to a Legal Entity Principal Delete request.

Parent Elements:

None

Attributes:

Child Elements:

transactionId, legalEntityId, principalId, responseDescription

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

PayFac API XML Elements legalEntityPrincipalUpdatable

156 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.70 legalEntityPrincipalUpdatable

The legalEntityPrincipalUpdatable element is the parent element for the XML message

used to update a Legal Entity Principal. Using this transaction type, you can update the following

Legal Entity items:

Parent Elements:

None

Attributes:

Child Elements:

Optional: emailAddress, contactPhone, address, backgroundCheckFields

•contactPhone •stateProvince

•streetAddress1 •postalCode

•streetAddress2 •emailAddress

•city

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

legalEntityResponse PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 157

PayFac API Reference Guide

4.71 legalEntityResponse

The legalEntityResponse element is the parent element for the XML message returned by

the platform in response to a Legal Entity Update request.

Parent Elements:

None

Attributes:

Child Elements:

transactionId, legalEntityId, responseCode, responseDescription, backgroundCheckResults

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

duplicate String No Appears in the response message only if the

legalEntityUpdateRequest was a duplicate

request.

Allowed values = true or false

PayFac API XML Elements legalEntityRetrievalResponse

158 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.72 legalEntityRetrievalResponse

The legalEntityRetrievalResponse element is the parent element for the XML message

returned by the platform in response to a Legal Entity retrieval request.

Parent Elements:

None

Attributes:

Child Elements:

legalEntityName, legalEntityType, taxId, annualCreditCardSalesVolume,

hasAcceptedCreditCards, address, legalEntityId, responseCode, responseDescription,

backgroundCheckResults, transactionId, updateDate, decisionDate, tinValidationStatus,

sub_merchant_processing_status

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

overallStatus String Yes Defines the overall status of the Legal Entity.

minLength = 1 maxLength = 100

legalEntityType PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 159

PayFac API Reference Guide

4.73 legalEntityType

The legalEntityType element is a required child of the legalEntityCreateRequest

element and defines the business type of the Legal Entity.

Type = String (enum); minLength = N/A; maxLength = N/A

Parent Elements:

legalEntityCreateRequest, legalEntityRetrievalResponse

Attributes:

None

Child Elements:

None

Enumerations:

Enumeration

INDIVIDUAL_SOLE_PROPRIETORSHIP

CORPORATION

LIMITED_LIABILITY_COMPANY

PARTNERSHIP

LIMITED_PARTNERSHIP

GENERAL_PARTNERSHIP

TAX_EXEMPT_ORGANIZATION

GOVERNMENT_AGENCY

NOTE:All Legal Entity Type are available for use by Canadian based Legal

Entities; however, LIMITED_PARTNERSHIP and GENERAL_PARTNERSHIP

will be deprecated in a future release, so you should avoid their use.

PayFac API XML Elements legalEntityUpdateRequest

160 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.74 legalEntityUpdateRequest

The legalEntityUpdateRequest element is the parent element for the XML message used to

update a Legal Entity. Using this transaction type, you can update the following Legal Entity

items:

Parent Elements:

None

Attributes:

Child Elements:

Optional: address, contactPhone, doingBusinessAs, annualCreditCardSalesVolume,

hasAcceptedCreditCards, principal, backgroundCheckFields

•streetAddress1 (entity and/or principal) •lastName (principal)

•streetAddress2 (entity and/or principal) •ssn (principal)

•city (entity and/or principal) •dateOfBirth (principal)

•stateProvince (entity and/or principal) •driversLicense (principal)

•postalCode (entity and/or principal) •driversLicenseState (principal)

•doingBusinessAs •legalEntityName

•annualCreditCardSalesVolume •legalEntityType

•hasAcceptedCreditCards •taxId

•firstName (principal)

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and you must specify it as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

lienResult PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 161

PayFac API Reference Guide

4.75 lienResult

The lienResult element is an optional child of the backgroundCheckResults element. It

contains child elements that provides information about the lien history of the company from the

background checks performed by us.

Parent Elements:

backgroundCheckResults

Attributes:

None

Child Elements:

lienType, releasedCount, unreleasedCount, companyName, streetAddress1, streetAddress2, city,

state, zip, zip4, filingDate

Example: lienResult Structure

<lienyType>Subtype of Lien</lienyType>

<companyName>Company Name</companyName>

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 2</streetAddress2>

<city>Boston</city>

</lienResult>

PayFac API XML Elements lienType

162 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.76 lienType

The lienType element is an optional child of the lienResult element and specifies the

sub-type of lien discovered during the background check process.

Type = String; minLength = 1; maxLength = 50

Parent Elements:

lienResult

Attributes:

None

Child Elements:

None

manuallyEntered PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 163

PayFac API Reference Guide

4.77 manuallyEntered

The manuallyEntered element is a required child of the legalEntityAgreement element

and defines whether information about the party signing the Legal Entity Agreement was entered

manually or electronically. When this element is set to false, you must include a value for the

userIPAddress element. When this element is set to true, the userIPAddress element is

optional.

Type = boolean; Allowed Values = true or false

Parent Elements:

legalEntityAgreement

Attributes:

None

Child Elements:

None

PayFac API XML Elements maxTransactionAmount

164 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.78 maxTransactionAmount

The maxTransactionAmount element is a required child of the

subMerchantCreateRequest element and specifies the maximum transaction amount (in the

purchase currency) allowed on a single transaction submitted by the Sub-merchant. Supply the

value in dollars without a decimal point. For example, a value of 50000 signifies $50,000.

Type = Long; minLength = N/A; maxLength = 12

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

merchantCategoryCode PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 165

PayFac API Reference Guide

4.79 merchantCategoryCode

The merchantCategoryCode element is a required child of the

subMerchantCreateRequest element and specifies the Merchant Category Code of the

Sub-merchant.

Type = String; minLength = 1; maxLength = 4

Parent Elements:

subMerchantCreateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

PayFac API XML Elements merchantIdentString

166 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.80 merchantIdentString

The merchantIdentString element is a required child of the

subMerchantCreateResponse element and is a system generated merchant identifier required

to process transactions for this Sub-merchant. It is also returned as a child of both the

originalSubMerchant and subMerchantRetrievalResponse elements.

Type = String; minLength = 1; maxLength = 50

Parent Elements:

subMerchantCreateResponse, originalSubMerchant, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

NOTE:This value is the unique string used to identify the merchant when

submitting payment transactions to our system. In the cnpAPI used for

payment transactions, it is the merchantId attribute used in the

batchRequest, batchResponse, and cnpOnlineRequest.

merchantName PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 167

PayFac API Reference Guide

4.81 merchantName

The merchantName element is a required child of the subMerchantCreateRequest element

and specifies the name of the Sub-merchant.

Type = String; minLength = 1; maxLength = 50

Parent Elements:

subMerchantCreateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

PayFac API XML Elements nameAddressPhoneAssociation

168 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.82 nameAddressPhoneAssociation

The nameAddressPhoneAssocaition element is an optional child of the

verificationResult element and contains child elements providing the results of background

checks performed on the Legal Entity that indicate how tightly coupled the name is to the phone

number and address provided.

Parent Elements:

verificationResult

Attributes:

None

Child Elements:

code, description

Example: nameAddressPhoneAssociation Structure

<code>Name_Address_Phone_info</code>

<description>Text Description of Code</description>

</nameAddressPhoneAssociation>

nameAddressSsnAssociation PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 169

PayFac API Reference Guide

4.83 nameAddressSsnAssociation

The nameaddressSsnAssociation element is an optional child of the

verificationResult element and contains child elements providing the results of background

checks performed on the Legal Entity that indicate how tightly coupled the name is to the SSN

and address provided.

Parent Elements:

verificationResult

Attributes:

None

Child Elements:

code, description

Example: nameAddressTaxIdAssociation Structure

<code>Name_Address_SSN_info</code>

<description>Text Description of Code</description>

</nameAddressSsnAssociation>

PayFac API XML Elements nameAddressTaxIdAssociation

170 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.84 nameAddressTaxIdAssociation

The nameaddressTaxIdAssociation element is an optional child of the

verificationResult element and contains child elements providing the results of background

checks performed on the Legal Entity that indicate how tightly coupled the name is to the Tax Id

and address provided.

Parent Elements:

verificationResult

Attributes:

None

Child Elements:

code, description

Example: nameAddressTaxIdAssociation Structure

<code>Name_Address_TIN_info</code>

<description>Text Description of Code</description>

</nameAddressTaxIdAssociation>

nameVerified PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 171

PayFac API Reference Guide

4.85 nameVerified

The nameVerified element is an optional child of the verificationIndicators element. A

value of true indicates that the name of the principal or business was verified, while a value of

false indicates that the name could not be verified.

Type = Boolean; Allowed values = true or false

Parent Elements:

verificationIndicators

Attributes:

None

Child Elements:

None

PayFac API XML Elements originalLegalEntityId

172 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.86 originalLegalEntityId

The originalLegalEntityId element is an optional child of the

legalEntityCreateResponse, returned when the legalEntityCreateRequest is a

duplicate. The value indicates the Legal Entity ID of the original Legal Entity.

Type = String; minLength = 1; maxLength = 19

Parent Elements:

legalEntityCreateResponse

Attributes:

None

Child Elements:

None

originalLegalEntityStatus PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 173

PayFac API Reference Guide

4.87 originalLegalEntityStatus

The originalLegalEntityStatus element is an optional child of the

legalEntityCreateResponse, returned when the legalEntityCreateRequest is a

duplicate. The value indicates the status of the Legal Entity.

Type = String; minLength = 1; maxLength = 100

Parent Elements:

legalEntityCreateResponse

Attributes:

None

Child Elements:

None

PayFac API XML Elements originalSubMerchant

174 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.88 originalSubMerchant

The originalSubMerchant element is optional child of the subMerchantCreateResponse

message. This element and its children are returned only if the system has determined the

subMerchantCreateRequest is a duplicate and provides the information from the creation of the

original Sub-merchant.

Parent Elements:

subMerchantCreateResponse

Attributes:

None

Child Elements:

address, disabled, bankAccountNumber, bankRoutingNumber, customerServiceNumber,

amexMid, discoverConveyedMid, hardCodedBillingDescriptor, maxTransactionAmount,

merchantCategoryCode, merchantName, url, subMerchantId, transactionId, merchantIdentString

overallScore PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 175

PayFac API Reference Guide

4.89 overallScore

The overallScore element is an optional child of the verificationResult element and

contains child elements providing the results of background checks performed on the Legal

Entity.

Parent Elements:

verificationResult

Attributes:

None

Child Elements:

score, description

Example: overallScore Structure

<score>Overall results for Business</score>

<description>Text Description of Score</description>

</overallScore>

PayFac API XML Elements password

176 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.90 password

The password element is a required child of the credentials element and specifies the

password portion of the authentication credentials used to submit transaction to the production

environment.

Type = String; minLength = 1; maxLength = 72

Parent Elements:

credentials

Attributes:

None

Child Elements:

None

passwordExpirationDate PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 177

PayFac API Reference Guide

4.91 passwordExpirationDate

The passwordExpirationDate is an optional of the credentials element that specifies the

expiration date of the provided password.

Type = dateTime; Format = YYYY-MM-DDTHH:MM:SS+/-HH:MM

Parent Elements:

credentials

Attributes:

None

Child Elements:

None

NOTE:The +/-HH:MM portion of the dateTime format represents the offset from

UTC time. For example, for Boston the value would be -05:00, meaning

five hours behind UTC time.

PayFac API XML Elements paypageCredential

178 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.92 paypageCredential

The paypageCredential element is a required child of the paypageCredentials element

and contains child elements that define the paypageId and associated userName used to submit

card info via the PayPage application.

Parent Elements:

paypageCredentials

Attributes:

None

Child Elements (required):

userName, paypageId

Example: paypageCredential Structure

<userName>UserName</userName>

</paypageCredentials>

paypageCredentials PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 179

PayFac API Reference Guide

4.93 paypageCredentials

The paypageCredentials element is an optional child of the

subMerchantCreateResponse and subMerchantRetrievalResponse elements and

contains child elements that define the paypageId and associated userName used to submit card

info via the PayPage application.

Parent Elements:

subMerchantCreateResponse, subMerchantRetrievalResponse

Attributes:

None

Child Elements (required):

paypageCredential

PayFac API XML Elements paypageId

180 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.94 paypageId

The paypageId element is an optional child of the paypageCredential element and specifies

the PayPage identifier used to submit PayPage transactions to the production environment. The

system returns a paypageId only if the Sub-merchant uses the Vault/PayPage feature and you set

the createCredentials element to true in the create request.

Type = String; minLength = 1; maxLength = 50

Parent Elements:

paypageCredential

Attributes:

None

Child Elements:

None

phone PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 181

PayFac API Reference Guide

4.95 phone

The phone element is a required child of the primaryContact element. It defines the phone

number for the Sub-merchant’s primary contact.

Type = String; minLength = 1; maxLength = 13

Parent Elements:

primaryContact

Attributes:

None

Child Elements:

None

PayFac API XML Elements phoneVerified

182 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.96 phoneVerified

The phoneVerified element is an optional child of the verificationIndicators element.

A value of true indicates that the phone number (of the business) was verified, while a value of

false indicates that the phone number could not be verified.

Type = Boolean; Allowed values = true or false

Parent Elements:

verificationIndicators

Attributes:

None

Child Elements:

None

postalCode PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 183

PayFac API Reference Guide

4.97 postalCode

Depending upon where used, this is either the postal code of the Legal Entity controlling the

Sub-merchant or of the principal, or of the Sub-merchant. This postalCode element is always

required for a Legal Entity and for a principal if the Legal Entity is a Sole Proprietorship

(legalEntityType).

Type = String; minLength = 1; maxLength = 7

Parent Elements:

address

Attributes:

None

Child Elements:

None

PayFac API XML Elements primaryContact

184 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.98 primaryContact

The primaryContact element is an optional child of both the subMerchantCreateRequest

and the subMerchantUpdateRequest transactions. The children of this element specify

information about the primary contact of the Sub-merchant.

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements (all required):

firstName, lastName, phone, emailAddress

Example: primaryContact

<emailAddress>John.Doe@company.com</emailAddress>

</primaryContact>

principal PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 185

PayFac API Reference Guide

4.99 principal

The principal element has multiple uses in the schema. In two instances it is the parent for the

child elements used to provide information about the Legal Entity principal owners/officers. Its

structure changes based upon whether it is part of a legalEntityCreateRequest,

legalEntityUpdateRequest, legalEntityPrincipalCreateRequest, or a

legalEntityResponse. It is also a child of the backgroundCheckResults element.

Parent Elements:

legalEntityCreateRequest, legalEntityCreateResponse, legalEntityUpdateRequest,

backgroundCheckResults, legalEntityPrincipalCreateRequest,

Attributes:

None

Child Elements (when used in legalEntityCreateRequest or

legalEntityPrincipalCreateRequest):

Required: firstName, lastName, ssn (required for Sole Proprietorship, otherwise optional),

address (some child elements may be optional), dateOfBirth, stakePercent

Optional: emailAddress, contactPhone, driversLicense, driversLicenseState, title

Example: principal Structure when used in legalEntityCreateRequest and

legalEntityPrincipalCreateRequest

<title>Chief Financial Officer</title>

NOTE:Although part of the schema structure, the principalId element is not

used in a legalEntityCreateRequest message.

PayFac API XML Elements principal

186 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 400</streetAddress2>

<city>Lowell</city>

</address>

</principal>

Child Elements (when used in legalEntityCreateResponse):

principalId, firstName, lastName, responseCode, responseDescription, backgroundCheckResults

Example: principal Structure when used in a legalEntityCreateResponse

<description>Business verified on multiple sources - no contradictory

findings</description>

</overallScore>

<nameVerified>false</nameVerified>

<addressVerified>false</addressVerified>

<cityVerified>false</cityVerified>

<stateVerified>false</stateVerified>

<zipVerified>false</zipVerified>

<phoneVerified>false</phoneVerified>

<taxIdVerified>false</taxIdVerified>

principal PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 187

PayFac API Reference Guide

</verificationIndicators>

</verificationResult>

</business>

<description>Full name, address, phone , SSN verified</description>

</overallScore>

<nameVerified>false</nameVerified>

<addressVerified>false</addressVerified>

<phoneVerified>false</phoneVerified>

<ssnVerified>false</ssnVerified>

<dobVerified>false</dobVerified>

</verificationIndicators>

</verificationResult>

</principal>

<description>Association found between the person and the company in the

Company Contacts data</description>

</businessToPrincipalAssociation>

<bankruptcyType>btype</bankruptcyType>

<companyName>testCompanyName</companyName>

<streetAddress1>testStreetAddress1</streetAddress1>

<streetAddress2>testStreetAddress2</streetAddress2>

<city>testCity</city>

PayFac API XML Elements principal

188 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

</bankruptcyData>

<lienType>ltype</lienType>

<companyName>testLienCompanyName</companyName>

<streetAddress1>testLienStreetAddress1</streetAddress1>

<streetAddress2>testLienStreetAddress2</streetAddress2>

<city>testLienCity</city>

</lienResult>

</backgroundCheckResults>

</principal>

Example: principal Structure when used in legalEntityUpdateRequest

<streetAddress1>100 Main Street</streetAddress1>

<streetAddress2>Suite 400</streetAddress2>

<city>Lowell</city>

</address>

principal PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 189

PayFac API Reference Guide

</principal>

PayFac API XML Elements principalId

190 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.100 principalId

The principalId element is a required child of the principal element, when used in a

legalEntityCreateResponse message. It is a system generated identifier for the

principal/owner.

Type = Integer; minLength = N/A; maxLength = 10

Parent Elements:

principal, legalEntityPrincipalCreateResponse

Attributes:

None

Child Elements:

None

NOTE:Although part of the schema structure, this element is not used in a

legalEntityCreateRequest message.

pspMerchantId PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 191

PayFac API Reference Guide

4.101 pspMerchantId

The pspMerchantId element is a required child of the subMerchantCreateRequest element

and is the PayFac supplied identifier string for the Sub-merchant within the PayFac’s systems.

Type = String; minLength = 1; maxLength = 32

Parent Elements:

subMerchantCreateRequest, subMerchantRetrievalResponse, subMerchantUpdateRequest

Attributes:

None

Child Elements:

None

PayFac API XML Elements purchaseCurrency

192 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.102 purchaseCurrency

The purchaseCurrency element is an optional child of the subMerchantCreateRequest

element and defines the purchase currency of transactions from this Sub-merchant. If this element

is not included in the create request, the purchase currency value defaults to the value defined in

the Sub-merchant template used to provision other Sub-merchants associated with this Legal

Entity. When included in the create request, the purchaseCurrency element is also returned in

the Sub-merchant retrieval request and the Sub-merchant create response if the create request was

a duplicate.

Type = String; minLength = 3; maxLength = 3

Parent Elements:

subMerchantCreateRequest, subMerchantRetrievalResponse, subMerchantCreateResponse (if

duplicate), subMerchantUpdateRequest

Attributes:

None

Child Elements:

None

releasedCount PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 193

PayFac API Reference Guide

4.103 releasedCount

The releasedCount element is an optional child of the lienResult element and specifies the

count of released lien records found.

Type = int; totalDigits = N/A

Parent Elements:

lienResult

Attributes:

None

Child Elements:

None

PayFac API XML Elements response

194 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.104 response

The response element is the parent of the XML message acknowledging the receipt of a Legal

Entity Update (legalEntityUpdateRequest), Sub-merchant update

(subMerchantUpdateRequest), or Disable Sub-merchant message.

Parent Elements:

None

Attributes:

Child Elements:

transactionId

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and must be specified as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

responseCode PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 195

PayFac API Reference Guide

4.105 responseCode

The responseCode element is an optional child of the legalEntityResponse message. The

code indicate either success or the reason for the failure of the request. Possible values are listed

in the table below.

Type = String; minLength = N/A; maxLength = 2

Parent Elements:

legalEntityResponse, legalEntityRetrievalResponse

Attributes:

None

Child Elements:

None

Possible Values:

Code responseDescription

10 Approved

20 Manual Review

30 Retry

35 Manual Review - Duplicate

36 Duplicate

40 Declined

98 Manual Review - End Point Down

99 Manual Review - Background Check Error

NOTE:If you receive a responseCode 30 - Retry, the decision notes will contain

additional details about the information that you should provide/correct

on the retry.

PayFac API XML Elements responseDescription

196 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.106 responseDescription

The responseDescription element is an optional child of the legalEntityResponse

message and is a text description of the responseCode.

Type = String; minLength = 1; maxLength = 100

Parent Elements:

legalEntityResponse, legalEntityRetrievalResponse, legalEntityResponse

Attributes:

None

Child Elements:

None

Possible Values:

responseDescription Code

Approved 10

Manual Review 20

Retry 30

Manual Review - Duplicate 35

Duplicate 36

Declined 40

Manual Review - Background Check Error 99

NOTE:If you receive a responseCode 30 - Retry, the decision notes will contain

additional details about the information that you should provide/correct

on the retry.

riskIndicator PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 197

PayFac API Reference Guide

4.107 riskIndicator

The verificationResult element is an optional child of the business and principal

elements and contains child elements providing the results of background checks performed on

the Legal Entity.

Parent Elements:

riskIndicators

Attributes:

None

Child Elements:

code, description

Example: riskIndicator Structure

<code>Risk Indicator Info</code>

<description>Text Description of Code</description>

</riskIndicator>

PayFac API XML Elements riskIndicators

198 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.108 riskIndicators

The riskIndicators element is an optional child of the verificationResult element and

contains child elements providing the results of background checks performed on the Legal

Entity.

Parent Elements:

verificationResult

Attributes:

None

Child Elements:

riskIndicator

Example: riskIndicators Structure

<code>Risk Indicator Info</code>

<description>Text Description of Code</description>

</riskIndicator>

</riskIndicators>

score PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 199

PayFac API Reference Guide

4.109 score

Depending upon where used, this element defines overall score assigned based on the background

checks of either the business, the principal, or the business-to-principal association.

Type = String (Enum); minLength = N/A; maxLength = N/A

Parent Elements:

overallScore, businessToPrincipalAssociation

Attributes:

None

Child Elements:

None

Enumerations: (Higher number is better.)

Enums Definition when

Descendant of business Definition when

Descendant of principal

Definition when

Descendant of

businessToPrincipalAs

sociation

0 Nothing found to confirm

existence of business. Nothing verified - ID

elements not found or are

associated with a different

person.

No information found to link

Principal to Business

10 One or more of the

following:

•Significant contradictory

findings

•OFAC match exists

•Input address and

phone are invalid

One or more of the

following:

•Critical ID elements not

verified or are

associated with a

different person

•OFAC matches

•deceased/invalid SSNs

•SSN issued prior to

DOB

•records with invalid

addresses and phones

Principal’s verified name

partially matches input

Business name.

20 Partial verification of the

input data; the business

may exist, but cannot be

positively confirmed.

Minimal verifications; critical

ID elements not verified or

are associated with a

different person

Principal’s verified address

matches input Business

address.

PayFac API XML Elements score

200 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

30 Business identity is

confirmed, but failure to

verify all identity elements.

Several ID elements

verified; SSN or address

verification failures exist.

Principal’s verified address

matches input Business

address and Principal’s

verified name partially

matches input Business

name.

40 Business identity is

confirmed at the input

address

Last name, address, and

SSN verified; first name or

phone verification failures.

Principal linked to Business

by SSN /Tax Id match.

50 Business is verified using

multiple sources. no

contradictory findings.

Full name, address, phone,

and SSN verified. Principal is likely an officer

or employee of Business

confirmed by public records.

Enums Definition when

Descendant of business Definition when

Descendant of principal

Definition when

Descendant of

businessToPrincipalAs

sociation

settlementCurrency PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 201

PayFac API Reference Guide

4.110 settlementCurrency

The settlementCurrency element is an required child of the subMerchantCreateRequest

element and defines the settlement currency of transactions from this Sub-merchant.

Type = String; minLength = 3; maxLength = 3

Parent Elements:

subMerchantCreateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

PayFac API XML Elements ssn

202 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.111 ssn

The ssn element is a child of the principal element and specifies the Social Security Number

of the principal. If the entityType is INDIVIDUAL_SOLE_PROPRIETORSHIP, you must

submit the principal’s SSN. For other Legal Entity types, you can substitute the Tax ID for the

SSN in this element.

Type = String; minLength = 9; maxLength = 25

Parent Elements:

principal

Attributes:

None

Child Elements:

None

ssnVerified PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 203

PayFac API Reference Guide

4.112 ssnVerified

The ssnVerified element is an optional child of the verificationIndicators element,

when verificationIndicator is a descendant of the principal element. A value of true

indicates that the SSN of the principal was verified, while a value of false indicates that the SSN

could not be verified.

Type = Boolean; Allowed values = true or false

Parent Elements:

verificationIndicators

Attributes:

None

Child Elements:

None

PayFac API XML Elements stakePercent

204 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.113 stakePercent

The stakePercent element is a required child of the principal element and defines the

percentage of the Legal Entity owned by the principal.

Type = Integer; Minimum value = 0; Maximum value = 100

Parent Elements:

principal

Attributes:

None

Child Elements:

None

state PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 205

PayFac API Reference Guide

4.114 state

The state element is an optional child of both the bankrupcyData and lienResults elements,

where it specifies the state of the company with bankruptcy or lien information.

Type = String; minLength = N/A; maxLength = 2

Parent Elements:

bankruptcyData, lienResult

Attributes:

None

Child Elements:

None

PayFac API XML Elements stateVerified

206 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.115 stateVerified

The cityVerified element is an optional child of the verificationIndicators element,

when verificationIndicators is a descendant of the business element. A value of true

indicates that the city (of the business) was verified, while a value of false indicates that the city

could not be verified.

Type = Boolean; Allowed values = true or false

Parent Elements:

verificationIndicators

Attributes:

None

Child Elements:

None

stateProvince PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 207

PayFac API Reference Guide

4.116 stateProvince

Depending upon where used, this is either the code representing the state of the business entity

controlling the Sub-merchant or of the principal. This stateProvince element is always

required for a Legal Entity and for a principal if the Legal Entity is a Sole Proprietorship

(legalEntityType). If the Legal Entity is not a Sole Proprietorship, this element is optional.

Type = String; minLength = 1; maxLength = 2

Parent Elements:

address

Attributes:

None

Child Elements:

None

PayFac API XML Elements streetAddress1, streetAddress2

208 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.117 streetAddress1, streetAddress2

The elements streetAddress1 and streetAddress2 define the address information. The

streetAddress1 element is always required for a Legal Entity. It is also required for the

principal if the Legal Entity is a Sole Proprietorship (legalEntityType). The streeAddress2

element is always optional.

Type = String; minLength = 1; maxLength = 60

Parent Elements:

address, bankruptcyData, lienResult

Attributes:

None

Child Elements:

None

subMerchantCreateRequest PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 209

PayFac API Reference Guide

4.118 subMerchantCreateRequest

The subMerchantCreateRequest element is the parent element for the XML message used to

create a Sub-merchant associated with a Legal Entity. You must create a Legal Entity prior to

adding Sub-merchants controlled by the entity.

Parent Elements:

None

Attributes:

Child Elements:

Required: merchantName, customerServiceNumber, hardCodedBillingDescriptor,

maxTransactionAmount, merchantCategoryCode, bankRoutingNumber, bankAccountNumber,

pspMerchantId, address (some child elements may be optional), settlementCurrency

Required/Optional (depending upon if using PayFac Assurance model): url

Optional: address, amexMid, discoverConveyedMid, purchaseCurrency, primaryContact,

createCredentials, eCheck, fraud, subMerchantFunding

NOTE:After the creation of a Sub-merchant, wait a minimum of two minutes

before attempting to process transactions for the Sub-merchant. This is

the minimum amount of time required for information about the newly

created Sub-merchant to propagate through our system. Attempts to

process transactions for a new Sub-merchant sooner than two minutes

will result in system errors.

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and must be specified as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

PayFac API XML Elements subMerchantCreateResponse

210 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.119 subMerchantCreateResponse

The subMerchantResponse element is the parent element for the XML message returned by

the platform in response to a subMerchantCreateRequest message.

Parent Elements:

None

Attributes:

Child Elements:

Required: transactionId, merchantIdentString

Optional: subMerchantId, originalSubMerchant

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and must be specified as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

duplicate Boolean No Appears in the response message only if the

submerchantCreateRequest was a duplicate

request.

Allowed values = true or false

subMerchantFunding PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 211

PayFac API Reference Guide

4.120 subMerchantFunding

The subMerchantFunding element is an optional child of the subMerchantCreateRequest,

the subMerchantUpdateRequest elements, as well as the

subMerchantRetrievalResponse. Through its child elements, it defines either the Fee

Profile applied to the funding of the Sub-merchant, when the Managed Payout funding feature is

enabled, or the fundingSubMerchantId, when the Dynamic Payout feature is enabled.

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

Child Elements (optional):

feeProfile (required for Managed Payout), fundingSubmerchantId (required for Dynamic Payout)

Example: subMerchantFunding Structure for Managed Payout

<feeProfile>Name of Fee Profile</feeProfile>

</subMerchantFunding>

Example: subMerchantFunding Structure for Dynamic Payout

<fundingSubmerchantId>Unique Funding Id</fundingSubmerchantId>

</subMerchantFunding>

Attribute Name Type Required? Description

enabled Boolean Yes Set to true and include the

fundingSubmerchantId element when using

Dynamic Payout. Set to true and include the

feeProfile element when using Managed Payout

for the Sub-merchant. If neither condition applies (i.e.,

you are funding directly), set to false.

Allowed values = true or false

PayFac API XML Elements subMerchantId

212 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.121 subMerchantId

The subMerchantId element is an optional child of the subMerchantCreateResponse

element and is a system generated identifier for this Sub-merchant within the legal entity. You use

this value as a parameter in the calls when updating, retrieving, and disabling a Sub-merchant.

Type = String; minLength = N/A; maxLength = 19

Parent Elements:

subMerchantCreateResponse, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

NOTE:This value is unique within the Legal Entity, but not across Legal Entities.

sub_merchant_processing_status PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 213

PayFac API Reference Guide

4.122 sub_merchant_processing_status

The sub_merchant_processing_status element is a required child of the

legalEntityRetrievalResponse and indicates if you can create sub-merchants associated

with the Legal Entity, based upon the state of the Legal Entity. A value of true indicates that you

can create sub-merchants.

Type = Boolean; Allowed values = true or false.

Parent Elements:

legalEntityRetrievalResponse

Attributes:

None

Child Elements:

None

PayFac API XML Elements subMerchantRetrievalResponse

214 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.123 subMerchantRetrievalResponse

The subMerchantRetrievalResponse element is the parent element for the XML message

returned by the platform in response to a Sub-merchant Retrieval Request.

Parent Elements:

None

Attributes:

Child Elements:

merchantName, amexMid, discoverConveyedMid, url, customerServiceNumber,

hardCodedBillingDescriptor, maxTransactionAmount, purchaseCurrency,

merchantCategoryCode, bankRoutingNumber, bankAccountNumber, pspMerchantId, fraud,

address, primaryContact, createCredentials, eCheck, subMerchantFunding, settlementCurrency,

subMerchantId, amexSellerId, disabled, transactionId, merchantIdentString, credentials,

paypageCredentials, updateDate

NOTE:If you are processing transactions only on the Vantiv eCommerce platform

and using Dynamic Payout, after creating a Sub-merchant using a value of

AUTO_GENERATE for the fundingSubmerchantId, retrieve the

assigned fundingSubmerchantId value by submitting a Sub-merchant

Retrieval Request.

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and must be specified as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

subMerchantUpdateRequest PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 215

PayFac API Reference Guide

4.124 subMerchantUpdateRequest

The subMerchantUpdateRequest element is the parent element for the XML message used to

update a Sub-merchant associated with a Legal Entity. You can update the following items:

Parent Elements:

None

Attributes:

Child Elements:

amexMid, discoverConveyedMid, url, customerServiceNumber, hardCodedBillingDescriptor,

maxTransactionAmount, bankRoutingNumber, bankAccountNumber, address, primaryContact,

disable, fraud, eCheck, subMerchantFunding

•url •streetAddress1

•customerServiceNumber •streetAddress2

•hardCodedBillingDescriptor •city

•maxTransactionAmount •stateProvince

•bankRoutingNumber •postalCode

•bankAccountNumber •primaryContact

•eCheckBillingDescriptor •eCheckCompanyName

Attribute Name Type Required? Description

xmlns String Yes Defines the URI of the schema definition. This is a

fixed location and must be specified as:

http://payfac.vantivcnp.com/api/merchant/o

nboard

minLength = N/A maxLength = 50

PayFac API XML Elements taxAuthority

216 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.125 taxAuthority

The taxAuthority element is an optional child of both the submerchantCreateRequest and

the submerchantUpdateRequest elements; however, you must specify a value if the MCC of

the sub-merchant is 9311 (Tax Payments - Government Agencies). The element specifies the Tax

Authority (taxing body) for which the sub-merchant collects tax payments.

Type = String; minLength = N/A; maxLength = N/A

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest

Attributes:

None

Child Elements:

None

NOTE:Although maxLength is not defined in the schema, the maximum length of

the taxAuthority + Billing Descriptor prefix cannot exceed 20 characters.

Please ask your Implementation consultant for additional information.

taxAuthorityState PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 217

PayFac API Reference Guide

4.126 taxAuthorityState

The taxAuthorityState element is an optional child of both the

submerchantCreateRequest and the submerchantUpdateRequest elements; however,

you must specify a value if the MCC of the sub-merchant is 9311 (Tax Payments - Government

Agencies). The element specifies the state for which the sub-merchant collects tax payments.

Type = String; minLength = 1; maxLength = 2

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest

Attributes:

None

Child Elements:

None

PayFac API XML Elements taxId

218 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.127 taxId

The taxId element is a required child of the legalEntityCreateRequest element and

defines the Tax ID (or EIN if applicable) of the Legal Entity controlling the Sub-merchants. If the

entityType is INDIVIDUAL_SOLE_PROPRIETORSHIP and a Tax ID is not available, you

can include the principal’s SSN in this element.

Type = String; minLength = 9; maxLength = 25

Parent Elements:

legalEntityCreateRequest, legalEntityRetrievalResponse

Attributes:

None

Child Elements:

None

taxIdVerified PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 219

PayFac API Reference Guide

4.128 taxIdVerified

The taxIdVerified element is an optional child of the verificationIndicators element,

when verificationIndicators is a descendant of the business element. A value of true

indicates that the Tax Id (of the business) was verified, while a value of false indicates that the

Tax Id could not be verified.

Type = Boolean; Allowed values = true or false

Parent Elements:

verificationIndicators

Attributes:

None

Child Elements:

None

PayFac API XML Elements tinValidationStatus

220 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.129 tinValidationStatus

The tinValidationStatus element is an optional child of the

legalEntityRetrievalResponse element and specifies the status of the Tax Id Number

validation operation. Currently, possible values are: Approved, Failed, Pending, and Not

Required.

Type = String; minLength = 1; maxLength = 20

Parent Elements:

legalEntityRetrievalResponse

Attributes:

None

Child Elements:

None

title PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 221

PayFac API Reference Guide

4.130 title

The title element is an optional child of the principal element that specifies the title of the

principal. It is, however, required when your Organization is configured (in your Merchant

Profile) to use the PayFac Assurance model. In this case, failure to include the element will result

in a validation error.

Type = String; minLength = N/A; maxLength = 60

Parent Elements:

principal

Attributes:

None

Child Elements:

None

NOTE:Although the title element is optional, you must include a value if you

support American Express Opt Blue transactions.

PayFac API XML Elements transactionId

222 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.131 transactionId

The transactionId element is a required child of the legalEntityResponse element and is

a system generated identifier for the submitted request.

Type = String; minLength = 1; maxLength = 19

Parent Elements:

legalEntityAgreementCreateResponse, legalEntityResponse, legalEntityRetrievalResponse,

subMerchantCreateResponse, response, errorResponse, subMerchantRetrievalResponse,

approvedMccResponse

Attributes:

None

Child Elements:

None

unreleasedCount PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 223

PayFac API Reference Guide

4.132 unreleasedCount

The unreleasedCount element is an optional child of the lienResult element and specifies

the count of unreleased lien records found.

Type = int; totalDigits = N/A

Parent Elements:

lienResult

Attributes:

None

Child Elements:

None

PayFac API XML Elements updateDate

224 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.133 updateDate

The updateDate element is and optional child of both the legalEntityRetrievalResponse

and the subMerchantRetrievalResponse element. The value represents the last date/time an

update was performed to the Legal Entity/Sub-Merchant.

Type = dateTime; Format = YYYY-MM-DDTHH:MM:SS+/-HH:MM

Parent Elements:

legalEntityRetrievalResponse, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

NOTE:The +/-HH:MM portion of the dateTime format represents the offset from

UTC time. For example, for Boston the value would be -05:00, meaning

five hours behind UTC time.

url PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 225

PayFac API Reference Guide

4.134 url

The url element is an optional child of the subMerchantCreateRequest element and

specifies the URL of the Sub-merchant.

Type = String; minLength = 1; maxLength = 120

Parent Elements:

subMerchantCreateRequest, subMerchantUpdateRequest, subMerchantRetrievalResponse

Attributes:

None

Child Elements:

None

PayFac API XML Elements userFullName

226 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.135 userFullName

The userFullName element is a required child of the legalEntityAgreement element and

defines name of the party signing the Legal Entity Agreement.

Type = String; minLength = 1; maxLength = 50

Parent Elements:

legalEntityAgreement

Attributes:

None

Child Elements:

None

userIPAddress PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 227

PayFac API Reference Guide

4.136 userIPAddress

The userIPAddress element is a child of the legalEntityAgreement element and defines

the IP Address of the party signing the Legal Entity Agreement. This element is required when

the manuallyEntered element is set to false. It is not required when the manuallyEntered

element is set to true. The only allowed characters are lower-case a-z, upper-case A-Z, numbers

0-9, colon (:), and a period (.).

Type = String; minLength = 1; maxLength = 40

Parent Elements:

legalEntityAgreement

Attributes:

None

Child Elements:

None

PayFac API XML Elements userName

228 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.137 userName

The username element is a required child of the credentials element and specifies the user

name portion of the authentication credentials used to submit transaction to the production

environment.

Type = String; minLength = 1; maxLength = 72

Parent Elements:

credentials, paypageCredential

Attributes:

None

Child Elements:

None

NOTE:Although the V4 schema specifies this element as username, the actual

element returned in the response file is userName.

userSystemName PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 229

PayFac API Reference Guide

4.138 userSystemName

The userSystemName element is a required child of the legalEntityAgreement element

and defines name the party signing the Legal Entity Agreement uses on the PayFac system.

Type = String; minLength = 1; maxLength = 50

Parent Elements:

legalEntityAgreement

Attributes:

None

Child Elements:

None

PayFac API XML Elements verificationIndicators

230 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.139 verificationIndicators

The verificationIndicators element is an optional child of the verificationResult

element and contains child elements that indicated whether or not certain data points about the

Legal Entity were verified during the background checks.

Parent Elements:

verificationResult

Attributes:

None

Child Elements:

Common: nameVerified, addressVerified, phoneVerified

Descendant of bussiness: cityVerified, stateVerified, zipVerified, taxIdVerified

Descendant of principal: ssnVerified, dobVerified

Example: verificationIndicators Structure (when descendant of bussiness)

<nameVerified>true or false</nameVerified>

<addressVerified>true or false</addressVerified>

<cityVerified>true or false</cityVerified>

<stateVerified>true or false</stateVerified>

<zipVerified>true or false</zipVerified>

<phoneVerified>true or false</phoneVerified>

<taxIdVerified>true or false</taxIdVerified>

</verificationIndicators>

Example: verificationIndicators Structure (when descendant of principal)

<nameVerified>true or false</nameVerified>

<addressVerified>true or false</addressVerified>

<phoneVerified>true or false</phoneVerified>

<ssnVerified>true or false</ssnVerified>

<dobVerified>true or false</dobVerified>

verificationIndicators PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 231

PayFac API Reference Guide

</verificationIndicators>

PayFac API XML Elements verificationResult

232 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.140 verificationResult

The verificationResult element is an optional child of the business and principal

elements and contains child elements providing the results of background checks performed on

the Legal Entity.

Parent Elements:

business, principal

Attributes:

None

Child Elements:

Common: overallScore, nameAddressPhoneAssociation, verificationIndicators, riskIndicators

Descendant of bussiness: nameAddressTaxIdAssociation

Descendant of principal: nameAddressSsnAssociation

Example: verificationResult Structure (as child of business)

<score>Overall results for Business</score>

<description>Text Description of Score</description>

</overallScore>

<code>Name_Address_TIN_info</code>

<description>Text Description of Code</description>

</nameAddressTaxIdAssociation>

<code>Name_Address_Phone_info</code>

<description>Text Description of Code</description>

</nameAddressPhoneAssociation>

<nameVerified>true or false</nameVerified>

<addressVerified>true or false</addressVerified>

<cityVerified>true or false</cityVerified>

<zipVerified>true or false</zipVerified>

verificationResult PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 233

PayFac API Reference Guide

<phoneVerified>true or false</phoneVerified>

<taxIdVerified>true or false</taxIdVerified>

</verificationIndicators>

<code>Risk Indicator Info</code>

<description>Text Description of Code</description>

</riskIndicator>

</riskIndicators>

</verificationResult

Example: verificationResult Structure (as child of principal)

<score>Overall Results for Principal</score>

<description>Text Description of Score</description>

</overallScore>

<code>Name_Address_SSN_info</code>

<description>Text Description of Code</description>

</nameAddressSsnAssociation>

<code>Name_Address_Phone_info</code>

<description>Text Description of Code</description>

</nameAddressPhoneAssociation>

<nameVerified>true or false</nameVerified>

<addressVerified>true or false</addressVerified>

<phoneVerified>true or false</phoneVerified>

<ssnVerified>true or false</ssnVerified>

<dobVerified>true or false</dobVerified>

</verificationIndicators>

<code>Risk Indicator results</code>

PayFac API XML Elements verificationResult

234 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

<description>Text Description of Code</description>

</riskIndicator>

</riskIndicators>

</verificationResult>

yearsInBusiness PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 235

PayFac API Reference Guide

4.141 yearsInBusiness

The yearsInBusiness element is an optional child of the legalEntityCreateRequest

element. It is, however, required when your Organization is configured (in your Merchant Profile)

to use the PayFac Assurance model. In this case, failure to include this element will result in a

validation error.

Type = Integer; minLength = N/A; maxLength = 3

Parent Elements:

legalEntityCreateRequest, legalEntityUpdateRequest

Attributes:

None

Child Elements:

None

PayFac API XML Elements zip

236 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.142 zip

The zip element defines the company postal code in both the bankruptcyData and

lienResults elements. The element is optional.

Type = String; minLength = N/A; maxLength = 5

Parent Elements:

bankruptcyData, lienResult

Attributes:

None

Child Elements:

None

zip4 PayFac API XML Elements

Document Version: 2.1 — API Release: 13.0 237

PayFac API Reference Guide

4.143 zip4

The zip4 element defines the extended +4 portion of the company postal code in both the

bankruptcyData and lienResults elements. The element is optional.

Type = String; minLength = N/A; maxLength = 4

Parent Elements:

bankruptcyData, lienResult

Attributes:

None

Child Elements:

None

PayFac API XML Elements zipVerified

238 Document Version: 2.1 — API Release: 13.0

PayFac API Reference Guide

4.144 zipVerified

The zipVerified element is an optional child of the verificationIndicators element,

when verificationIndicators is a descendant of the business element. A value of true

indicates that the zip code (of the business) was verified, while a value of false indicates that the

zip code could not be verified.

Type = Boolean; Allowed values = true or false

Parent Elements:

verificationIndicators

Attributes:

None

Child Elements:

None

PayFac API Reference Guide Vantiv Pay Fac APIV13.0 V2.1

Navigation menu

Versions of this User Manual:

Views

Navigation