Developer API Reference
Service Information Data Elements
The following Service Information data elements are associated with the ‘Preparing the Application to Transact’ process.
Contains merchant address information. This is a required element.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| X | City | City | String |
| X | CountryCode | Country - Maps to the TypeISOCountryCodeA3 enumeration. | Enum |
| X | PostalCode | Postal Code | String |
| X | StateProvince | State or Province - Maps to the TypeStateProvince enumeration. | Enum |
| X | Street1 | Street Address Line 1 | String |
| Optional | Street2 | Street Address Line 2 | String |
ApplicationData includes information about the application that must be supplied to the Service Information endpoint prior to transacting. This is a required element.
ApplicationData is returned by the following Service Information operation signatures for GetApplicationData.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| X | ApplicationAttended | Indicates if the application is attended or unattended. | Boolean |
| X | ApplicationLocation | Location of the application relative to the merchant. | Enum |
| X | ApplicationName | Name of the application. | String |
| Conditional* | DeveloperId | Developer or Third-Party Processor Identifier (TPP ID) - *Required if provided by an application certification entity. | String |
| Optional | DeviceSerialNumber | The serial number located on the physical device used to acquire payment account data. | String |
| Optional | EncryptionType | The encryption block used by the card reader. | Enum |
| X | HardwareType | The device running the application. | Enum |
| X | PINCapability | Indicates cardholder Personal Identification Number (PIN) functionality is supported. | Enum |
| X | PTLSSocketId(alsostring value) | Unique identifier issued to certified software applications. Note: All subsequent transaction requests pass this value as applicationProfileId. | String |
| X | ReadCapability | The device setting for reading cardholder data. | Enum |
| X | SerialNumber | Serial number of the application as defined by the developer. Unique per installed instance of the application. | String |
| X | SoftwareVersion | Software version as defined by the application developer. | String |
| X | SoftwareVersionDate | Software version date as defined by the application developer. | DateTime |
| Conditional* | VendorId | Vendor Identifier - *Required if provided by application certification entity. | String |
PTLSSocketId
IMPORTANT! Make sure no spaces are included when copying and pasting the PTLSSocketId string.
Contains information specific to the Bankcard Processing service class for merchants using the application. This class is required for merchants using Credit Card and PIN Debit services.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| Conditional* | ABANumber | Identifies the merchant to a direct debit switch. * Required when provisioned by the service provider. | String |
| Optional | AcquirerBIN | Acquirer Bank Identification Number - Identifies the merchant acquiring bank. Typically provisioned by the service provider. | String |
| Optional | AgentBank | Agent Bank Identifier - Typically provisioned by the service provider. | String |
| Optional | AgentChain | Agent Chain Identifier - Typically provisioned by the service provider. | String |
| Optional | Aggregator | Identifies the merchant as an aggregator - Typically provisioned by the service provider. If not present, the default value is 'false'. | Boolean |
| Optional | ClientNumber | Client number - Typically provisioned by the service provider. | String |
| X | IndustryType | The industry type for the transaction. This value is saved in theMerchantProfile (default) and cannot be overridden on individual transactions. | Enum |
| Conditional* | Location | Unique identifier for the merchant location. *Required if provisioned by the service provider. | String |
| Optional | MerchantType | Merchant type - Typically provisioned by the service provider. | String |
| Conditional* | PrintCustomerServicePhone | Used to determine if the customer service telephone number is printed on a customer transaction receipt. *Required for MOTO transactions. | Boolean |
| Optional | QualificationCodes | Qualification codes - Typically provisioned by the service provider. | String |
| Conditional* | ReimbursementAttribute | Designates the reimbursement fee applicable to the transaction. *Required if provisioned by the service provider. | String |
| Conditional* | SecondaryTerminalId | Additional transaction device identifier. *Required if provisioned by the service provider. | String |
| Conditional* | SettlementAgent | Identifies the merchant settling agent to direct debit networks. *Required if provisioned by the service provider. | String |
| Conditional* | SharingGroup | Provides a list of debit and EBT networks for a Point-of-Sale (POS) system to access. *Required if provisioned by the service provider. | String |
| X | SIC | Standard Industry Code used to identifie the merchant industry classification. May be provisioned by the service provider. | String |
| Conditional* | StoreId | Unique merchant store identifier. *Required if provisioned by the service provider. | String |
| Conditional* | TerminalId | Transaction device identifier often referred to as Terminal Number or Terminal Id (TID). *Required if provisioned by the service provider. | String |
| Conditional* | TimeZoneDifferential | Timezone of the merchant location and the Daylight Savings Time observation status. *Required if provisioned by the service provider. | String |
Contains information specific to the Electronic Checking service class for the merchant using the application. This is a conditional class, required if one or more of the data elements are required by the service provider.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| X | OriginatorID | Unique identifier representing the ACH originator in the service provider system. Typically provisioned by the service provider. | String |
| Optional | ProductId | Product Identifier. Typically provisioned by the service provider. | String |
| Optional | SiteId | Site Identifier. Typically provisioned by the service provider. | String |
Contains information returned to the application with details about the Bankcard service(s) configured.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| Optional | AlternativeMerchantData | Indicates the service supports displaying AlternativeMerchantData on accountholder statements. Subject to Issuer discretion. | Boolean |
| X | AutoBatch | Indicates the service supports AutoBatch. | Boolean |
| X | AVSData | Address Verification Services supported by the service. | Object |
| Conditional* | CutoffTime | The cut-off time for new transactions to be included in the daily automated batch (when supporting AutoBatch). *Required if the service supports AutoBatch. | DateTime |
| X | EncryptionKey | Public key used for encrypting payment account data. | String |
| X | ManagedBilling | Indicates the service supports Managed Billing. | Boolean |
| X | MaximumBatchItems | Maximum number of transactions to include in a single batch. | Long |
| Optional | MaximumLineItems | Maximum number of line items to include when sending Level 3 line item data. | Long |
| X | MultiplePartialCapture | Indicates the service supports multiple partial captures of a single authorization amount. | Boolean |
| X | Operations | The Transaction Processing Bankcard operations supported by the service. | Object |
| X | PurchaseCardLevel | Indicates the highest level of purchase card data supported by the service. Level 3 support is inclusive of Level 2 data and Level 2 support is inclusive of Level 1 data. | Enum |
| X | ServiceId | Unique service identifier. | String |
| X | ServiceName | Service name. | String |
| X | Tenders | Tenders supported by the service. | Object |
Contains a collection of Stored Value-specific services. The service is required if Stored Value transaction processing is supported.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| X | Operations | The Transaction Processing Stored Value operations supported by the service. | Object |
| Conditional* | SecureMSRAllowed | Indicates support for card data collected from a magnetic stripe and protected by an encrypting card reader. *Required when SecureMSRAllowed = 'true'. At least one of the following must be providedCardData, PaymentAccountDataToken or SecurePaymentAccountData must be provided. |
|
| X* | ServiceId | Unique Service Identifier. | String |
| X | ServiceName | Service Name. | String |
| X | Tenders | Tenders supported by the service. | Object |
Contains information specific to the Bankcard Processing service class for the merchant using the application. The service is required for merchants using Credit Card and PIN Debit services.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| Optional | AgentChain | Agent Chain Identifier. Typically provisioned by the service provider. | String |
| Optional | ClientNumber | Client number. Typically provisioned by the service provider. | String |
| X | IndustryType | The industry type for the transaction. Saved in the MerchantProfile (default) but may be overridden on each transaction. | Enum |
| X | SIC | Standard Industry Code used to identify the merchant industry classification. May be provisioned by the service provider. | String |
| Conditional* | StoreId | Unique merchant store identifier. *Required if provisioned by the service provider. | String |
| Conditional* | TerminalId | Transaction device identifier - Often referred to as Terminal Number or Terminal ID (TID). *Required if provisioned by the service provider. | String |
Contains information specifying the Address Verification System (AVS) fields. The service may be required by the service provider.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| Conditional* | CardholderName | Indicates when Cardholder Name is required for AVS. *Required if BankcardServiceAVSData is not null. |
Boolean |
| Conditional* | City | Indicates if City is required for AVS. *Required if BankcardServiceAVSData is not null. |
Boolean |
| Conditional* | Country | Indicates if Country is required for AVS. *Required if BankcardServiceAVSData is not null. |
Boolean |
| Conditional* | Phone | Indicates if cardholder Phone Number is required for AVS. *Required if BankcardServiceAVSData is not null. |
Boolean |
| Conditional* | PostalCode | Indicates if Postal Code is required for AVS. *Required if BankcardServiceAVSData is not null. |
Boolean |
| Conditional* | StateProvince | Indicates if State or Province is required for AVS. *Required if BankcardServiceAVSData is not null. |
Boolean |
| Conditional* | Street | Indicates if Street Address is required for AVS. *Required if BankcardServiceAVSData is not null. |
Boolean |
Contains a collection of Bankcard-specific services. The service is required if Bankcard is supported.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| X | BankcardService | Contains detailed configuration information for Bankcard service(s). | Object |
| X | ElectronicCheckingService | Contains detailed configuration information for Electronic Checking service(s) | Object |
Contains information sent with all Bankcard transactions. Can be overridden on a transaction basis. This is a required element.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| Optional | CurrencyCode | Merchant currency code as defined by the International Standards Organization (ISO). Maps to the TypeISOCurrencyCodeA3 enumeration. | Enum |
| Optional | CustomerPresent | Cardholder presence relative to the point-of-service. | Enum |
| Optional | EntryMode | DEPRECATED: This must be set on each individual transaction. Indicates the method for retrieving the was retrieved. Indicates that the card data was manually collected when authorized with stored card data, either locally or with a PaymentAccountDataToken. | Enum |
| Optional | RequestACI | Authorization Characteristics Indicator - Identifies the request as potential qualifier for the Visa CPS or MasterCard Merit programs. | Enum |
| Optional | RequestAdvice | Indicates if advice on declined recurring payment transactions is included. | Enum |
Contains merchant data required across all supported service classes. In single-merchant applications, a merchantProfileId must be saved for the merchant. In multi-merchant applications, a unique merchantProfileId is required for each merchant.
Once saved, the IsMerchantProfileInitialized operation can be invoked to verify a specific merchant profile is saved. Upon successful verification, the application passes the unique merchantProfileId with all subsequent transactions.
MerchantProfile is returned by the following Service Information operation signatures:
GetMerchantProfile, GetMerchantProfiles, GetMerchantProfilesByProfileId & ValidateMerchantProfile
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| X | LastUpdated | Last Updated date for the current merchant profile. Calling GetMerchantProfiles returns this value. |
DateTime |
| X | MerchantData | Contains general data for a merchant that is used across all service classes. Maps to MerchantProfileMerchantData. | Object |
| Optional | ProfileId | Unique identifer for the merchant profile. Referred to as merchantProfileId in transaction processing operations. | String |
| Conditional* | ServiceId | The merchant service provider service ID. *Required when the service key supports more than one Bankcard service. A merchant profile should be saved for each service provider. | String |
| X | ServiceName | The name of the service where the profile is saved. Calling GetMerchantProfiles return this value. |
String |
| X | TransactionData | Allows a merchant profile to be saved with transaction data defaults. If this data does not change for each transaction, no override of the the values on the transaction is required. Maps to MerchantProfileTransactionData. | Object |
Contains merchant specific information. This is a required element.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| X | Address | Merchant address - Maps to AddressInfo. | Object |
| Conditional* | BankcardMerchantData | Additional merchant data for the Bankcard Processing service class including Credit Card and PIN Debit. *Required for merchants using Credit Card and PIN Debit services. | Object |
| Optional | CustomerServiceInternet | Merchant customer service web URL or email address. | String |
| Conditional* | CustomerServicePhone | Merchant customer service phone number. *Required for Bankcard MOTO transactions. | String |
| X | Language | Language used for the response text message. Maps to the TypeISOLanguageCodeA3 enumeration. | Enum |
| X | MerchantId | Merchant Identifier (MID). Provisioned by the service provider. | String |
| X | Name | Name of the merchant. May be provisioned. | String |
| Conditional* | Phone | Merchant local telephone number. *Required for Bankcard Ecommerce and MOTO transactions. | String |
| Optional | TaxId | Merchant federal (FED ID)or Value-Added Tax (VAT) identification number. | String |
Contains a list of merchant profiles. A minimum of one merchant profile is required.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| X | MerchantProfile | Contains all merchant data across all supported service classes. | Object |
Contains transaction-specific information associated with a particular merchant. This is a required element.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| X | BankcardTransactionDataDefaults | Contains information sent with all Bankcard transactions. Can be overridden at the transaction level when needed. | Object |
Contains transaction processing operations supported by the service.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| X | Adjust | Indicates the Adjust operation is supported. | Boolean |
| X | AuthAndCapture | Indicates the AuthorizeAndCapture operation is supported. | Boolean |
| X | Authorize | Indicates the Authorize operation is supported. | Boolean |
| X | Capture | Indicates the Capture operation is supported. | Boolean |
| X | CaptureAll | Indicates the CaptureAll operation is supported. | Boolean |
| X | CloseBatch | Defines the level of support for batch release functionality.Future Use. | Enum |
| X | Disburse | Indicates the Disburse operation is supported. | Boolean |
| X | ManageAccount | Indicates the ManageAccount operation is supported. | Boolean |
| X | ManageAccountById | Indicates the ManageAccountById operation is supported. | Boolean |
| X | QueryAccount | Indicates the QueryAccount operation is supported. | Boolean |
| X | QueryRejected | Indicates the QueryRejected operation is supported. | Boolean |
| X | ReturnById | Indicates the ReturnById operation is supported. | Boolean |
| X | ReturnUnlinked | Indicates the ReturnUnlinked operation is supported. | Boolean |
| X | Undo | Indicates the Undo operation is supported. | Boolean |
| X | Verify | Indicates the Verify operation is supported. | Boolean |
Contains supported service(s) information from the GetServiceInformation call. ServiceInformation is returned by the following Service Information operation signatures: GetServiceInformation
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| Conditional* | BankcardServices | Represents a collection of Bankcard-specific services. *Required if Credit Card or PIN Debit services are available. Maps to BankcardService. | Object |
| Expected | Workflows | Represents a collection of workflows. Maps to Workflow. | Object |
Contains supported payment tenders information from the GetServiceInformation call.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| X | BatchAssignmentSupport | Indicates level of BatchAssignment supported by the service. | Enum |
| Optional | CredentialsRequired | Specifies if user credentials are required for the service. If not present defaults to 'false'. | Boolean |
| X | Credit | Indicates support for the Credit Card tender. | Boolean |
| X | CreditAuthorizeSupport | Indicates the level of credit authorization support on a service. Maps to the CreditAuthorizeSupportType enumeration. | Enum |
| X | CreditReturnSupport | Indicates the types of Return transactions supported by the service for Credit transactions. Maps to the CreditReturnSupportType enumeration. | Enum |
| CreditReversalSupportType | Specifies if Reversal is supported. | Enum | |
| Expected | PartialApprovalSupportType | Specifies if the service supports partial authorizations at the transaction level. If not present, defaults to 'DisabledAlwaysSupported'. | Enum |
| X | PINDebit | Indicates PIN Debit tender is supported. | Boolean |
| X | PINDebitReturnSupport | Indicates if Return is supported by the service for PIN Debit transactions. Maps to thePinDebitReturnSupportType enumeration. Defaults to 'Standalone'. | Enum |
| X | PINDebitUndoSupport | Indicates if Undo is supported by the service for PIN Debit transactions. Maps to the PINDebitUndoSupportType enumeration. | Enum |
| X | PINDebitUndoTenderDataRequired | Specifies if a new card swipe is required when performing an Undo on a PIN Debit card. | Boolean |
| X | PINlessDebit | Indicates support for Pinless Debit. | Boolean |
| X | QueryRejectedSupport | Indicates if date ranges are supported for QueryRejected on a service. Maps to the QueryRejectedSupportType enumeration. | Enum |
| X | TrackDataSupport | Indicates the types of track data supported. Maps to the TrackDataSupportType enumeration | Enum |
Represents a collection of workflows returned by the GetServiceInformation operation in the ServiceInformation object.
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| Expected | Name | The workflow name. | String |
| Expected | ServiceId | The Service Id corresponding to the Bankcard or Electronic Checking service within the workflow. | String |
| Expected | WorkflowId | The Workflow Identifier. | String |
| Expected | WorkflowServices | Represents a collection of workflow services. Maps to WorkflowService. | Object |
Contains detailed information about the configured workflow service(s).
| Required | Parameter | Description | Data Type |
|---|---|---|---|
| Expected | Ordinal | The ordinal position within the workflow. | Integer |
| Expected | ServiceId | The Service Id corresponding to the Bankcardor Electronic Checking service within the workflow. | String |
| Expected | ServiceName | The Service Name. | String |
| Expected | ServiceType | The Service Type. | String |