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 programatic 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 that our partners may need. There are 3 primary usage scenarios for working with the API which are listed below. There is additional documentation (including diagrams) for each of these workflows that describes how the partner would utilize the API to implement the workflow. Please be sure to click the below link(s) that may apply to your needs. Please be sure to click one or more of the below links to see this important additional documentation.

Documented Usage Scenarios:


Application Workflow

A Merchant Application is created via the API by calling Create Application and passing in an ApplicationSave data structure. 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 Application unique identifier will be returned that enables further management of that application. To modify information associated with the application send a fully populated ApplicationSave data structure to the 'Update Application' method 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, iPayment’s web application. The 'merchanthandoff' method is used to email the Merchant an iEntry URL, login credentials and instructions on completing the Application submission process. If the required information is not present the MerchantCompletionEmail method will return a ValidationResults 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), the 'presubmission' method must be called 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, 'presubmission' will return a ValidationResults structure. The Application will also change state to 'Waiting for a Signed Contract'. Calling 'Update' is no longer allowed, 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 calling the 'finalsubmission' method. The Application will change state again to 'Submitted' and be queued for processing by iPayment. If an error occurs, 'finalsubmission' will return 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.



API Authentication

All calls to the API REST endpoints must be made using Secure HTTP (HTTPS) and authenticated by including an API Key and API Secret which 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 fullful 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 provides a context that applications exist within by defining the fields, equipment, legal terms etc. Packages are specific to and designed for each partner, the rules and settings in any given package are determined by the business working with the partner. The packages available to the partner is obtained by calling Package List. The specifics for an individual Package are obtained by calling Package Detail. The equipment (gateways, software and terminals) available for a package is obtained by additional method calls (see the Swagger documentation for a full list).

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 EquipmentItem 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 (see the EquipmentTypes lookup list). The list of gateways, terminals and software available for a package can be obtained by additional API method calls which return lists suitable for display and selection. Each equipment item being ordered must have a payment processor specified and can specify additional information via FieldValues if needed. Each piece of Equipment can also optionally specify Peripherals to be ordered for it. The available choices can be obtained by calling the List of Gateway Processors, List of Gateway Peripherals, List of Terminal Processors, List of Terminal Peripherals, List of Software Processors or List of Software Peripherals. If the Peripheral being ordered has options or needs additional information FieldValues can be populated for the individual Peripherals.


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. Which gateways, terminals and software are available for inclusion is determined by the application package being used. Various methods, described below, are provided to obtain these lists. Payment Processors and Peripherals are specified as part of an individual equipment item. The list of available processors and peripherals is determined by both the package and the item it’s being associated with.

Gateways

The list of gateways available for a package is always obtained by calling the PackageGateways method. This list should be displayed to the user for selection. If a gateway is chosen by the user they should then be prompted to select a payment processor and optional peripherals. The lists for these to be displayed are obtained by calling EquipmentGatewayProcessors and EquipmentGatewayPeripherals methods. Once user selection of a gateway has been completed an additional EquipmentItem record should be added to the ApplicationSave data structure for calling either Application Create or Application Update. When adding the EquipmentItem record use the GatewayID as the EquipmentID.

Terminals and Software

Adding terminals and software to an application can be done the same way as adding gateways by using PackageTerminals, PackageSoftware, EquipmentTerminalProcessors, EquipmentTerminalPeripherals, EquipmentSoftwareProcessors and EquipmentSoftwarePeripherals methods. However since terminals and software could potentially contain many items these lists can be further broken down into a 2 step process of Brand then Model for terminals and Title then Version for software. To obtain the list of terminal brands the PackageTerminalBrands method is used. Once a brand has been chosen the models under that brand are obtained by calling PackageTerminalBrandModels and passing in the terminal brand’s ID. The items and IDs returned by the List of Package Terminal Models are the same as those returned by List of Package Terminals, but filtered to only include ones for the indicated brand. The two step software selection process works the same using the PackageSoftwareTitles and PackageSoftwareTitleVersions methods.


Sales Representatives

Every Merchant Application must specify a representative that will credit for the sale. The list of representatives associated with the partner can be obtained from the Agent resources (which returns a list of SalesRep data structures). A representatives can be 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 structure that contains one or more ValidationResult objects.

When an application’s data is saved by calling Create Application or Update Application, its individual field values are validated to ensure they are acceptable. The save operation will not succeed if any field values are invalid.

These two methods 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. When calling Update all Field Values, Principals, Equipment, etc. must be specified in every call because the entire contents of the Application is replaced with the ApplicationSave structure sent to the Update method. Fields that are marked as required (via IsRequired) must have a value before the Signature method is called. The application is checked against the complete set of validation rules and any omissions or changes required returned via a ValiationResults structure when the Signature or Validate methods are called for the Application.

ValidationResults (DTO)

Defines an error message describing a validation failure associated with a merchant's application
FieldTypeDescription
ApplicationID String (GUID) If the application is saved returns its unique identifier.
Results List of ValidationResult List containing messages returned by the attempted action.

ValidationResult (DTO)

Contains a message relating to data in the Merchant's Application (typically describes a validaiton that failed).
FieldTypeDescription
ReferenceType string Optional. Indicates the application eleemnt type that ReferenceID refers to.
ReferenceID Guid Optional unqiue identifier of the element within the merchant's Application that this validation result pertains to.
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
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 convienience 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.

Application

Represents an application submittied by a merchant to initiate credit card processing.
FieldTypeDescription
ApplicationID Guid Unique identifier of the merchant Application.
SalesRepID Guid Unique identifier of the SalesRep who is associated with the application (obtained from the SalesReps lookup resource).
PackageID Guid Unique identifier of the Package (obtained from the Packages resource) that defines the application's metadata.
ApplicationStatusID string Unqiue identifier of the ApplicationStatus (obtained from the Lookup resource) that indicates the application's current state in the workflow.
HasSignature bool True if the Merchant has signed or otherwise accepted the MPA
CreatedWhen DateTime Date & time the application was created
UpdatedWhen DateTime Date & time the application was last changed / saved
FieldValues List of FieldValue List of values for the applicatoin's fields
PassthroughValues List of PassthroughValue Optional passthrough Key/Value pairs for the application
Principals List of ApplicationPrincipal List of Principals for the business.
Equipment List of ApplicationEquipment List of equipment included (along with associated configuration and peripherals).
Documents List of ApplicationDocument List of documents that are associated with the application.

ApplicationDocument

Represents a document (file) associated with a merchant's application
FieldTypeDescription
DocumentID Guid Uniuqe identifier of the attached document
DocumentTypeID string Unqiue identifier of the DocumentType (obtained from the Lookup resource) that indicates the type, format and purpose of the document.
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 string MIME Type of the file

ApplicationEquipment

Specifies a piece of equipment and its configuration information.
FieldTypeDescription
EquipmentTypeID string Unqiue identifier of the EquipmentType (obtained from the Lookup resource) that indicates what type of equipment (gateway, terminal or software) is being specified.
EquipmentID Guid Unqiue identifier of the equipment item. Information about equipment can be obtained via the Packages resource.
ProcessorID Guid Unqiue identifier of the Processor to be associated with the equipment. Information about equipment can be obtained via the Packages resource.
FieldValues List of FieldValue List of field/value pairs that specifies information about and configuration for the equipment item.
Peripherials List of ApplicationEquipmentPeripheral Optionally specifies peripherals to be included with the equipment item.

ApplicationEquipmentPeripheral

Specifies an equipment peripheral and its configuraiton information.
FieldTypeDescription
PeripheralID Guid Unqiue identifier of the peripheral item. Information about equipment can be obtained via the Packages resource.
FieldValues List of FieldValue Field/value pairs that specifies information about and configuration for the equipment item.

ApplicationInfo

Provides high level information and meta data about a merchant's application
FieldTypeDescription
ApplicationID Guid Unique identifier of this merchant Application.
SalesRepID Guid Unique identifier of the SalesRep who is associated with the application (obtained from the SalesReps lookup resource).
PackageID Guid Unique identifier of the Package (obtained from the Packages resource) that defines the application's metadata.
ApplicationStatusID string Unqiue identifier of the ApplicationStatus that indicates the application's current state in the workflow.
HasSignature bool True if the Merchant has signed or otherwise accepted the MPA
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 (obtained from the Packages resource).
LegalText string Legal text generated specifically for the Application. Please note that the legal text obtained from the Package resource (PackageLegal) may contain place-holder tokens for information that is specific to individual applications.

ApplicationPrincipal

A set of Field/Value pairs that specify information about a person related to the business.
FieldTypeDescription
FieldValues List of FieldValue List of field/value pairs that specify information about the Principal.

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 (obtained from the SalesReps lookup resource).
PackageID Guid Unique identifier of the Package (obtained from the Packages resource) that defines the application's metadata.
UserIpAddress string IP address of the remote user if applicable.
FieldValues List of FieldValue List of values for the applicatoin's fields
PassthroughValues List of PassthroughValue Optional passthrough Key/Value pairs for the application
Principals List of ApplicationPrincipal List of Principals for the business.
Equipment List of 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

DocumentType

Defines a type of Document that can be attached to a mercahnt's Application
FieldTypeDescription
DocumentTypeID string Unique identifier
Name string Display name
Description string Optional description
IsReadOnly bool If true Documents of this type can not be added.

EquipmentCount

Provides the total number of items available of a specific Equipment Type.
FieldTypeDescription
EquipmentTypeID string Unqiue identifier of the EquipmentType (obtained from the Lookup resource) that indicates what type of equipment (gateway, terminal or software) is being specified.
Quantity int Quantity of items available.

EquipmentType

Defines a class of Equipment item (such as Gateways, Terminals, Software, etc)
FieldTypeDescription
EquipmentTypeID string Unique identifier for indicating a type of equipment (gateway, processor or software).
Name string Display name
Description string Optional description

FieldValue

Represents the value assigned to a specific field in a merchant application
FieldTypeDescription
FieldID Guid Unqiue identifier that identifies the PackageField (obtained from the Packages resource).
Value string Value assigned to this field in the merchant application

Package

A Package specifies metadata which defines the fields and equipment for submitting a merchant application.
FieldTypeDescription
PackageID Guid Unique identifier for the Package.
Name string Display name
Description string Optional description
Fields List of PackageField List of all fields that can be included in a merchant application that is assigned to this PackageID.
EquipmentCounts List of EquipmentCount Provides the total number of available items grouped by Equipment Type.

PackageField

Defines an individual data entry field of a Package
FieldTypeDescription
FieldID Guid Uniuqe identifier of the Field. Please note that these identifiers are consistent across Packages in that the same FieldID will always refer to the same data item (though the rules and business logic for that field may differ between packages).
DisplayName string The name of the field to be displayed in the Application.
Classification string Provides metadata useful to a developer for determining how the field is used.
IsReadOnly bool If true the field value cannot be edited and must be submitted with the DefaultValue in the Application
IsRequired bool Required field validation is not performed during create and update operations, required field validation only occurs when attempting to submit and application. This is a guideline to help direct the programmer but please note that some fields have dynamic logic in our back end that change when they are or are not required.
DefaultValue string Optional default (initial) value for the field
MinValue string Only applies only to decimal/integer data types. If a value is specified it indicates the lowest number acceptable (inclusive of the MinValue). This will be validated by the API when calling Create or Update and will result in the operation failing if the validation does not pass.
MaxValue string Only applies only to decimal/integer data types. If a value is specified it indicates the highest number acceptable (inclusive of the MaxValue). This will be validated by the API when calling Create or Update and will result in the operation failing if the validation does not pass.
MinLength string Only applies only to string data types. If a value is specified it indicates the shortest length acceptable. This will be validated by the API when calling Create or Update and will result in the operation failing if the validation does not pass.
MaxLength string Only applies only to string data types. If a value is specified it indicates the longest length acceptable. This will be validated by the API when calling Create or Update and will result in the operation failing if the validation does not pass.
DataType string Indicates the data type for values Name indicating the type of data to be input (string, boolean, byte, char, datetime, decimal, double, guid, int16, int32, int64)
Choices List of PackageFieldChoice Certain fields have pre-defined values that are the only acceptable values for a field. For those fields this will contain a list of PackageFieldChoice DTO structures listing the acceptable values. The ID of the selected choice should be used for the field's value. If IsMultiValue is true multiple choices can be specified by specifying multiple IDs in the value separated by commas.
IsMultiValue bool True if multiple Choices can be specified in the field value. If false only a single choice can be specified.
SectionID Guid Intended for use during development (not intended for display to users). This field is provided to help developers understand how fields relate to each other within the hierarchy used by iPayment. Sections are separate sections of the application while Groups are sub-sets within sections.
GroupID Guid Intended for use during development (not intended for display to users). This field is provided to help developers understand how fields relate to each other within the hierarchy used by iPayment. Sections are separate sections of the application while Groups are sub-sets within sections.

PackageFieldChoice

Defines an individual valid choice (selection) associated with a specific Package Field.
FieldTypeDescription
ID string Unique identifier for the choice
Name string Display name for the choice

PackageLegal

Legal Terms and Conditions for a Package.
FieldTypeDescription
PackageID Guid Unique identifier of the Package (obtained from the Packages resource).
LegalText string Legal text for the Package. Please note that this may contain may contain place-holder tokens for information that is specific to individual applications. To obtain the actual legal text that pertains to a specific merchant application please see ApplicationLegal.

PassthroughValue

Represents a Key/Value pair for use by external partners
FieldTypeDescription
Key string Unique key / field name for the passthrough value (within the local context)
Value string Value to be passed through to the external partner.

SalesRep

Defines a single Sales Representative associated with the caller's API login.
FieldTypeDescription
SalesRepID Guid Unique identifier for the Sales Representative.
SalesNumber string Sales Number associated with the Representative.
Name string Display name of the Sales Representative.

ValidationResult

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

ValidationResults

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