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:
-
Batch Mode Workflow
- This would apply to partners who use the API to submit applications after they have gathered all of the necessary information.
-
Paysafe Web Handoff Workflow
- This applies to partners who use the API to initiate new merchant applications but don't include all necessary information. The merchant completes
the application process interactively using Paysafe's web application.
-
Interactive Partner GUI Workflow
- Partners who have or build their own interactive GUI for interacting with the merchant and use the API as a backend to store and work with in-progress applications.
Application Workflow
A Merchant Application is created via the API by POSTing an ApplicationSave data structure to /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 /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 /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 /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
/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 /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.
The following summarizes the three types of Application create functions:
-
Physical Signature
In this process the Merchant Processing Agreement must be downloaded and signed by the Merchant and then uploaded to finalize submission.
-
Virtual Signature
If the merchant entered their information using an interactive computer system (such as your own web application) you may be able to use our "click to agree" capability to have the merchant virtually sign the Merchant Processing Agreement.
The Merchant does not need to directly interact with our systems to complete submission, nor do they have to physically sign an agreement.
Instead they must have indicated on your systems that they agree to process the request.
-
Send to Merchant (Merchant Handoff)
The Merchant handoff function allows the Application to be part completed by the partner before handing a link to the Merchant that allows the Merchant to finalize submission.
The Merchant does not need to physically sign our Merchant Processing Agreement.
Instead the Merchant agrees to process the request by checking the "Terms & Conditions" checkbox before clicking Submit.
The flow of the three types of Application submission are depicted in the diagram below
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:
- ApplicationInfo - Mainly used to return search results. This DTO specifies the main information about an application without the details.
- Application - Provides all information related to an application including the Field Values, Principals, Equipment, Documents, etc.
- ApplicationSave - This DTO is used when posting requests to create or update an application.
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 /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 /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 /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 /v2/packages/{PackageID}/terminals and
/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 /v2/packages/{PackageID}/terminalbrands provides the TerminalBrandID
that can be used in a GET to /v2/packages/{PackageID}/terminalbrands/{TerminalBrandID}, which returns the same list of
EquipmentTerminalModel as /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 /v2/packages/{PackageID}/softwaretitles provides the SoftwareTitleID
that can be used in a GET to /v2/packages/{PackageID}/softwaretitles/{SoftwareTitleID}, which returns the same list of
EquipmentSoftwareVersion as /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 /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 /v2/applications to create a new Application or /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
- /v2/packages/{PackageID}/gateways/{GatewayID}/processors,
- /v2/packages/{PackageID}/gateways/{GatewayID}/peripherals,
- /v2/packages/{PackageID}/terminals/{TerminalID}/processors,
- /v2/packages/{PackageID}/terminals/{TerminalID}/peripherals,
- /v2/packages/{PackageID}/software/{SoftwareID}/processors,
- /v2/packages/{PackageID}/software/{SoftwareID}/peripherals.
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 /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 /v2/applications to create a new Application or /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 /v2/applications/{ApplicationID}, it must include
every FieldValue, PassthroughValue, ApplicationPrincipal,
and ApplicationEquipment, in the Application, because /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 /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 /v2/applications/{ApplicationID}/virtualsignature or /v2/applications/{ApplicationID}/presubmission, all fields
marked as required (via IsRequired) must have a value. Those POSTs and the GET to /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
| Field | Type | Description |
|---|
| 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).
| Field | Type | Description |
|---|
| 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.
| Identifier | Data Type | Description |
|---|
| 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
| Field | Type | Description |
|---|
| AccessoryTypeId |
string |
|
| AccessoryId |
Guid? |
|
| AccessoryName |
string |
|
Application
Represents an Application submitted by a merchant to initiate credit card processing.
| Field | Type | Description |
|---|
| 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 /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 /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 /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.
| Field | Type | Description |
|---|
| 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 /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.
| Field | Type | Description |
|---|
| 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 /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.
| Field | Type | Description |
|---|
| 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 /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.
| Field | Type | Description |
|---|
| 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 /v2/lookups/equipmenttypes) |
| EquipmentID |
Guid |
Unique identifier of an Equipment item returned from a GET to /v2/packages/{PackageID}/gateways,
/v2/packages/{PackageID}/terminals, or /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 /v2/packages/{PackageID}/gateways/{GatewayID}/processors, /v2/packages/{PackageID}/terminals/{TerminalID}/processors,
and /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.
| Field | Type | Description |
|---|
| PeripheralID |
Guid |
Unique identifier of a Peripheral item returned from a GET to /v2/packages/{PackageID}/gateways/{GatewayID}/peripherals,
/v2/packages/{PackageID}/terminals/{TerminalID}/peripherals, or /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.
| Field | Type | Description |
|---|
| 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 /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 /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 /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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| SalesRepID |
Guid |
Unique identifier of the SalesRep who is associated with the Application
(the SalesRep is returned from a GET to /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 /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.
| Field | Type | Description |
|---|
| ApplicationStatusID |
string |
Unique identifier |
| Name |
string |
Display name |
| Description |
string |
Optional description |
BackEnd
Information to identify a BackEnd.
| Field | Type | Description |
|---|
| BackEndId |
Guid |
Unique identifier |
| Name |
string |
Display name |
BoardingStatus
| Field | Type | Description |
|---|
| 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
| Field | Type | Description |
|---|
| SearchType |
string |
SearchType=["AnyValueIsPresent", "NoValueIsPresent", null] |
| SearchValues |
List<Guid> |
|
| Output |
bool |
|
BrandNameQuery
Query for BrandNames to search
| Field | Type | Description |
|---|
| 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
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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 /v2/lookups/equipmenttypes) |
| Quantity |
int |
Quantity of items available |
EquipmentGateway
Basic information for an item in a list of Gateways.
| Field | Type | Description |
|---|
| GatewayID |
Guid |
Unique identifier |
| Name |
string |
Display name |
EquipmentGatewayDetail
Details about a Gateway.
| Field | Type | Description |
|---|
| 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
| Field | Type | Description |
|---|
| 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
| Field | Type | Description |
|---|
| SearchType |
string |
SearchType=["AnyValueIsPresent", "NoValueIsPresent","BeginsWithAnyValue", "DoesNotBeginWithAnyValue","ContainsAnyValue", "DoesNotContainAnyValue", null] |
| SearchValues |
List<string> |
|
| Output |
bool |
|
EquipmentOwnershipType
Information to identify a EquipmentOwnershipType.
| Field | Type | Description |
|---|
| EquipmentOwnershipTypeId |
Guid |
Unique identifier |
| Name |
string |
Display name |
EquipmentPeripheral
Information to identify and categorize a Peripheral.
| Field | Type | Description |
|---|
| 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 /v2/lookups/peripheraltypes) |
| Name |
string |
Display name |
EquipmentPeripheralType
Defines a type of Peripheral (such as pin pad, card reader, receipt printer, etc.).
| Field | Type | Description |
|---|
| PeripheralTypeID |
string |
Unique identifier |
| Name |
string |
Display name |
| Description |
string |
Optional description |
EquipmentProcessor
Information to identify a Processor.
| Field | Type | Description |
|---|
| ProcessorID |
Guid |
Unique identifier |
| Name |
string |
Display name |
EquipmentSearchQuery
Defines a query object that can be used to search equipments
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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).
| Field | Type | Description |
|---|
| EquipmentTypeID |
string |
Unique identifier |
| Name |
string |
Display name |
| Description |
string |
Optional description |
EquipmentTypeQuery
Query for Equipment Types to search
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| FrontEndId |
Guid |
Unique identifier |
| Name |
string |
Display name |
Handoff
Information to complete a handoff of a Merchant Application to another system.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| IndustryId |
string |
Unique identifier |
| Name |
string |
Display name |
| Description |
string |
Optional description |
IndustryQuery
Query for Industry to search
| Field | Type | Description |
|---|
| SearchType |
string |
SearchType=["AnyValueIsPresent", "NoValueIsPresent", null] |
| SearchValues |
List<string> |
|
| Output |
bool |
|
ItemQuery
Query for Items to search
| Field | Type | Description |
|---|
| SearchType |
string |
SearchType=["AnyValueIsPresent", "NoValueIsPresent", null] |
| SearchValues |
List<Guid> |
|
| OutputEquipment |
bool |
|
| OutputPeripherals |
bool |
|
OwnershipQuery
Query for Ownership Types to search
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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
| Field | Type | Description |
|---|
| ID |
string |
Unique identifier |
| Name |
string |
Display name |
PackageInfo
Basic information for an item in a list of Packages.
| Field | Type | Description |
|---|
| PackageID |
Guid |
Unique identifier |
| Name |
string |
Display name |
| Description |
string |
Optional description |
PackageLegal
Legal Terms and Conditions for a Package.
| Field | Type | Description |
|---|
| 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 |
PackageLink
Information about a URL that will initiate a Merchant Application with a particular Package for a particular SalesRep.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| PaymentProcessorId |
Guid |
Unique identifier |
| BackEndId |
Guid |
Unique identifier |
| FrontEndId |
Guid |
Unique identifier |
PaymentProcessorQuery
Query for PaymentProcessors to search
| Field | Type | Description |
|---|
| SearchType |
string |
SearchType=["AnyValueIsPresent", "NoValueIsPresent", null] |
| SearchValues |
List<Guid> |
|
| Output |
bool |
|
PeripheralNameQuery
Query for PeripheralName to search
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
|---|
| 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.
