Merchant Application API v2

The Merchant Application API allows you to submit applications for merchants to obtain credit card processing services.

Overview

The purpose of this API is to allow our partners a programmatic way to submit merchant applications. Once an application has been submitted through this API the on-boarding / underwriting status can be obtained using the Merchant DataFeed v2 API.

For a detailed list of the REST API endpoints please see the Swagger Documentation.

If you have not done so yet, please read the Getting Started and Design Principles documentation for important information related to our APIs.


Usage Scenarios

This API is designed to be flexible in supporting various usage scenarios for our partners. There are three primary usage scenarios for working with the API that are listed below. Each of these workflows include additional documentation (including diagrams), describing its implementation. Please be sure to click the links below to open additional important documentation.

Documented Usage Scenarios:


Application Workflow

A Merchant Application is created via the API by POSTing an ApplicationSave data structure to /api/v2/applications. All field values passed in must be valid for the 'Save' to complete successfully. Field Values, Principals, and Equipment are optional when creating a new Application. If validation errors occur, they will be returned as a ValidationResults data structure. Once an Application has been created, an ApplicationID will be returned that enables further management of that Application. To modify information associated with the Application, POST a fully populated ApplicationSave data structure to /api/v2/applications/{ApplicationID} which will replace all existing information with the contents of the supplied ApplicationSave structure.

Once a certain minimal set of information has been provided in the Application, the Merchant can be directed to complete the Application via iEntry, Paysafe’s web application. POST to /api/v2/applications/{ApplicationID}/merchanthandoff to email the Merchant an iEntry URL, login credentials, and instructions on completing the Application submission process. If the required information is not present, errors will be returned as a ValidationResults data structure. If successful, an automated email is sent to the merchant containing instructions and a URL that directs the merchant to iEntry.

If completing the Application using the API (without using iEntry), it is necessary to POST to /api/v2/applications/{ApplicationID}/presubmission once all information for the Application has been provided. A PDF of the contract will be automatically added to the Application. If validation errors exist or information is missing, errors will be returned as a ValidationResults data structure. The Application will also change state to 'Waiting for a Signed Contract'. POSTing to /api/v2/applications/{ApplicationID} will no longer be valid but document uploads will still be permitted. To complete and submit the Application, a signed copy of the contract must be attached to the Application, followed by POSTing to /api/v2/applications/{applicationID}/finalsubmission. The Application will change state again to 'Submitted' and be queued for processing by Paysafe. If any errors occur, they will be returned as a ValidationResults data structure.

The flow of Applications through the API is depicted in the below diagram. The grey boxes in the diagram refer to additional diagrams and accompanying documentation which describe key workflow actions. Please view the documented Usage Scenarios to see the additional workflow diagrams and documentation.


Application Workflow Diagram

The following summarizes the three types of Application create functions:

The flow of the three types of Application submission are depicted in the diagram below


Create Application Flow Diagram

API Authentication

All calls to the API REST endpoints must be made using Secure HTTP (HTTPS) and authenticated by including the API Key and API Secret that will be provided to the partner. Please refer to our Design Principles documentation for additional information.


Applications

The term "Application" in this API refers to a collection of information that describes a merchant who is applying for credit card processing services. Applications are the most frequent data entity developers will work with in the API. There are three top level DTOs for working with Applications:


Documents

Each Merchant Application can have zero or more Documents attached to it which are represented by the ApplicationDocument data structure. Some documents, such as the unsigned Merchant Processing Agreement are automatically generated and attached at certain points during the Application's workflow. Other types of documents can be uploaded and attached by the Partner or Merchant to provide additional information (such as banking records) or to fulfill certain processing requirements (such as uploading a scanned copy of a physically signed contract).


Packages

The term "Package" in this API refers to the metadata that describes the information that can be included in an Application. The top level DTO for working with Package metadata is Package

A Package relates to Applications in a similar way that, in object-oriented programming, a class relates to instances of a class. The Package defines the available fields, available equipment, legal terms, etc. that are common to all Applications produced under the terms of that Package. Packages are specific to and designed for each partner. Paysafe works with each partner to determine the rules and settings for each Package. The Packages available to the partner is returned as an array of PackageInfo from a GET to /api/v2/packages. Each PackageInfo contains a PackageID as well as a Name and Description. The specifics for an individual Package are returned from a GET to /api/v2/packages/{PackageID}.

A Package can also limit which Equipment is available. The lists of available Equipment is not returned with the Package details, but from separate endpoints as documented in the following section.


Equipment & Peripherals

The information in this section is obsolete as of the 0619 app version. See breaking changes here.

The three types of Equipment that can be added to Applications are Gateways, Terminals, and Software. The Gateways, Terminals, and Software available for inclusion are determined by the Application's Package. Lists suitable for display and selection of the Gateways, Terminals, and Software available for a Package are returned from additional GETs.

Gateways

The list of Gateways available for a Package is returned from a GET to /api/v2/packages/{PackageID}/gateways. This list can be displayed to the user for selection. Each EquipmentGateway has a unique GatewayID.

Terminals and Software

Terminals and Software can be selected just like Gateways from lists returned from GETs to /api/v2/packages/{PackageID}/terminals and /api/v2/packages/{PackageID}/software, and this may be appropriate for Packages that limit the available Terminals and Software to short lists. However, when large number of Terminals and Software are available, the API enables you to group Terminals by Brand and group Software Versions by Software Title to simplify the selection process.

The list of Terminal Brands returned from a GET to /api/v2/packages/{PackageID}/terminalbrands provides the TerminalBrandID that can be used in a GET to /api/v2/packages/{PackageID}/terminalbrands/{TerminalBrandID}, which returns the same list of EquipmentTerminalModel as /api/v2/packages/{PackageID}/terminals except it includes only those items with the provided TerminalBrandID. Each EquipmentTerminalModel has a unique TerminalID.

The list of Software Title returned from a GET to /api/v2/packages/{PackageID}/softwaretitles provides the SoftwareTitleID that can be used in a GET to /api/v2/packages/{PackageID}/softwaretitles/{SoftwareTitleID}, which returns the same list of EquipmentSoftwareVersion as /api/v2/packages/{PackageID}/software except it includes only those items with the provided SoftwareTitleID. Each EquipmentSoftwareVersion has a unique SoftwareID.

Adding Equipment to an Application

Gateways, Terminals, and Software, along with associated Peripherals, can be ordered as part of an Application by adding them in the Application's Equipment list. Please note that the ApplicationEquipment data structure requires an EquipmentID value which can be a GatewayID, TerminalID, or SoftwareID. The type of item being specified is indicated by the EquipmentTypeID value. Valid EquipmentTypeID values are returned from a GET to /api/v2/lookups/equipmenttypes.

If the user chooses an Equipment item, they should then be prompted to select a Payment Processor and optional Peripherals (see below). For each Equipment item selected, add an ApplicationEquipment item to the Equipment collection of the ApplicationSave data structure POSTed to either /api/v2/applications to create a new Application or /api/v2/applications/{ApplicationID} to update an existing Application.

Payment Processors, Peripherals, and Additional Information

Each ApplicationEquipment must have a Payment Processor specified and can specify additional information via FieldValues if needed. Each ApplicationEquipment can also optionally specify Peripherals to be ordered for it. The list of available Payment Processors and Peripherals is determined by both the Package and the Equipment item. The available choices are returned from GETs to

If the Peripheral being ordered has options or needs additional information, FieldValues can be populated for the individual Peripherals.


Sales Representatives

Every Merchant Application must specify a representative that will get credit for the sale. The list of representatives associated with the partner is returned from a GET to /api/v2/agent/salesreps. Each SalesRep data structure returned has details for an individual person or a virtual identity, such as a sales office or the organization as a whole.


Errors & Validation Results

When an error or validation failure is returned from the API, the result will be a ValidationResults data structure that contains one or more ValidationResult data structures.

When an application’s data is saved by POSTing to either /api/v2/applications to create a new Application or /api/v2/applications/{ApplicationID} to update an existing Application, its individual FieldValues are validated to ensure they are acceptable. The save operation will fail if any FieldValues are invalid.

These two operations will return a ValidationResults data structure if errors are found. Saving an application only performs field level validation, but does not apply broader multi-field validations. This allows partial applications that do not include all required information to be saved for later completion.

Every time an ApplicationSave data structure is POSTed to /api/v2/applications/{ApplicationID}, it must include every FieldValue, PassthroughValue, ApplicationPrincipal, and ApplicationEquipment, in the Application, because /api/v2/applications/{ApplicationID} replaces the entire ApplicationSave data structure.

After all the Application data is finally saved, operations that move the Application to subsequent stages of the merchant application process perform additional validations. At any point, a GET to /api/v2/applications/{ApplicationID}/validation will return the ValidationResults that would be returned if you were to attempt an operation that would move the Application forward.

Before POSTing to /api/v2/applications/{ApplicationID}/virtualsignature or /api/v2/applications/{ApplicationID}/presubmission, all fields marked as required (via IsRequired) must have a value. Those POSTs and the GET to /api/v2/applications/{ApplicationID}/validation also check the Application against the complete set of validation rules and return any omissions or changes required as ValidationResults.

ValidationResults (DTO)

Defines an error message describing a validation failure associated with a Merchant Application
FieldTypeDescription
ApplicationID Guid? If the application is saved, returns its unique identifier.
Results List<ValidationResult> List containing validation error messages returned by the attempted action.
Warnings List<ValidationResult> List containing warning messages returned by the attempted action.

ValidationResult (DTO)

Contains a message relating to data in the Merchant Application (typically describes a validation that failed).
FieldTypeDescription
ReferenceType string Optional. Indicates the type of Application element to which the ReferenceID refers.
ReferenceID Guid? Optional unique identifier of the element within the Merchant Application to which this validation result pertains.
Message string Descriptive message indicating the validation failure.

Reference Types

Type Description Identifiers
Application Message applies to the application as a whole (no ReferenceID will be provided)
Field Message applies to a specific field FieldID
Equipment:[EquipmentTypeID] Message applies to a specific equipment item that was included in the application
Example: ReferenceType = ‘Equipment:G’ for gateway, ‘Equipment:TM’ for terminal model, ‘Equipment:SV’ for software version
GatewayID, SoftwareID, or TerminalID
Document Message applies to a specific document associated with the application DocumentID

Identifiers

List of all unique identifiers used by the API.
IdentifierData TypeDescription
ApplicationID Guid
ApplicationStatusID string
DocumentID Guid
DocumentTypeID string
EquipmentID Guid
EquipmentTypeID string
FieldID Guid
GatewayID Guid
GroupID Guid
PackageID Guid
PeripheralID Guid
PeripheralTypeID string
ProcessorID Guid
SalesRepID Guid
SectionID Guid
SoftwareID Guid
SoftwareTitleID Guid
TerminalBrandID Guid
TerminalID Guid

Data Type Reference (DTOs)

Below are tables describing the most common DTO data structures used in the API. This information is provided for convenience and easy reading. When in doubt please refer to the Swagger Documentation which is automatically generated from source code and contains all data structures used by the API.

Accessory

FieldTypeDescription
AccessoryTypeId string
AccessoryId Guid?
AccessoryName string

Application

Represents an Application submitted by a merchant to initiate credit card processing.
FieldTypeDescription
FieldValues List<FieldValue> List of values for the Application's fields
PassthroughValues List<PassthroughValue> Optional passthrough Key/Value pairs for the Application
Principals List<ApplicationPrincipal> List of Principals for the business
Equipment List<ApplicationEquipment> List of Equipment included (along with associated configuration and Peripherals)
Documents List<ApplicationDocument> List of Documents that are associated with the application
ApplicationID Guid Unique identifier of this Merchant Application
SalesRepID Guid Unique identifier of the SalesRep who is associated with the Application (the SalesRep is returned from a GET to /api/v2/agent/salesreps)
PackageID Guid Unique identifier of the Package that defines the metadata for the Application (the Package is returned from a GET to /api/v2/packages/{PackageID})
ApplicationStatusID string Unique identifier of the ApplicationStatus that describes the current status of the Application (the ApplicationStatus is returned from a GET to /api/v2/lookups/applicationstatustypes)
HasSignature bool True if the Merchant has signed or otherwise accepted the Merchant Processing Agreement
CreatedWhen DateTime Date & time the Application was created
UpdatedWhen DateTime Date & time the Application was last changed / saved

ApplicationDocument

Represents a Document (file) associated with a Merchant Application.
FieldTypeDescription
DocumentID Guid Unique identifier of the attached Document
DocumentTypeID string Unique identifier of the DocumentType that indicates the type, format, and purpose of the Document (the DocumentType is returned from a GET to /api/v2/lookups/documenttypes)
FileSize int Size (in bytes) of the file that was uploaded
FileName string Name of the file that was uploaded
Description string User-entered description
MimeType string MIME Type of the file
CreatedWhen DateTime Date and time when the Document was attached to the Merchant Application

ApplicationDocumentContent

A Document (including the binary content) that is related to a specific Merchant Application.
FieldTypeDescription
FileData byte[] Binary file image
DocumentID Guid Unique identifier of the attached Document
DocumentTypeID string Unique identifier of the DocumentType that indicates the type, format, and purpose of the Document (the DocumentType is returned from a GET to /api/v2/lookups/documenttypes)
FileSize int Size (in bytes) of the file that was uploaded
FileName string Name of the file that was uploaded
Description string User-entered description
MimeType string MIME Type of the file
CreatedWhen DateTime Date and time when the Document was attached to the Merchant Application

ApplicationDocumentUpload

Document file to be uploaded and attached to a Merchant Application.
FieldTypeDescription
DocumentTypeID string Unique identifier of the DocumentType that indicates the type, format, and purpose of the Document (the DocumentType is returned from a GET to /api/v2/lookups/documenttypes)
Description string User-entered description
MimeType string MIME Type of the file
FileName string Name of the file that was uploaded
FileSize int Size (in bytes) of the file that was uploaded
FileData byte[] Binary file image

ApplicationEquipment

Specifies a piece of Equipment and its configuration information.
FieldTypeDescription
EquipmentTypeID string Unique identifier of the EquipmentType that indicates the type of the Equipment (Gateway, Terminal, or Software) being specified (the EquipmentType is returned from a GET to /api/v2/lookups/equipmenttypes)
EquipmentID Guid Unique identifier of an Equipment item returned from a GET to /api/v2/packages/{PackageID}/gateways, /api/v2/packages/{PackageID}/terminals, or /api/v2/packages/{PackageID}/software
ProcessorID Guid Unique identifier of the Processor to be associated with the Equipment, which must be found in the list returned from the appropriate GET among /api/v2/packages/{PackageID}/gateways/{GatewayID}/processors, /api/v2/packages/{PackageID}/terminals/{TerminalID}/processors, and /api/v2/packages/{packageID}/software/{SoftwareID}/processors
FieldValues List<FieldValue> Information about the configuration of the Equipment item as specified in a list of field/value pairs
Peripherials List<ApplicationEquipmentPeripheral> Optionally specifies Peripherals and their configuration to be included with the Equipment item (yes, the field is misspelled, sorry, but correcting it would be a breaking change)

ApplicationEquipmentPeripheral

Specifies an Equipment Peripheral and its configuration information.
FieldTypeDescription
PeripheralID Guid Unique identifier of a Peripheral item returned from a GET to /api/v2/packages/{PackageID}/gateways/{GatewayID}/peripherals, /api/v2/packages/{PackageID}/terminals/{TerminalID}/peripherals, or /api/v2/packages/{packageID}/software/{SoftwareID}/peripherals
FieldValues List<FieldValue> Information about the configuration of the Peripheral item as specified in a list of field/value pairs

ApplicationInfo

Provides high level information and metadata about a Merchant Application.
FieldTypeDescription
ApplicationID Guid Unique identifier of this Merchant Application
SalesRepID Guid Unique identifier of the SalesRep who is associated with the Application (the SalesRep is returned from a GET to /api/v2/agent/salesreps)
PackageID Guid Unique identifier of the Package that defines the metadata for the Application (the Package is returned from a GET to /api/v2/packages/{PackageID})
ApplicationStatusID string Unique identifier of the ApplicationStatus that describes the current status of the Application (the ApplicationStatus is returned from a GET to /api/v2/lookups/applicationstatustypes)
HasSignature bool True if the Merchant has signed or otherwise accepted the Merchant Processing Agreement
CreatedWhen DateTime Date & time the Application was created
UpdatedWhen DateTime Date & time the Application was last changed / saved

ApplicationLegal

Legal Terms and Conditions for an Application.
FieldTypeDescription
ApplicationID Guid Unique identifier of the Application
PackageID Guid Unique identifier of the Package
LegalText string Legal text for the Package or Application (as a property of ApplicationLegal, this is the actual legal text, as a property of PackageLegal, it may contain placeholder tokens that will be replaced for each Application depending on data in that Application

ApplicationPrincipal

Information about a person who will be responsible for the merchant account.
FieldTypeDescription
FieldValues List<FieldValue> Information about the Principal as specified in a list of field/value pairs

ApplicationSave

Data structure used to create or update a Merchant Application.
FieldTypeDescription
SalesRepID Guid Unique identifier of the SalesRep who is associated with the Application (the SalesRep is returned from a GET to /api/v2/agent/salesreps)
PackageID Guid Unique identifier of the Package that defines the metadata for the Application (the Package is returned from a GET to /api/v2/packages/{PackageID})
UserIpAddress string IP address of the remote user if applicable
FieldValues List<FieldValue> List of values for the Application's fields
PassthroughValues List<PassthroughValue> Optional passthrough Key/Value pairs for the Application
Principals List<ApplicationPrincipal> List of Principals for the business
Equipment List<ApplicationEquipment> List of Equipment included (along with associated configuration and Peripherals)

ApplicationStatus

Defines a Status that indicates the current state of a merchant's Application.
FieldTypeDescription
ApplicationStatusID string Unique identifier
Name string Display name
Description string Optional description

BackEnd

Information to identify a BackEnd.
FieldTypeDescription
BackEndId Guid Unique identifier
Name string Display name

BoardingStatus

FieldTypeDescription
ApplicationID Guid
MerchantNumber string
LegalBusinessName string
DBABusinessName string
SalesAgent string
BoardingStatusDescription string
Comments string
ApprovalDate DateTime?
MID string
TID string
DateReceived DateTime?
SerialNumber string
ApplicationType string
DownloadComments string
DownloadPhoneNumber string
SubmitDate DateTime?
LastUpdated DateTime

BrandIdQuery

Query for Brands to search
FieldTypeDescription
SearchType string SearchType=["AnyValueIsPresent", "NoValueIsPresent", null]
SearchValues List<Guid>
Output bool

BrandNameQuery

Query for BrandNames to search
FieldTypeDescription
SearchType string SearchType=["AnyValueIsPresent", "NoValueIsPresent","BeginsWithAnyValue", "DoesNotBeginWithAnyValue","ContainsAnyValue", "DoesNotContainAnyValue", null]
SearchValues List<string>
Output bool

DocumentType

Defines a type of Document that can be attached to a Merchant Application
FieldTypeDescription
DocumentTypeID string Unique identifier
Name string Display name
Description string Optional description
IsReadOnly bool If true, Documents of this type cannot be added

EquipmentCount

Provides the total number of items available of a specific Equipment Type.
FieldTypeDescription
EquipmentTypeID string Unique identifier of the EquipmentType that indicates the type of the Equipment (Gateway, Terminal, or Software) being specified (the EquipmentType is returned from a GET to /api/v2/lookups/equipmenttypes)
Quantity int Quantity of items available

EquipmentGateway

Basic information for an item in a list of Gateways.
FieldTypeDescription
GatewayID Guid Unique identifier
Name string Display name

EquipmentGatewayDetail

Details about a Gateway.
FieldTypeDescription
RequiresMobileDevice bool If true, the Gateway is intended for use by mobile devices
PeripheralCount int Quantity of compatible Peripheral devices
Processors IList<EquipmentProcessor> List of compatible Processors
GatewayID Guid Unique identifier
Name string Display name

EquipmentIdentity

FieldTypeDescription
EquipmentTypeId string
IndustryId string
BrandId Guid?
BrandName string
EquipmentId Guid?
EquipmentName string
PaymentProcessorId Guid?
OwnershipIds IReadOnlyCollection<Guid>
Accessories IReadOnlyCollection<Accessory>

EquipmentNameQuery

Query for EquipmentNames to search
FieldTypeDescription
SearchType string SearchType=["AnyValueIsPresent", "NoValueIsPresent","BeginsWithAnyValue", "DoesNotBeginWithAnyValue","ContainsAnyValue", "DoesNotContainAnyValue", null]
SearchValues List<string>
Output bool

EquipmentOwnershipType

Information to identify a EquipmentOwnershipType.
FieldTypeDescription
EquipmentOwnershipTypeId Guid Unique identifier
Name string Display name

EquipmentPeripheral

Information to identify and categorize a Peripheral.
FieldTypeDescription
PeripheralID Guid Unique identifier
PeripheralTypeID string Unique identifier of the EquipmentPeripheralType that indicates the type of the Peripheral (pin pad, card reader, etc.) being specified (the EquipmentPeripheralType is returned from a GET to /api/v2/lookups/peripheraltypes)
Name string Display name

EquipmentPeripheralType

Defines a type of Peripheral (such as pin pad, card reader, receipt printer, etc.).
FieldTypeDescription
PeripheralTypeID string Unique identifier
Name string Display name
Description string Optional description

EquipmentProcessor

Information to identify a Processor.
FieldTypeDescription
ProcessorID Guid Unique identifier
Name string Display name

EquipmentSearchQuery

Defines a query object that can be used to search equipments
FieldTypeDescription
Type EquipmentTypeQuery Query for Equipment Types to search
Item ItemQuery Query for Items to search
EquipmentName EquipmentNameQuery Query for EquipmentNames to search
PeripheralName PeripheralNameQuery Query for PeripheralNames to search
Industry IndustryQuery Query for Industry to search
BrandId BrandIdQuery Query for Brands to search
BrandName BrandNameQuery Query for BrandNames to search
PaymentProcessor PaymentProcessorQuery Query for PaymentProcessors to search
Ownership OwnershipQuery Query for Ownership Types to search

EquipmentSoftwareTitle

Basic information for an item in a list of Software Titles.
FieldTypeDescription
SoftwareTitleID Guid Unique identifier
Name string Display name
VersionCount int Number of EquipmentSoftwareVersions that exist for this Title

EquipmentSoftwareVersion

Basic information for an item in a list of Software Versions.
FieldTypeDescription
SoftwareID Guid Unique identifier
SoftwareTitle string Display name of the Software Title
SoftwareVersion string Display name of the Software Version

EquipmentSoftwareVersionDetail

Details about a Software Version.
FieldTypeDescription
SoftwareTitleId Guid Unique identifier of the Software Title this Version belongs to
PeripheralCount int Quantity of compatible Peripheral devices
Processors IList<EquipmentProcessor> List of compatible Processors
SoftwareID Guid Unique identifier
SoftwareTitle string Display name of the Software Title
SoftwareVersion string Display name of the Software Version

EquipmentTerminalBrand

Basic information for an item in a list of Terminal Brands.
FieldTypeDescription
TerminalBrandID Guid Unique identifier
Name string Display name
ModelCount int Number of EquipmentTerminalModels that exist for this Brand

EquipmentTerminalModel

Basic information for an item in a list of Terminal Models.
FieldTypeDescription
TerminalID Guid Unique identifier
BrandName string Display name of the Terminal Brand
ModelName string Display name of the Terminal Model

EquipmentTerminalModelDetail

Details about a Terminal Model.
FieldTypeDescription
TerminalBrandId Guid Unique identifier of the Terminal Brand this Model belongs to
ComplianceExpirationDate DateTime? The date when this Terminal Model is no longer in compliance
PeripheralCount int Quantity of compatible Peripheral devices
Processors IList<EquipmentProcessor> List of compatible Processors
TerminalID Guid Unique identifier
BrandName string Display name of the Terminal Brand
ModelName string Display name of the Terminal Model

EquipmentType

Defines a type of Equipment item (Gateway, Terminal, or Software).
FieldTypeDescription
EquipmentTypeID string Unique identifier
Name string Display name
Description string Optional description

EquipmentTypeQuery

Query for Equipment Types to search
FieldTypeDescription
SearchType string SearchType=["AnyValueIsPresent", "NoValueIsPresent", null]
SearchValues List<string>
OutputEquipment bool
OutputPeripherals bool

FieldValue

Represents the value assigned to a specific field in a Merchant Application.
FieldTypeDescription
FieldID Guid Unique identifier of the PackageField for which this is the value (the PackageField must be contained in the Fields list of the Package identified by the PackageID of the Application or ApplicationSave containing the FieldValues list containing this FieldValue)
Value string Value assigned to this PackageField in this Merchant Application

FrontEnd

Information to identify a BackEnd.
FieldTypeDescription
FrontEndId Guid Unique identifier
Name string Display name

Handoff

Information to complete a handoff of a Merchant Application to another system.
FieldTypeDescription
ApplicationID Guid The unique identifier of the Application being handed off
SystemName string Name of the system receiving the handoff
Pin string PIN needed to access the handed-off Application in the receiving system

Industry

Defines a Industry.
FieldTypeDescription
IndustryId string Unique identifier
Name string Display name
Description string Optional description

IndustryQuery

Query for Industry to search
FieldTypeDescription
SearchType string SearchType=["AnyValueIsPresent", "NoValueIsPresent", null]
SearchValues List<string>
Output bool

ItemQuery

Query for Items to search
FieldTypeDescription
SearchType string SearchType=["AnyValueIsPresent", "NoValueIsPresent", null]
SearchValues List<Guid>
OutputEquipment bool
OutputPeripherals bool

OwnershipQuery

Query for Ownership Types to search
FieldTypeDescription
SearchType string SearchType=["AnyValueIsPresent", "NoValueIsPresent", null]
SearchValues List<Guid>
Output bool

Package

A Package specifies metadata which defines the fields and equipment for submitting a Merchant Application.
FieldTypeDescription
PackageID Guid Unique identifier
Name string Display name
Description string Optional description
Fields IList<PackageField> List of all fields that can be included in a Merchant Application with this PackageID
EquipmentCounts IList<EquipmentCount> Total number of available Equipment items grouped by EquipmentType
PublishedRevisionID Guid? If this Package has been replaced by a later revision, the PackageID of the published revision

PackageDocTemplate

Information about a Template used to generate a Document that will be attached to a Merchant Application.
FieldTypeDescription
DocTemplateID Guid Unique identifier
DisplayName string Display name
Category string Category of Document generated from the Template
ToBeSigned bool If true, the generated Document will be included in the merchant signature process
IsDependentOnFieldData bool If true, the Document will only be generated when certain values are found in the Merchant Application
HasPassThroughFields bool If true, the Template requires one or more Passthrough Values to generate the Document
PassthroughList IList<string> Keys in the Passthrough Values whose values are put in the generated Document

PackageDocumentContent

A document (including the binary content) associated with a particular Package.
FieldTypeDescription
PackageID Guid Unique identifier of the associated Package
MimeType string Internet MIME type of the binary file data
Description string Optional short description of the Document's contents
FileSize int Size (in bytes) of the binary file
FileData byte[] Binary file image

PackageField

Defines an individual data entry Field of a Package.
FieldTypeDescription
FieldID Guid Unique identifier of the Field (consistent across Packages, such that the same FieldID always refers to the same data item, even if the rules and business logic differ between Packages)
DisplayName string Display name
Classification string A category to help understand how the Field is used
IsReadOnly bool If true, the Value of the FieldValue submitted for this Field must be the same as the DefaultValue of this PackageField
IsRequired bool If true, a FieldValue must be submitted for this Field and its Value must not be empty or attempting to submit the Application will result in a validation error (however, note that dynamic logic in our system may permit an empty value depending on other data in the Application)
DefaultValue string Optional default (initial) value for the Field Value
MinValue string Minimum value acceptable for the Field Value (this is validated for numeric fields when an Application is created or updated)
MaxValue string Maximum value acceptable for the Field Value (this is validated for numeric fields when an Application is created or updated)
MinLength string Minimum length acceptable for the Field Value (this is validated for text fields when an Application is created or updated)
MaxLength string Maximum length acceptable for the Field Value (this is validated for text fields when an Application is created or updated)
DataType string Acceptable type of data for the Field Value (string, boolean, byte, char, datetime, decimal, double, guid, int16, int32, int64)
Choices List<PackageFieldChoice> If specified, a list of the only acceptable choices for the Field Value (if IsMultiValue is true, the Value of the FieldValue submitted for this Field must be a comma-separated list of IDs of the selected PackageFieldChoices, if IsMultiValue is false, the Value must be the ID of the selected PackageFieldChoice
IsMultiValue bool True if multiple PackageFieldChoices can be selected for the Field Value, false if a single value must be selected
GroupID Guid Unique identifier of the Group within the Package containing the Field (intended as developer guidance, not for the user, to understand the logical Field hierarchy used by Paysafe)
SectionID Guid Unique identifier of the Section within the Package containing the Group (intended as developer guidance, not for the user, to understand the logical Field hierarchy used by Paysafe)
InputMask string Optionally specifies an input mask that, when present, indicates the format that the system expects the data to be in.
ValidationRegEx string Optionally specifies a RegEx that, when present, the system will use to validate the data. If the input data does not match the RegEx then a validation error will be returned. Please note that this RegEx is written for the Microsoft .NET RegEx interpreter.

PackageFieldChoice

Defines an individual valid choice (selection) associated with a specific PackageField
FieldTypeDescription
ID string Unique identifier
Name string Display name

PackageInfo

Basic information for an item in a list of Packages.
FieldTypeDescription
PackageID Guid Unique identifier
Name string Display name
Description string Optional description

PackageLegal

Legal Terms and Conditions for a Package.
FieldTypeDescription
PackageID Guid Unique identifier of the Package
LegalText string Legal text for the Package or Application (as a property of ApplicationLegal, this is the actual legal text, as a property of PackageLegal, it may contain placeholder tokens that will be replaced for each Application depending on data in that Application
Information about a URL that will initiate a Merchant Application with a particular Package for a particular SalesRep.
FieldTypeDescription
LinkID Guid Unique identifier
Description string Optional description
LinkUrl string URL for initiating a new Merchant Application
PackageID Guid Unique identifier of the Package that will be used for the new Merchant Application
SalesRepID Guid Unique identifier of the SalesRep who will be associated with the new Merchant Application

PassthroughValue

A Key/Value pair a partner can use to provide custom data to be printed on an MPA or other Document.
FieldTypeDescription
Key string Unique key (often a PDF field name) for the passthrough value
Value string Value to be printed in the Document for the PDF field tied to the Key

PaymentProcessor

Defines a Payment Processor identity that along with associated identity of front end and back end.
FieldTypeDescription
PaymentProcessorId Guid Unique identifier
BackEndId Guid Unique identifier
FrontEndId Guid Unique identifier

PaymentProcessorQuery

Query for PaymentProcessors to search
FieldTypeDescription
SearchType string SearchType=["AnyValueIsPresent", "NoValueIsPresent", null]
SearchValues List<Guid>
Output bool

PeripheralNameQuery

Query for PeripheralName to search
FieldTypeDescription
SearchType string SearchType=["AnyValueIsPresent", "NoValueIsPresent","BeginsWithAnyValue", "DoesNotBeginWithAnyValue","ContainsAnyValue", "DoesNotContainAnyValue", null]
SearchValues List<string>
Output bool

SalesRep

Identifies a single Sales Representative associated with the partner.
FieldTypeDescription
SalesRepID Guid Unique identifier
SalesNumber string Sales Number for the Representative
Name string Display name

ValidationResult

See the ValidationResult data structure in the Errors & Validation Results section.