Developer API Reference

Service Information Data Elements

The following Service Information data elements are associated with the ‘Preparing the Application to Transact’ process.

AddressInfo

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

Application Data

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.

 

BankcardMerchantData

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

ElectronicCheckingMerchantData

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

BankcardService

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

StoredValueService

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

StoredValueMerchantData

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

BankcardServiceAVSData

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

BankcardService

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

BankcardTransactionDataDefaults

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

MerchantProfile

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

MerchantProfileMerchantData

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

MerchantProfiles

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

MerchantProfileTransactionData

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

Operations

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

Operations

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

Tenders

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

Workflow

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

WorkflowService

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