swagger: '2.0' schemes: - https host: emv.payroc.com basePath: /services/api.asmx/ info: description: | # 1. IBX Services ## IBX Services WSDLs The IBX services can be accessed via the following URLs - https://gateway.ibxpays.com/ws/transact.asmx?wsdl - https://gateway.ibxpays.com/ws/cardsafe.asmx?wsdl - https://gateway.ibxpays.com/ws/customfields.asmx?wsdl - https://gateway.ibxpays.com/vt/ws/trxdetail.asmx?wsdl - https://gateway.ibxpays.com/vt/ws/recurring.asmx?wsdl ## IBX Services **Transact WSDL** provides information for the following transaction processing services: - ProcessCreditCard - ProcessDebitCard - ProcessCheck - ProcessEBTCard - ProcessGiftCard - ProcessSignature - ProcessCheck (Recurring Billing) - ProcessCreditCard (Recurring Billing) **TRXdetail WSDL** provides information for the following report processing services: - GetCardTrx - GetCardTrxSummary - GetCheckTrx - GetOpenBatchSummary **Recurring WSDL** provides information for the following recurring billing processing services: - ManageCustomer - ManageCreditCardInfo - ManageCheckInfo - ManageContract - ManageContractAddDaysToNextBillDt - AddRecurringCreditCard **CardSafe WSDL** provides information for the following storing credit card information processing services: - StoreCard - ProcessCreditCard **CustomFields WSDL** provides information for adding custom fields programmatically to a gateway account: - AddCustomField # 2. IMPLEMENTATION GUIDE # 2.1. SOAP The SOAP interface is most easily accessed through a .NET application. If you are developing in .Net, simply add the URL of the web service – or of the specific service method – you are attempting to consume as a service reference in Visual Studio. Once you have added the service reference, Visual Studio will handle the bulk of the heavy lifting and will create a class for the web service and/or method you are attempting to access which will build the SOAP object for you and return a response in the form of an object. It is important to note that we use SSL accelerators in our infrastructure. If you are having trouble communicating with the web service check to see if the endpoint URL’s included in the WSDL file generated by the web reference are incorrectly set to ‘http://’ . If so simply change them to ‘https://’ in whatever IDE you are working in, and you should have no trouble communicating with the web service. If you are using a program language other than VB.NET or C#, and are not familiar with interacting with .NET web services, it is recommended that you integrate using HTTPS as it is far less complicated then building SOAP objects outside of an IDE, and will save a tremendous amount of time and headache. If you are familiar and comfortable using SOAP to consume .NET web services, navigate to the URL for each web service method you plan to consume for additional details regarding the XML SOAP schema. If you are not using a Microsoft .NET framework to access the services, refer to the cURL, PHP, Node.js and Ruby [Implementation Examples](#section/9.1.Implementation-Examples) for examples on how to use these services in alternative environments. Most integrators will only need to concern themselves with the ProcessCreditCard web service. However, if additional functionality is required, our web services have been labeled intuitively, and the functionality exposed in each service is implied in the title. The API is broken up into categories according to functionality to ease this further. If you have any development specific questions, please contact our technical support center at the following email address: support@ibxpays.com. # 2.2. Name-Value Pairs The Name-Value Pairs implementation relies on the .NET framework’s built in HTTP to SOAP translation layer. As a result, there are a few idiosyncracies that an integrator must be aware of when implementing using HTTPS. 1. The .NET framework is taking the HTTPS request and building a SOAP object using the fields that it receives. 2. As a result, regardless of whether or not a field’s VALUE is required, the field name must be sent along with the request. 3. Although this may seem counter intuitive, the .NET web service will simply build the SOAP object using only the fields that are passed to it. 4. If a field name is not included in the request, the SOAP object will be built without that parameter, thus resulting in an improperly formed SOAP object that will be rejected by the web service. 5. To avoid this, each field name must be sent even if you are not passing a value to the service. You must send the field EVEN if the API indicates that the field is not required, but send the field with a ‘NULL’ value. Eg; “CustomerName=” 6. Remember, the request MUST include all field names, but when deciding whether to send a value in a specific field you can rely on the API to indicate whether a specific field requires a value in order to return a valid result When calling a service using HTTPS, you must also use a slightly different URL. This URL is displayed for each web service in the API under the heading ‘Service Location’. Please make sure that when implementing using Name-Value Pairs over HTTPS that you are sending the request to the URL labeled ‘For standard HTTPS connections’. For additional detail regarding HTTPS GET or POST format, navigate to the service URL labeled ‘For SOAP connections and scroll down to view properly formed GET and POST requests for each service. Most integrators will only need to concern themselves with the ProcessCreditCard web service. However, if additional functionality is required, our web services have been labeled intuitively, and the functionality exposed in each service is implied in the title. The API is broken up into categories according to functionality type to ease this further. If you have any development specific questions, please contact our technical support center at the following email address: support@ibxpays.com Table of contents for test forms can be located at: https://gateway.ibxpays.com/ws/ # 3. Transaction Processing # 3.1. ProcessCreditCard This web service is used whenever a transaction is completed via customer credit card. ## Request ProcessCreditCard(UserName, Password, TransType, CardNum, ExpDate, MagData, NameOnCard, Amount, InvNum, PNRef, Zip, Street, CVNum, ExtData) ## Request Example Note: This example assumes that two [custom fields have been created](#section/8.1.-AddCustomField) (one a numeric the other a string). Remove the CustomFields XML if attempting to use without custom fields. ``` SmartPaymentsSoapClient transact = new SmartPaymentsSoapClient("SmartPaymentsSoap"); transactResponse = transact.ProcessCreditCard( "username", "password", "Sale", "4012888888881881", "1216", "", "Barney Rubble", "200", "666", "", "", "", "999", @"MANUAL3.852 18 Chocolate goodness " ); ``` ## Response AuthCode, ExtData, GetAVSResult, GetAVSResultTXT, GetCommercialCard, GetCVResult, GetCVResultTXT, GetStreetMatchTXT, GetZipMatchTXT, HostCode, Message, Message1, Message2, PNRef, RespMSG, Result ## Response Example ``` AuthCode "TAS202" string AuthorizedAmount null string Balance null string ExtData "InvNum=666,CardType=VISA" string GetAVSResult "0" string GetAVSResultTXT "Issuer did not perform AVS" string GetCVResult "M" string GetCVResultTXT "Match" string GetCommercialCard "False" string GetGetOrigResult "" string GetStreetMatchTXT "Service Not Requested" string GetZipMatchTXT "Service Not Requested" string HostCode "000000000926896" string HostURL "" string Message "" string Message1 "" string Message2 "" string PNRef "3413610" string ReceiptURL null string RespMSG "Approved" string Result 0 int ``` View [Transaction Response Fields.](#section/transaction-response-fields) ## ProcessCreditCard Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name | Description |-----|----- | UserName | User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service. | Password | Password associated with the user name provided. | TransType | Identifies the type of credit card transaction being made. | | Valid values are: | | - Sale – make a purchase using a credit card| | | - Auth – authorize the amount on a credit card| | | - Return – credits the card holder’s account | | - Void – undo an unsettled transaction | | - Force – force an Auth transaction in to the current batch (PostAuth) or place a transaction not processed through the payment server into the current batch (ForceAuth). Note: When using this transaction type for a ForceAuth, you must include an AuthCode under the ExtData parameter. | | - RepeatSale – perform a recurring billing or installment payment transaction| | | Processors supporting the restaurant adjustment function only: | | - Adjustment – used to modify an existing tip amount for an original sale To call the service | | Terminal-based processors only: | | - Capture – settle a single transaction in the current batch | | - Reversal – perform a manual full reversal on a credit card or repeat sale within 24 hours of the original transaction. See [Reversal Transactions.](#section/reverse) | CardNum |Credit card number used to uniquely identify the card owner’s account. Required on all swiped CC transactions| | ExpDate | Credit card date of expiration in MMYY format. |Required on all swiped CC transactions | | MagData | Track data encoded in the magnetic stripe of a credit card. The data will follow the following format: | Not required for CaptureAll | %B5149612222222229^FDCS/TEST CHECK CARD^12041011234567 | required for swiped/card present transactions | 440?;5149612222222229=12041011234567440? | | This parameter must contain the full magnetic read in order to be classified as a ‘card present’ transaction | NameOnCard| Card owner’s name as it appears on the card. | Optional unless required by merchant’s processor setup | See [Invalid Character Processing.](#section/invalidchar) | Amount| Total transaction amount in DDDD.CC format. | Required for swiped/card present transactions | | InvNum| The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice. | Optional | | | See [Invalid Character Processing.](#section/invalidchar) | | View the [ExtData Parameters Table](#section/_Toc455564524) for more information. | PNRef | Unique payment reference number used to identify a single transaction within the system. The payment reference number | Required on Force and Capture transactions | (PNRef) is assigned by the payment server at the time the transaction is created. | Zip | Card owner’s billing address five-digit postal/zip code. | Optional unless required by merchant’s setup | See [Invalid Character Processing.](#section/invalidchar) | CVNum | Card verification number. | Optional unless required by merchant’s setup| |ExtData| The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. |Optional| ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. View the [ExtData Parameters Table](#section/_Toc455564524) for more information. ## ExtData Parameters Table View the ExtData Examples and Parameters Table below for available parameters. ## ExtData Parameter Examples Example 1 ``` MANUAL 3.85 1.12 ``` Example 2 ``` 3.00 Commodity Description .50 True 1234 1.00 0 0 False BushelUS 3.5100 8675309 ``` **To view the contents of the ExtData Parameters table click** | ExtData Parameters | Description |-----|----- | Authorization Code | Original authorization/approval code. | Required when | Valid format is: | TransType=Force | | | _AuthorizationCode_ where _Authorization Code_ is the original authorization or approval code. | Customer Code Optional| Customer or purchase order (PO) number used with Level II information for Global Payments only (if using another processor that supports Level II, use the PO Number to pass this information instead). | | See [Invalid Character Processing.](#section/invalidchar) | | Valid format is: | | _CustomerCode_ where _Customer Code_ is the number assigned to identify the customer or the PO number. | Convenience Amount Optional| Allows the merchant to add a flat fee to the total transaction to cover the cost of paying in a more convenient way for the customer (Eg. Online vs. in person at the municipal center). This function may be used by utility companies, government agencies, and schools. | | Valid format is: | | _Amount_ where _Amount_ is the value to be added to the total transaction in DDDD.CC format. | Surcharge Amount Optional| Allows the merchant to add a fee to the total transaction to recoup the costs of offering the credit card transaction. This is different from a Convenience Fee (above) as that fee is for the added cost of offering the service in a more convenient way (pay for tickets online rather than in person). | | Valid format is: | | _Amount_ where _Amount_ is the value to be added to the total transaction in DDDD.CC format. | Tip Amount Optional| Allows the customer to specify a dollar amount that is already included in the total amount for the purpose of tipping. | | Valid format is: | | _Amount_ where _Amount_ is the value of the tip already included in the total transaction in DDDD.CC format. | Tax Amount Optional| Allows the merchant to add a dollar amount to the total transaction to cover sales tax. | | Valid format is: | | _Amount_ where _Amount_ is the value to be added to the total transaction in DDDD.CC format. | Tax Exempt Optional| Allows the merchant to declare whether the transaction is tax exempt. The default value for this is F (false) when not supplied. | | Valid format is: | | _T_ where _T_ or _TRUE_ denotes the transaction is tax exempt and _F_ or _FALSE_ would indicate it is taxable. | Sequence Number Optional| Identifies the payment order with a repeat sale or installment transaction. For example, payment 1 of 4. | | Valid format is: | | _SequenceNum_ where _SequenceNum_ is any positive integer less than or equal to the SequenceCount. | Sequence Count Optional| Identifies the total number of charges that will be made for a repeat sale or installment transaction. For example, 4 payments must be made to complete the payment. | | Valid format is: | | _SequenceCount_ where _SequenceCount_ is any positive integer greater than or equal to the _SequenceNum_. | Server ID | Unique server identification number. | Optional| See [Invalid Character Processing.](#section/invalidchar). Valid format is:_ServerID_ where _ServerID_ uniquely identifies the payment server used. | Time Out Optional| Processor time out value in seconds. The default value for the parameter is 30 seconds for a transaction and 300 seconds for a settlement transaction. | | Valid format is: | | _TimeOut_ where _TimeOut_ is the processor time out value in seconds. | Training Mode Optional| This is an indicator that specifies whether transactions will be processed for local loop back testing or treated normally. | | Valid formats are: | | T where _T_ (true) indicates that training mode is active and transactions are processed for local loop back testing. | | F where _F_ (false) indicates that training mode is inactive and transactions should be treated normally. | Transaction ID Optional | Merchant-assigned numerical string passed along with an original transaction that can be used for identification and voids. | | Valid format is: | | _TransactionIdentifierValue_ where _TransactionIdentifierValueis_ a numerical string. | Target Optional | Identifies the target transaction ID for the original transaction you wish to void without the use of a PNRef. | | Valid format is: | | _TransactionIdentifierValue_ where _TransactionIdentifierValue_ is a numerical string identifying the original transaction. | Force Optional |This is an indicator that specifies whether or not duplicate transactions will be processed. | | Valid formats are: | | _T_ where _T_ (true) indicates that duplicate transactions are accepted. | | _F_ where _F_ (false) indicates that duplicate transactions are not accepted. | | Note: Some processors, including Concord EFS, will not recognize this tag and delete duplicate transactions. | Register Number | Unique identifier for a specific register. | Optional |See [Invalid Character Processing.](#section/invalidchar). | | Valid format is: | | _RegisterNum_ where _RegisterNum_ is a valid unique identifier assigned to a specific register. | City | City name for the card owner’s billing address. | Depending on processor, may be required |See [Invalid Character Processing.](#section/invalidchar). | | Valid format is: | | _City_ where _City_ is the card owner’s city name. | Bill-To State | Two-character state code for the card owner’s bill-to address. | Depending on processor, may be required |See [Invalid Character Processing.](#section/invalidchar). | | Valid format is: | | _BillToState_ where _BillToState_ is the two-character state code for the card owner’s bill-to address. | Customer ID |Identification number assigned to the customer by the merchant. | Optional| | | Valid format is: | | _CustomerID_ where _CustomerID_ is the customer’s assigned customer ID. | Purchase Order (PO) Number | Customer or PO number used with Level II information. | Optional| See [Invalid Character Processing.](#section/invalidchar). | | Valid format is: | | _PONum_ where _‘PONum’_ is the number assigned to identify the customer or the PO. | | Note: If using Level II with Global Payments, use the CustCode to pass this information instead. | Bill Payment | This is an indicator that specifies whether or not the transaction is being used to pay a utility bill. It is only supported when TransType = Sale or RepeatSale. | Optional| | | Valid formats are: | |_T_ where _T_ (true) indicates that the transaction is being used to pay a utility bill. | |_F_ where _F_ (false) indicates that the transaction is being used for something other than a utility bill. | | Note: This tag is only relevant to Retail, MOTO, and ecommerce markets. The information is currently supported by Vital, First Data North, and Global Payments processors. Other processors may be supported in the future. | Custom Fields | This tag is used to pass along information arbitrary custom information into a custom fields for the transaction. | Optional| Within the CustomFields tag a tag is created that has the name of the specific custom field to be defined where the value is then stored as the tag value. These names are not allowed to have spaces or special characters. | | For example: If you had two custom fields (FruityPebbles and CocoaPebbles) and you wanted to pass the values of “18” FruityPebbles and a value of “Chocolate goodness” as the value of CocaoPebbles then the valid format would be: | | | |18 | |Chocolate goodness | |” | Token Request | The RequestToken tag is used to request a token be returned for the initiating transaction. The token will be returned in the ExtData of the response | Optional| | | Valid formats are: | | 1 where “1” denotes a valid “jstoken” type. Other types will be supported in future versions of the API | Entry Mode | Indicates how the values for payment information were obtained. | Optional| | | Valid formats are: | | UNKNOWN where _unknown_ indicates that the mode of entry is unknown. | |MANUAL where _manual_ indicates that the payment values were manually entered. | |MagneticStripe where _MagneticStripe_ indicates that the payment values were entered via magnetic stripe card reader (swiped card). | |ICC where _ICC_ indicates that the mode of entry is Instant Card Clearing. | |PROXIMITY where _proximity_ indicates that the payment values were entered via proximity card reader. | AMEX Batch Phase | When working with AMEX batch settlement, the Phase value can be used to determine the phase of the settlement file. | Optional| | | Valid formats are: | | Confirm where Confirm indicates that the batch is ready to settle | |Submit where Submit indicates that the batch has been submitted to the payment processor | |None where None indicates that no action has occurred | |Note: Batches must be submitted before they can be settled (Confirm). If you send a “confirm” only, the most recently submitted batch will be settled. | IIAS Indicator |When working with healthcare applications it is necessary to comply with inventory information approval system merchant certifications. | Optional| The IIAS indicator will inform the gateway that it is about to process a healthcare transaction. Once that is configured associated parameters are passed to indicate the type of healthcare charges to be considered. The default value is F | | Valid Examples are: | | T | |If this tag is not included the default is F (false) to indicate that this is not a healthcare transaction. | |If the tag is included then some of the following parameters also need to be included in the ExtData | |120.00 where this denotes the total amount of Clinic or other qualified medical items. | |100.00 where this denotes the total amount of Prescription/Rx (℞) items. | |80.00 where this denotes the total amount of Vision or Optical items. | |300.00 where this denotes the total amount of Dental items. | |600.00 where this denotes the sum total of all medical items. | |Note: These tags are not nested within the tag but rather at the same level. They are only documented at this way to make it clear when to use these tags. | External IP| When using the Transact web service, the IP address defaults to the calling computer’s IP. If the request is coming from an external source, the external IP address can be substituted for the purpose of logging and fraud control. | Optional | To implement this IP pass through functionality, the following XML node should be included in the external data field of the web service call | |IP Address Here | | If the ExternalIP node is not included in the external data field, then the default behavior of using the callers IP address is used. | Client Data| When using the Transact web service, the API allows a client pass through data via the Client Data mechanism. This data can be alphanumeric. | Optional | Arbitrary Data Here | |The ClientData can be used to pass through various POS or Client data related to the transaction. # 3.2. ProcessDebitCard This web service is used whenever a transaction is completed via a customer debit card. ## Request ProcessDebitCard(UserName, Password, TransType, CardNum, ExpDate, MagData, NameOnCard, Amount, InvNum, PNRef, Pin, RegisterNumber, SureChargeAmt, CashBackAmt, ExtData) ## Response IBXTransact.Response View [Transaction Response Fields.](#section/transaction-response-fields) ## ProcessDebitCard Input Parameters Unless noted otherwise, the parameter is **required**. | Parameter Name| Description |-----|----- | UserName | User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service. |Password | Password associated with the user name provided. | TransType| Identifies the type of debit card transaction being made. | | Valid values are: | | - Sale – make a purchase using a debit card | | - Return – credits the card holder’s account | | - Reversal – perform a manual full reversal on a debit card sale within 24 hours of the original transaction. The expected behavior of this transaction type is defined by the type of the payment processor the merchant account is configured for. See [Credit Card Reversals.](#section/reverse) | | - Inquire – check the balance | | BuyPass fuel transactions only: | | - Auth – authorize the amount on a debit card | | - Force – force an Auth transaction in to the current batch (PostAuth)Terminal-based processors only: | | - Capture – settle a single transaction in the current batch | | Terminal-based processors and host-based processors supporting batch release feature only: | | - CaptureAll – settle all transactions in the current batch | | Global Canadian Debit : | | - AddReversal – used when the host sends a response and the information is validated through the pin pad, if the information is found to be invalid. This transaction type can reverse the transaction sent to the host. The PNREF number of the original transaction can be sent along with the AddReversal transaction type to perform the reversal of that transaction. | CardNum Not required for Capture and CaptureAll transactions| Debit card number used to uniquely identify the owner’s account. | ExpDate| Debit card date of expiration in MMYY format. | MagData| Data located the magnetic strip on the back of the card. The format of the MagData is CardNum=ExpDate followed by the service date and checksum. For example: | Required on all swiped transactions| 36438999960016=05121015432112345678 | NameOnCard| Card owner’s name as it appears on the card. | Optional| | Amount| Total transaction amount in DDDD.CC format. | Not required on CaptureAll transactions| Note: This amount includes the CashBackAmt and SureChargeAmt. | InvNum| The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice. | Optional| View the [ExtData Field Definitions](#section/extdatadef) for more information. | PNRef| Unique payment reference number used to identify a single transaction within the system. The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created. | Required on Force and Capture transactions| | Pin| The encrypted PIN-block returned by the PIN pad. | Not required in Capture and CaptureAll transactions| Note: The transaction will fail if an unencrypted PIN is used. | | Note: This information is not required for PIN-less debit transactions. See [PIN-less Debit Transactions.](#section/pinless) | RegisterNumber| A string that uniquely identifies the register, terminal, or computer on which the transaction was performed. |Optional | | SureChargeAmt| The amount, in DDDD.CC format, charged by a merchant in exchange for processing a debit card transaction. |Optional | |CashBackAmt | The amount, in DDDD.CC format, requested by the card holder in cash back from the debit transaction. |Optional | |ExtData | The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. |Optional | ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. ## ExtData Parameters Table View the ExtData Examples and Parameters Table below for available parameters. ## ExtData Parameter Example Example To view the ExtData Parameters table click   | ExtData Parameters| Description |-----|----- |Timeout | Processor time out value in seconds. The default value for the parameter is 30 seconds for a transaction and 300 seconds for a settlement transaction. |Optional | | | Valid format is: | | _TimeOut_ where _TimeOut_ is the processor time out value in seconds. |TrainingMode | This is an indicator that specifies whether transactions will be processed for local loop back testing or treated normally. | Optional| | | Valid formats are: | | T where _T_ (true) indicates that training mode is active and transactions are processed for local loop back testing. | | F where _F_ (false) indicates that training mode is inactive and transactions should be treated normally. | Key Serial Number| PIN pad serial number. |Required for all non-PIN-less debit transactions | Valid format is: | | _KeySerialNumber_ where _KeySerialNumber_ is the PIN pad serial number used in managing DUKPT PIN pads. |Force | This is an indicator that specifies whether or not duplicate transactions will be processed. | Optional| | |Valid formats are: | |T where _T_ (true) indicates that duplicate transactions are accepted. | |F where _F_ (false) indicates that duplicate transactions are not accepted. | |Note: Some processors, including BuyPass, will not recognize this tag and reject duplicate transactions. # 3.3. ProcessCheck This web service is used whenever a transaction is completed via customer check. ## Request ProcessCheck(UserName, Password, TransType, CheckNum, TransitNum, AccountNum, Amount, MICR, NameOnCheck, DL, SS, DOB, StateCode, CheckType, ExtData) ## Response Need Response here View [Transaction Response Fields.](#section/transaction-response-fields) ## ProcessCheck Input Parameters Unless noted otherwise, the parameter is **required**. | Parameter Name| Description |-----|----- | UserName | User name assigned in the payment server. The user must have an appropriate level of access in order to utilize the web service. |Password | Password associated with the user name provided. | TransType| Identifies the type of credit card transaction being made. | | Valid values are: | | - Sale – make a purchase using a check | | - Auth (Verify) – authorizes or verifies the amount of a check | | - Return – return the money of a settled check transaction to the check holder | | - Void – undo a settled check transaction | | - Force – (ForceSale) force a previous Sale transaction into the current batch | | Terminal-based Processors Only: | | - Capture – settle a single transaction in the current batch | | - CaptureAll – settle all transactions in the current batch | | Note: If using the Return, Void, Force, or Capture TransTypes, you must include a PNRef using the ExtData parameter. | | Note: If using the Sale or Return TransTypes, you may be required to include city of account, bill-to street, and bill-to postal code using the ExtData parameter. | CheckNum| Uniquely identifies an individual’s check. | Not required for Capture and CaptureAll transactions| |TransitNum | Uniquely identifies the bank holding funds. Also called routing number. |Not required for Capture and CaptureAll transactions | | AccountNum| Uniquely identifies the check owner’s bank account. |Not required for Capture and CaptureAll transactions | |Amount | Total transaction value in DDDD.CC format. |Not required for Capture and CaptureAll transactions | |MICR | Magnetic Ink Check Reader data line. This data string includes the TransitNum and AccountNum. |Required on all swiped card transactions | | |Note: This input is required for processing check/consumer present transactions. | |Note: The formats of the MICR is processor specific and if the developer is not sure about what format your Check processor accepts, pass the RAW MICR as well in the TOAD format and details of this are described in the extended data. If the developer is sure about the precise format for MICR that is supported by the Check processor, then there is no need to pass the Raw MICR in TOAD format. |NameOnCheck | Check owner’s name as it appears on the check. |Not required for Capture and CaptureAll transactions | See [Invalid Character Processing.](#section/invalidchar) |May be required by merchant’s processor setup | |DL | Check owner’s driver’s license number. | Optional|See [Invalid Character Processing.](#section/invalidchar) |SS | Check owner’s Social Security number. | Optional|See [Invalid Character Processing.](#section/invalidchar) |DOB |Check owner’s date of birth. |Optional |See [Date Formats.](#section/dateformat) |StateCode |Check owner’s two-character state code. |Optional unless required by merchant’s processor setup |See [Invalid Character Processing.](#section/invalidchar) |CheckType | Identifies the type of check used in the transaction. |Optional | Valid values are: | |- Personal | |- Corporate | |- Government |ExtData |The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. |Optional |ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. ## ExtData Parameters Table View the ExtData Examples and Parameters Table below for available parameters. ## ExtData Parameter Examples Example To view the ExtData Parameters table click | ExtData Parameters| Description |-----|----- | Timeout | Processor time out value in seconds. The default value for the parameter is 30 seconds. |Optional | Valid format is: | | _TimeOut_ where _TimeOut_ is the processor time out value in seconds. |PNRef | Unique payment reference number used to identify a single transaction within the system. The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created. |Required for TransType = Return, Void, Force, or Capture | | |Valid format is: | |PNRef where PNRef is the valid payment reference number assigned to the transaction that is to be returned, voided, forced, or captured. |Phone |Check owner’s phone number. |Optional | See [Invalid Character Processing.](#section/invalidchar) | |Valid format is: | |_Phone_ where _Phone_ is the check owner’s phone number. |Email Address | Check owner’s email address. |Optional | See [Invalid Character Processing.](#section/invalidchar) | |Valid format is: | |_Email_ where _Email_ is the check owner’s email address. |Raw MICR |Raw Magnetic Ink Check Reader data line from the check reader. |Required for check/consumer present transactions | Valid format is: | | _RawMICR_ where _RawMICR_ is the transit number, account number, and check number in the following format:_TransitNumTAccountNumOCheckNum_ | |Note: TOAD format is the accepted default format for raw MICR for all check processors supported. |Invoice Number | The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice. |Optional | | |Valid format is: | |_InvNum_ where _InvNum_ is the merchant-assigned invoice number. | |Note: Many merchants use the invoice ID to store other values in the database. The exact nature of the value stored will vary by merchant. |TrainingMode | This is an indicator that specifies whether transactions will be processed for local loop back testing or treated normally. |Optional | | |Valid formats are: | |T where _T_ (true) indicates that training mode is active and transactions are processed for local loop back testing. | |F where _F_ (false) indicates that training mode is inactive and transactions should be treated normally. |Alliance Number | Check alliance number. |Optional | Valid formats are: | |_Checking_ to indicate a checking account | |_Savings_ to indicate a savings account |City of Account | City name for the check owner’s residential address. |Depending on merchant setup, may be required for TransType=Sale or Return | See [Invalid Character Processing.](#section/invalidchar) | |Valid format is: | |_CityOfAccount_ where _CityOfAccount_ is the check owner’s city name. |Bill-To Street | Street address for the check owner’s bill-to address. |Depending on merchant setup, may be required for TransType=Sale or Return | See [Invalid Character Processing.](#section/invalidchar) | |Valid format is: | |_BillToStreet_ where BillToStreet is the street name for the check owner’s bill-to address. |Bill-To City | City name for the check owner’s bill-to address. |Optional | See [Invalid Character Processing.](#section/invalidchar) | |Valid format is: | |_BillToCity_ where _BillToCity_ is the city name for the check owner’s bill-to address. |Bill-To State |Two-character state code for the check owner’s bill-to address. |Optional | See [Invalid Character Processing.](#section/invalidchar) | |Valid format is: | |_BillToState_ where _BillToState_ is the two-character state code for the check owner’s bill-to address. |Bill-To Postal Code | Postal/Zip code for the check owner’s bill-to address. |Depending on merchant setup, may be required for TransType=Sale or Return | See [Invalid Character Processing.](#section/invalidchar) | |Valid format is: | |_BillToPostalCode_ where _BillToPostalCode_ is the street name for the check owner’s bill-to address. |Bill-To Country | Country name for the check owner’s bill-to address. | Optional| See [Invalid Character Processing.](#section/invalidchar) | |Valid format is: | |_BillToCountry_ where _BillToCountry_ is the country name for the check owner’s bill-to address. |Customer ID |Identification number assigned to the customer by the merchant. |Optional |Valid format is: | |_CustomerID_ where _CustomerID_ is the customer’s assigned customer ID. | Card Type|For use with image uploads specific to the processor RDM_ITMS. |Optional | Valid format is: | |_IMAGE_ |External IP | When using the Transact web service, the IP address defaults to the calling computer’s IP. If the request is coming from an external source, the external IP address can be substituted for the purpose of logging and fraud control. |Optional | To implement this IP pass through functionality, the following XML node should be included in the external data field of the web service call… | |_IP Address Here_ | |If the ExternalIP node is not included in the external data field, then the default behavior of using the callers IP address is used. # 3.4. ProcessEBTCard EBT is used in all U.S. states to issue government benefits to recipients. Benefits are automatically deposited onto the card by the state and recipients are issued an “EBT card” (similar to a bank ATM or debit card) to receive their food stamp and/or cash benefits. Recipients with food stamp benefits can use their EBT cards for eligible food purchases at most grocery stores and some other retailers. ## Request ProcessEBTCard(UserName, Password, TransType, CardNum, ExpDate, MagData, NameOnCard, Amount, InvNum, PNRef, Pin, RegisterNum, SureChargeAmount, CashBackAmt, ExtData) ## Response Response here View [Transaction Response Fields.](#section/transaction-response-fields) ## ProcessEBTCard Input Parameters Unless noted otherwise, the parameter is **required**. | Parameter Name| Description |-----|----- | UserName | User name assigned in the payment server. The user must have an appropriate level of access in order to utilize the web service. |Password |Password associated with the user name provided. |TransType |Identifies the type of credit card transaction being made. | |Valid values are: | |- FoodStampSale – make a purchase on an EBT cardholder’s food stamp account | | - FoodStampReturn – credit to an EBT cardholder’s food stamp account | | - CashBenefitSale – make a purchase on an EBT cardholder’s cash benefit account | | - Inquire – check the balance on an EBT card | | - Capture – settle a single transaction in the current batch; only for terminal-based processors | | - CaptureAll – settle all transactions in the current batch; only for terminal-based processors or host-based processors that support a batch release feature | | - Force (Voucher Clear) – allow a merchant to pass a voucher number along with authorization code to perform a pin-less EBT sale. The voucher reference number is a reference number on the voucher slip to clear the transaction along with the authorization code obtained via a voice approval. | |The following transaction types apply to eWic processing. | |- EWICAUTHORIZATION – Authorize amount for eWic transaction | |- EWICCOMPLETION – Complete or capture the amount for an eWic authorization | |- EWICSALE – Perform an eWic Sale |CardNum | EBT card number used to uniquely identify the owner’s account. |Not required for Capture and CaptureAll transactions | |ExpDate | EBT card date of expiration in MMYY format. |MagData | Data located on the magnetic strip on the back of the card. The format of the MagData is CardNum=ExpDate followed by the service code and checksum. |Optional | | |For example: | |36438999960016=05121015432112345678 |NameOnCard |Card owner’s name as it appears on the card. | Optional unless required by merchant’s processor setup| Note: Invalid characters will be removed from this entry. See [Invalid Character Processing.](#section/invalidchar) |Amount |Total transaction amount in DDDD.CC format. |Not required for Capture and CaptureAll transactions |Note: This amount includes the CashBackAmt and SureChargeAmt. |InvNum |The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice. |Optional | | |View the [ExtData Field Definitions](#section/extdatadef) for more information. | PNRef| Unique payment reference number used to identify a single transaction within the system. |Required on all swiped card transactions | The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created. |Pin | The encrypted PIN-block returned by the PIN pad. |RegisterNum | A string that uniquely identifies the register, terminal, or computer on which the transaction was performed. | Optional| | SureChargeAmount| The amount, in DDDD.CC format, charged by a merchant in exchange for processing a debit card transaction. | Optional| |CashBackAmt | The amount, in DDDD.CC format, requested by the card holder in cash back from the debit transaction. |Optional | |ExtData | The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. |Optional | ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. ## ExtData Parameters Table View the ExtData Examples and Parameters Table below for available parameters. ## ExtData Parameter Examples To view the ExtData Parameters table click | ExtData Parameters| Description |-----|----- | Timeout | Processor time out value in seconds. The default value for the parameter is 30 seconds and 300 seconds for a settlement transaction. |Optional | ||Valid format is: | |_TimeOut_ where _TimeOut_ is the processor time out value in seconds. |Training Mode |This is an indicator that specifies whether transactions will be processed for local loop back testing or treated normally. |Optional | | |Valid formats are: | |_T_ where _T_ (true) indicates that training mode is active and transactions are processed for local loop back testing. | |_F_ where _F_ (false) indicates that training mode is inactive and transactions should be treated normally. |Key Serial Number | Key Serial Number: (required for all non-PIN-less debit transactions) PIN pad serial number. |Optional | | |Valid format is: | |_KeySerialNumber_ where _KeySerialNumberis_ the PIN pad serial number used in managing DUKPT PIN pads. |Force | This is an indicator that specifies whether or not duplicate transactions will be processed. |Optional | | |Valid formats are: | |_T_ where _T_ (true) indicates that duplicate transactions are accepted. | |_F_ where _F_ (false) indicates that duplicate transactions are not accepted. | |Note: Some processors, including BuyPass, will not recognize this tag and reject duplicate transactions. |External IP | When using the Transact web service, the IP address defaults to the calling computer’s IP. If the request is coming from an external source, the external IP address can be substituted for the purpose of logging and fraud control. |Optional | | |To implement this IP pass through functionality, the following XML node should be included in the external data field of the web service call… | | _IP Address Here_ | |If the ExternalIP node is not included in the external data field, then the default behavior of using the callers IP address is used. |eWic transactions (Specific to RapidConnect) | |For eWic transactions, you can supply eWic detail using the following parameters and must be contained in the EWicDetail group: | | - UPCPLUInd – Indicator for UPC/PLU, 0 for UPC, 1 for PLU | | - UPCPLUData – Can be up to 16 characters | | - UPCPrice – Can only be up to 6 digits, which includes two implied decimals | | - UPCQty – Number of Items or total weight of items, Can only be up to 5 digits, which includes two implied decimals | |Below is an examples of what the string would look like without data: | | | | |Merchant FNS: | |For a Food benefit/snap transaction you can provide the Merchant FNS Number in the MerchantFNS tag: | | - _12345_ # 3.5. ProcessGiftCard This web service is used to process gift card transactions for a merchant. ## Request ProcessGiftCard(UserName, Password, TransType, CardNum, ExpDate, MagData, Amount, InvNum, PNRef, ExtData) ## Response Response here View [Transaction Response Fields.](#section/transaction-response-fields) ## ProcessGiftCard Input Parameters Unless noted otherwise, the parameter is **required**. | Parameter Name| Description |-----|----- | UserName | User name assigned in the payment server. The user must have an appropriate level of access in order to utilize the web service. |Password| Password associated with the user name provided. |TransType| Identifies the type of gift card transaction being made. ||Valid values are: ||- Redeem – make a purchase on a gift card ||- Reload – increase the balance on a gift card ||- Refund – refund money back to a gift card ||- Activate – activate a gift card ||- Deactivate – deactivate a gift card ||- Inquire – check the balance on a gift card ||- Void – undo an unsettled transaction ||_Paymentech/Tampa only:_ ||- Force – place a transaction not processed through the payment server into the current batch (ForceAuth). ||_Terminal-based processors only:_ || - Capture – settle a single transaction in the current batch; only for terminal-based processors ||_Processors supporting the batch release feature only:_ ||- CaptureAll – settle all transactions in the current batch. |CardNum| Gift card number used to uniquely identify the owner’s account. |ExpDate| Gift card date of expiration in MMYY format. |MagData|Data located the magnetic strip on the back of the card. The format of the MagData is CardNum=ExpDate followed by the service code and checksum. For example: |Required on all swiped transactions| 36438999960016=05121015432112345678 |Amount| Total transaction amount in DDDD.CC format. |Not required for CaptureAll transactions| Note: This amount includes the CashBackAmt and SureChargeAmt. |InvNum| The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice. |Optional| View the [ExtData Field Definitions](#section/extdatadef) for more information. |PNRef| Unique payment reference number used to identify a single transaction within the system. |Required on Force and Capture transactions|The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created. |ExtData| The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. |Optional| ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. ## ExtData Parameters Table View the ExtData Examples and Parameters Table below for available parameters. ## ExtData Parameter Examples Example To view the ExtData Parameters table click | ExtData Parameters| Description |-----|----- | Training Mode | This is an indicator that specifies whether transactions will be processed for local loop back testing or treated normally. |Optional | ||Valid formats are: | |T where _T_ (true) indicates that training mode is active and transactions are processed for local loop back testing. | |F where _F_ (false) indicates that training mode is inactive and transactions should be treated normally. |Force | This is an indicator that specifies whether or not duplicate transactions will be processed. |Optional | | |Valid formats are: | |_T_ where _T_ (true) indicates that duplicate transactions are accepted. | |_F_ where _F_ (false) indicates that duplicate transactions are not accepted. | |Note: Some processors, including BuyPass, will not recognize this tag and reject duplicate transactions. |Time out | Processor time out value in seconds. The default value for the parameter is 30 seconds for a transaction and 300 seconds for a settlement transaction. |Optional | | |Valid format is: | | _TimeOut_ where _TimeOut_ is the processor time out value in seconds. |Register Number | This is unique identifier for the register, terminal or computer used to process the gift card transaction. |Optional | | |Valid format is: | | _RegisterNum_ where _RegisterNum_ is equal to the register identification number stored on the merchant’s account record. |Paymentech/Tampa Only |Force Authorizatioln | Places a previously authorized transaction (TransType = Redeem, Reload, or Activate) into the current batch. |Optional | | | _AuthCode_ where _AuthCode_ is the previously obtained authorization code from Paymentech/Tampa. |External IP | When using the Transact web service, the IP address defaults to the calling computer’s IP. If the request is coming from an external source, the external IP address can be substituted for the purpose of logging and fraud control. | Optional| | | To implement this IP pass through functionality, the following XML node should be included in the external data field of the web service call… | | IP Address Here | | If the ExternalIP node is not included in the external data field, then the default behavior of using the callers IP address is used. # 3.6. ProcessSignature The ProcessSignature web service allows you to capture customer signatures from an input device. This web service is used to capture a customer signature electronically and store that data on the virtual terminal. Transactions with captured signatures appear in the Payment Server with a small icon to the left of the transaction ID. ## Request ProcessSignature(UserName, Password, SignatureType, SignatureData, PNRef, Result, AuthCode, ExtData) This example combines the previous ProcessCreditCard call and appends a signature to it. An [example file is linked](https://www.payroc.com/Common/Images/Custom/5982/api-docs/gateway_signature.tif) (see “Path to File”) which you can download and save locally to try. ``` SmartPaymentsSoapClient transact = new SmartPaymentsSoapClient("SmartPaymentsSoap"); transactResponse = transact.ProcessCreditCard( "username", "password", "Sale", "4012888888881881", "1216", "", "Barney Rubble", "200", "666", "", "", "", "999", @"MANUAL3.85 2" ); Byte[] signatureBytes = File.ReadAllBytes(@""); String signatureContents64 = Convert.ToBase64String(signatureBytes); response = transact.ProcessSignature("username", "password", "Receipt1", signatureContents64, transactResponse.PNRef, "", transactResponse.AuthCode, ""); ``` ## Response ``` Message "APPROVAL" string Message1 "" string Message2 "" string PNRef "" string ReceiptURL null string RespMSG "OK" string Result 0 int ``` View [Transaction Response Fields.](#section/transaction-response-fields) ## ProcessSignature Input Parameters Unless noted otherwise, the parameter is **required**. | Parameter Name| Description |-----|----- | UserName | User name assigned in the payment server. The user must have an appropriate level of access in order to utilize the web service. |Password |Password associated with the user name provided. |SignatureType | Identifies the format of the signature data being provided. Valid values are: | |Valid values are: | |- Signature1 – Lipman credit | |- Signature2 – Lipman check | |- Signature3 – no longer used | |- Signature4 – signature provided in a vector string | |- Receipt1 – TIFF file (compressed and encoded Base64) | SignatureData| This parameter holds the data string containing the signature data. | | If SignatureType = Signature4, the SignatureData will contain a string value of vector coordinates, delimited with a ^ character in the following format: | |x1,y1^x2,y2^xN,yN^~ | |Where ^ is the coordinate delimiter, ~ is the ending delimiter, and a comma (,) is the vector delimiter. | |If there is a pen up event, use the coordinate 0,65535 to signal a break in the line. | |If SignatureType = Receipt1, you must compress and Base64 encode the image data. See [Compression and Encoding.](#section/comp) |PNRef | Unique payment reference number used to identify a single transaction within the system. The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created. |Result | Indicator that specifies whether the transaction was approved. |Optional | Valid entries are: | | - 1 (true) – transaction was approved | | - 0 (false) – transaction was not approved |AuthCode | The approval code is a 6-character string (alphanumeric) generated by the issuing bank. The code is used the card issuer to verify the specific authorization when transactions are being settled. |Optional | |ExtData | The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. |Optional | ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. | | The following information may be added via the ExtData parameter: | | Training Mode: This is an indicator that specifies whether transactions will be processed for local loop back testing or treated normally. | | Valid formats are: | | - _T_ where _T_ (true) indicates that training mode is active and transactions are processed for local loop back testing. | | - _F_ where _F_ (false) indicates that training mode is inactive and transactions should be treated normally. # 3.7. ProcessBatch The ProcessBatch web service provides the ability to control closing open batches for a merchant across Credit, Debit, EBT, ALL payment types. It serves as a convenience function as an alternative to calling Process(Credit|Debit|EBT)Card with the “CaptureAll” or “Capture” transaction types. ## Request ProcessBatch(UserName, Password, TransType, PaymentType, BatchID, BatchStatus, PNRef, ExtData) ``` SmartPaymentsSoapClient transact = new SmartPaymentsSoapClient("SmartPaymentsSoap"); transactResponse = transact.ProcessBatch("username", "password", "CAPTURE", "EBT", "", "", "", ""); ``` ## Response ``` 0 Approved OK GB79 GB79 CardType=CREDITSummaryCREDITNet_Count=9,Net_Amount=9.32Return=1.23,Sale=10.55,Return_Cnt=1,Sale_Cnt=5,Cnt=6 ``` View [Transaction Response Fields.](#section/transaction-response-fields) ## ProcessBatch Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- | UserName | User name assigned in the payment server. The user must have an appropriate level of access in order to utilize the web service. |Password |Password associated with the user name provided. |TransType | Currently only CAPTURE is supported. |PaymentType |This parameter determines which open batches to attempt to close. If not supplied ALL is assumed. This would be the equivalent of calling each of the Process(Credit,Debit,EBT)Card functions in turn with a CaptureAll transaction type. | Optional| | |The valid values are: | |- ALL | |- CREDIT | |- DEBIT | |- EBT | |- CHECK |BatchID | | |Currently unused | Optional| |BatchStatus | | |Currently unused |Optional | |PNRef |Unique payment reference number used to identify a single transaction within the system. The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created. |Optional |If a PNRef is supplied a PaymentType must be provided as well. The gateway will settle the PNRef associated with the specific payment type. |ExtData | The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. |Optional |ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. | |The following information may be added via the ExtData parameter: | | Timeout: The timeout for the transaction in seconds. This defaults to 40 seconds | |Valid formats are: | |- 60 | |Training Mode: This is an indicator that specifies whether transactions will be processed for local loop back testing or treated normally. | |Valid formats are: | |- _T_ where _T_ (true) indicates that training mode is active and transactions are processed for local loop back testing. | |_F_ where _F_ (false) indicates that training mode is inactive and transactions should be treated normally. # 3.8. GetInfo The GetInfo web service allows for miscellaneous checks against the gateway. These include the status of a current batch or an end-to-end status check to see if the gateway is currently responding. ## Request GetInfo(UserName, Password, TransType, ExtData) ``` SmartPaymentsSoapClient transact = new SmartPaymentsSoapClient("SmartPaymentsSoap"); transactResponse = transact.GetInfo("username", "password", "BatchInquiry", ""); ``` ## Response ``` 0 Approved Net_Amount=9.32,Net_Count=6,Credit_Sale_Amount=10.55,Credit_Sale_Count=5,Credit_Return_Amount=1.23,Credit_Return_Count=1,Credit_Net_Amount=9.32,Credit_Net_Count=6,Debit_Sale_Amount=0.00,Debit_Sale_Count=0,Debit_Return_Amount=0.00,Debit_Return_Count=0,Debit_Net_Amount=0.00,Debit_Net_Count=0,EBT_Sale_Amount=0.00,EBT_Sale_Count=0,EBT_Return_Amount=0.00,EBT_Return_Count=0,EBT_Net_Amount=0.00,EBT_Net_Count=0,Check_Sale_Amount=0.00,Check_Sale_Count=0,Check_Net_Amount=0.00,Check_Net_Count=0 ``` View [Transaction Response Fields.](#section/transaction-response-fields) ## GetInfo Input Parameters Unless noted otherwise, the parameter is **required**. | Parameter Name| Description |-----|----- | UserName | User name assigned in the payment server. The user must have an appropriate level of access in order to utilize the web service. |Password |Password associated with the user name provided. |TransType | CThe transaction type for the GetInfo call. | |Valid Values: | | - BatchInquiry – return a summary of the current batch status for the merchant (counts and amounts) for all types (Credit, Debig, EBT, Check) | |- StatusCheck – Run a pseudo transaction through the API merchants processor to determine if the gateway is responding. Returns OK only in ExtData |ExtData | | |The ExtData input parameter is reserved for future use. |Optional | # 3.9. Transaction Response Fields The following response fields may be part of the return value for web services using transact.asmx operations. These web services include: - GetInfo - ProcessCheck - ProcessCreditCard - ProcessDebitCard - ProcessEBTCard - ProcessGiftCard - ProcessSignature | Response Field Data Value | Description | |-----|----- |AuthCode|Returns the transaction result code from the payment processor. |String up to 50 characters| This value can be either an approval code, for approved transactions, or an error code, for declined transactions |ExtData| Returns extra data from the processed transaction. |String up to 500 characters| The value of ExtData will be in a specific format. The format typically consists of the name of the data field, an equal sign, and then the value for the data field. Multiple data fields are separated with a comma. ||See the [ExtData Field Definitions](#section/extdatadef) for full description of data elements that can be returned. ||The following is an example of the format: ExtName1=ExtValue1,ExtName2=ExtValue2 |GetAVSResult| Returns the overall address verification result code from the payment processor. |String up to 1 character| ||When programmatically validating an AVS Result, this value should ALWAYS be used instead of any formatted response message describing the result. ||View the [AVS Response Fields.](#section/avs-response-fields) |GetAVSResultTXT| Returns the formatted response message when address verification is performed. |String up to 25 characters| || Do NOT use this when programmatically validating a transaction’s AVS result; please see GetAVSResult field. |GetCommercialCard| Returns the payment processor’s response indicator that specifies if the card is a commercial card. |String representing Boolean value| ||This value is only applicable to credit card transactions. The card verification number is typically printed on the back of the card and not embossed on the front. It is used as an extra authentication method for “card not present” transactions. When programmatically validating a CV Result, this value should ALWAYS be used instead of any formatted response message describing the result. |GetCVResult| Returns the card verification result code from the payment processor. |String up to 1 character| ||This value is only applicable to credit card transactions. The card verification number is typically printed on the back of the card and not embossed on the front. It is used as an extra authentication method for “card not present” transactions. When programmatically validating a CV Result, this value should ALWAYS be used instead of any formatted response message describing the result. ||View the [CV Response Fields.](#section/cv-response-fields) |GetCVResultTXT| Returns the formatted response message when card verification is performed. |String up to 25 characters| ||This value is only applicable to credit card transactions. Do NOT use this when programmatically validating a transaction’s CV result; please see GetCVResult field. |GetStreetMatchTXT| Returns the formatted response message when street number address verification is performed. |String up to 25 characters| ||This value will typically be “Match”, for correctly matching the street address, or “No Match”, for an incorrect street address. |GetZipMatchTXT| Returns the formatted response message when zip code address verification is performed. |String up to 25 characters| ||This value will typically be “Match”, for correctly matching the zip code, or “No Match”, for an incorrect zip code. |HostCode| Typically returns a number which uniquely identifies the transaction in the payment processor. |String up to 30 characters| ||This value may not be returned for all payment processors. |Message| Returns a formatted response message concerning the processed transaction. |String up to 50 characters| ||This value will typically be “APPROVAL”, for approved transactions, or an error message, for declined transactions. Do NOT use this when programmatically validating a transaction’s result; please see Result field below. |Message1| Returns an extra formatted response message giving more information about the processed transaction. |String up to 50 characters| ||The Payment Server will only populate this field when there is applicable information from the payment processor to return. |Message2| Returns an extra formatted response message giving more information about the processed transaction. |String up to 50 characters| ||The Payment Server will only populate this field when there is applicable information from the payment processor to return. |PNRef|Returns a number which uniquely identifies the transaction in the payment gateway. |String representing a signed 32-bit integer| |RespMSG|Returns the response message concerning the processed transaction. |String up to 50 characters| ||This value is typically either Approved or Declined. Do NOT use this when programmatically validating a transaction’s result; please see Result field below. |Result| Returns the transaction result code from the payment gateway which signifies the result of the transaction (i.e. approved, decline, etc.). |String representing a signed 32-bit integer| ||When programmatically validating a transaction’s result, this value should ALWAYS be used instead of any response message describing the result. ||See the [Result Response Field Definitions](#section/resultresp) for a full list of result values and descriptions. ## ExtData Response Fields | Response Field| Description |-----|----- |BatchNum| Current batch number for transactions, settlement, and batch inquiries. ||Note: Not all payment processors support returning this data element. |CardType| Credit card type (VISA, MASTERCARD, etc) or payment method (Debit, EBT, or EGC) for card-based payments. ||Note: This value is not returned for Check/ACH payments. |InvNum| Invoice number for the transaction that was originally sent in the request to the Payment Server. |Token| This value contains the token result (up to 64 alphanumeric characters) if a token was requested during the initiating transaction. Please note that this is a base64 encoded value so when parsing the returned structure you must rely on the comma to delimit the fields and the first “=” sign to denote the key and value separator as “=” signs can exist at the end of the token. ||Eg: ||Token=7d4l2JLKFHzjQENGdQ8t6wP1C18JI59c6q5HCEAsJUBz0DK5I1pNxQ== |Balance|This XML tag contains the value for requests that require a balance response such as EBT balance inquiries. ||Eg: ||12.50 |Trace|This XML tag contains the System Trace Audit Number returned for Debit / EBT transactions. ||Eg: ||525982 |NetworkId|This XML tag contains the value for the identification code of the network on which the transaction was authorized. ||Eg: ||K |Approved Amount|This XML tag contains the approved amount for a transaction that results in a partial approval. It is always enclosed by a tag. ||Eg: ||_5.55_ ||Full Example: ||11.10 ||5.55 |Requested Amount|This XML tag contains the requested amount for a transaction that results in a partial approval. It is always enclosed by a tag. ||Eg: ||11.10 ||Full Example: ||11.10 ||5.55 # 3.10. Result Response Fields ## Result Response Field Definitions | Value | Description | |-----|----- |-100|Transaction NOT Processes; Generic Host Error |0| Approved |1| User Authentication Failed |2| Invalid Transaction |3| Invalid Transaction Type |4| Invalid Amount |5| Invalid Merchant Information |7|Field Format Error |8|Not a Transaction Server |9|Invalid Parameter Stream |10|Too Many Line Items |11|Client Timeout Waiting for Response |12|Decline |13|Referral |14|Transaction Type Not Supported In This Version |19|Original Transaction ID Not Found |20|Customer Reference Number Not Found |22|Invalid ABA Number |23|Invalid Account Number |24|Invalid Expiration Date |25|Transaction Type Not Supported by Host |26|Invalid Reference Number |27|Invalid Receipt Information |28|Invalid Check Holder Name |29|Invalid Check Number |30|Check DL Verification Requires DL State |40|Transaction did not connect (to NCN because Secure NCIS is not running on the web server) |50|Insufficient Funds Available |99|General Error |100|Invalid Transaction Returned from Host |101| Timeout Value too Small or Invalid Time Out Value |102| Processor Not Available |103| Error Reading Response from Host |104|Timeout waiting for Processor Response |105|Credit Error |106|Host Not Available |107|Duplicate Suppression Timeout |108|Void Error |109|Timeout Waiting for Host Response |110|Duplicate Transaction |111|Capture Error |112|Failed AVS Check |113|Cannot Exceed Sales Cap |1000|Generic Host Error |1001|Invalid Login |1002|Insufficient Privilege or Invalid Amount |1003|Invalid Login Blocked |1004|Invalid Login Deactivated |1005|Transaction Type Not Available |1006|Unsupported Processor |1007|Invalid Request Message |1008|Invalid Version |1010|Payment Type Not Supported |1011|Error Starting Transaction |1012|Error Finishing Transaction |1013|Error Checking Duplicate |1014|No Records To Settle (in the current batch) |1015|No Records To Process (in the current batch) # 3.11. AVS Response Fields | Value | Description | |-----|----- |X|Exact: Address and nine-digit Zip match |Y| Yes: Address and five-digit Zip match |A| Address: Address matches, Zip does not |Z|5-digit Zip: 5-digit Zip matches, address does not |W| Whole Zip: 9-digit Zip matches, address does not |N| No: Neither address nor Zip matches |U|Unavailable: Address information not available |G|Unavailable: Address information not available for international transaction |R|Retry: System unavailable or time-out |E|Error: Transaction unintelligible for AVS or edit error found in the message that prevents AVS from being performed |S|Not Supported: Issuer doesn’t support AVS service |B|Street Match: Street addresses match for international transaction, but postal code does not |C|Street Address: Street addresses and postal code not verified for international transaction |D|Match: Street addresses and postal codes match for international transaction |I|Not Verified: Address Information not verified for International transaction |M|Match: Street addresses and postal codes match for international transaction |P|Postal Match: Postal codes match for international transaction, but street address does not |O|No response sent |5|Invalid AVS response # 3.12. CV Response Fields | Value | Description | |-----|----- |M|CVV2/CVC2/CID Match |N|CVV2/CVC2/CID No Match |P|Not Processed |S|Issuer indicates that the CV data should be present on the card, but the merchant has indicated that the CV data is not present on the card. |U| Unknown / Issuer has not certified for CV or issuer has not provided Visa/MasterCard with the CV encryption keys. |X| Server Provider did not respond # 4. Reporting # 4.1. GetCardTrx This web service returns one or more card transactions (with details) for a specific merchant. In addition to the basic transaction search function, the GetCardTrx web service can help you: - Build a variety of custom reports, from customer billing histories to reports that help locate duplicate transactions. - Build data mining applications. For example, determining what percentage of sales derive from specific users or payment types. If you have multiple gateway accounts, you can compile the data from multiple sources into your own customized and aggregated reports. - Automate the reconciliation process between the payment server and the point-of-sale (POS) system or register. ## Request ## Request Example 1 GetCardTrx(UserName, Password, RPNum, PNRef, BeginDt, EndDt, PaymentType, ExcludePaymentType, TransType, ExcludeTransType, ApprovalCode, Result, ExcludeResult, NameOnCard, CardNum, CardType, ExcludeCardType, ExcludeVoid, User, invoiceId, SettleFlag, SettleMsg, SettleDt, TransformType, Xsl, ColDelim, RowDelim, IncludeHeader, ExtData) ## Request Example 2 A second version of this API changes SettleDt to be a range comprising BeginSettleDt and EndSettleDt. GetCardTrx(UserName, Password, RPNum, PNRef, BeginDt, EndDt, PaymentType, ExcludePaymentType, TransType, ExcludeTransType, ApprovalCode, Result, ExcludeResult, NameOnCard, CardNum, CardType, ExcludeCardType, ExcludeVoid, User, invoiceId, SettleFlag, SettleMsg, BeginSettleDt, EndSettleDt, TransformType, Xsl, ColDelim, RowDelim, IncludeHeader, ExtData) ``` TrxDetailSoapClient reporting = new TrxDetailSoapClient("TrxDetailSoap"); reportingResponse = reporting.GetCardTrx( "username", "password", "5", "13612", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "true", ""); ``` ## Response ``` 13612 666 2016-08-05T18:16:12.867+00:00 5 username 2 999 VISA Sale TSYS 13549 0 0 2016-08-05T18:16:13.663+00:00 13549 13550 200.0000 3.8500 200.0000 0.0000 0.0000 VISA 0 TAS979 000000000016865 0 M 080516 131613 ************1881 1216 VISA Barney Rubble true 0 192.168.1.2 0 0.0000 0 2016-08-05T18:16:12.867+00:00 0 Chocolate goodness 18 ``` View [TrxDetail Response Fields.](#section/trxdetail-response-fields) ## GetCardTrx Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- | UserName|User name assigned in the payment server. The user must have an appropriate security permissions in order for the system to return transaction records. |Password |Password for the user name assigned in the payment server. |RPNum |Unique value assigned to each gateway account used as a third credential to ensure security and | |Note: RPNum may also be called Merchant ID, Merchant Number, or Vendor Key. | PNRef| The unique payment reference number assigned to the transaction. |Optional | If this field is provided, all other query fields will be ignored when using PNRef parameter to query the system. | BeginDt| Beginning date of the transaction record query. |Required unless a PNRef value is provided | | EndDt| End date of the transaction record query. |Required unless a PNRef value is provided | |PaymentType |If provided, only those transactions matching the PaymentType will be included. |Optional | | |Valid values are: | |- ‘AMEX’ American Express card | |- ‘CARTBLANCH’ Carte Blanch card | |- ‘DEBIT’ Debit card | |- ‘DINERS’ Diners Club card | |- ‘DISCOVER’ Novus Discover card | |- ‘EBT’ Electronic Benefit Transfer | |- ‘JAL’ JAL card | |- ‘JCB’ Japanese Commercial Bank card | |- ‘MASTERCARD’ Master card | |- ‘VISA’ Visa card | |- ‘EGC’ Gift card | |- ‘PAYRECEIPT’ to retrieve receipt images that were uploaded to the payment server | |- ‘SETTLE’ to retrieve requests to settle transactions | |Note: The default value for this field is “All”. If no value is set, all payment types will be returned in the result set. | |Or any permutation of the above values, e.g. “‘PAYRECEIPT’,’SETTLE'” will pull all transactions with either PayReceipt or Settle payment types. |ExcludePaymentType | The ExcludePaymentType parameter allows you to exclude certain payment types from the result set. Any valid entry (or combination) listed under the PaymentType parameter may be used. |Optional |Note: If you pass the same value in the PaymentType and ExcludePaymentType parameters, the entry in the ExcludePaymentType parameter will override the PaymentType and results of that type will be excluded. |TransType | If provided, only those transactions matching the TransType will be included. |Optional | Valid values are | |- ‘Authorization’ to retrieve previously-authorized (pre-auth) transactions | | - ‘Capture’ to retrieve captured transactions | |- ‘Credit’ to retrieve return transactions | |- ‘ForceCapture’ to retrieve force-auth transactions | |- ‘GetStatus’ to make an inquiry to the EBT or gift card’s balance | |- ‘PostAuth’ to retrieve post-auth transactions | |- ‘Purged’ to remove a transaction from the current batch due to an error | |- ‘Receipt’ to retrieve receipt images that were uploaded to the payment server | |- ‘RepeatSale’ to retrieve repeat-sale transactions | |- ‘Sale’ to retrieve sale transactions | |- ‘Void’ to retrieve void transactions | |Or any permutation of the above values, e.g. “‘Credit’,’Sale'” will pull all transactions with either Credit or Sale transaction types. |ExcludeTransType | The ExcludeTransType parameter allows you to exclude certain transaction types from the result set. Any valid entry (or combination) listed under the TransType parameter may be used. |Optional | Note: If you pass the same value in the TransType and ExcludeTransType parameters, the entry in the ExcludeTransType parameter will override the TransType and results of that type will be excluded. | |Note: A value of ‘Void’ in the ExcludeTransType parameter will be overridden by the ExcludeVoid if both parameters are used. | |This parameter accepts multiple values. |ApprovalCode | The approval code is a 6-character string (alphanumeric) generated by the issuing bank. The code is used the card issuer to verify the specific authorization when transactions are being settled. This field may also be used by payment processors to return error messages. |Optional | Note: You may only query one approval code at a time; however, approval codes are not necessarily unique and there is potential (rare) for more than one record to be returned. | Result| If provided, only those transactions matching the Result will be included. |Optional | Valid values are: | | - ‘NULL’ returns both approved and declined transactions | |- ‘0’ returns only approved transactions | |- Any other value for Result will return transactions matching that Result code. | |Note: to return only declined transactions do not pass a value for this parameter and instead set ExcludeResult = 0. |ExcludeResult | If provided, any transactions matching the ExcludeResult will be excluded. |Optional | Note: To return a only declined transactions, set ExcludeResult = 0. |NameOnCard | Cardholder’s name as it is appears on the card. If provided, only those transactions with cardholder’s name matching NameOnCard will be included. |Optional |Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234”. |CardNum |A card number. If provided, only those transactions with the card number matching CardNum will be included. Matching is done using wild cards. |Optional | |CardType | This field has been deprecated. Please use the PaymentType field to specify the type of card used in a transaction. |Optional | View [ExtData Field Definitions](#section/extdatadef) for more information. |ExcludeCardType |This field has been deprecated. Please use the ExcludePaymentType field to specify the type of cards you wish to be excluded from the result set. |Optional | |ExcludeVoid | The ExcludeVoid parameter allows you to exclude voided transactions from the result set. |Required unless a PNRef value is provided | | |Valid entries are: | |- ‘TRUE’ – voided transactions are excluded | |- ‘FALSE’ – voided transactions are included | |Note: A value of ‘Void’ in the ExcludeTransType parameter will be overridden by the ExcludeVoid if both parameters are used. |User |The user who originated the transactions. If provided, only those transactions created by the matching User will be included. |Optional | Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234”. |InvoiceId |The invoice ID that was included in the original transaction. If provided, only those transactions with matching invoiceId will be included. |Optional | Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234” |SettleFlag | The SettleFlag parameter allows you to choose whether settled or unsettled transactions are included in the results. |Optional | Valid entries are: | |- Unused/blank returns all transactions | |- ‘1’ – returns only settled transactions | |- ‘0’ – returns only transactions that are not yet settled |SettleMsg | The settlement ID or message returned from the host. |Optional | |SettleDt | The date of settlement. |Optional | |TransformType | The type of format to transform the data into. Leave the field blank to default to XML |Optional | | | - ‘XML’ will output the plain XML string | |- ‘XSL’ will use XSL to transform the XML output | |- ‘DELIM’ uses ColDelim and RowDelim to format the output |Xsl | This field is used only if the TransformType is XSL. |Optional | If provided, the resulting dataset will be transformed using this XSL. You may pass in a URL to the XSL file, or the XSL string itself. If this field is not empty, the Web Services will try to locate the file from the URL. If that also fails, it will treat it as an XSL string. In any case, the final XSL string will be loaded and validated against the XSL schema; if it passes, then that XSL will be used for transformation. | |A sample predefined XSL is included with this Web Services: | |_‘https://gateway.ibxpays.com/admin/ws/TabDelim.xsl’_ for a tab delimited transformation. | ColDelim|This field is used only if the TransformType is DELIM. This defines the string that separates each column. |Optional | | |e.g. a value of ‘@’, would separate each column value with ‘@’ |RowDelim | This field is used only if the TransformType is DELIM. This defines the string that separates each row. |Optional | | |e.g. a value of ‘!’ would start each row with ‘!’ |IncludeHeader | This field is used only if the TransformType is DELIM. If TRUE, then field headers will be included in the first row using the same delimiter strings; must either be TRUE or FALSE. |ExtData | The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. |Optional | Extended data in XML format. Valid values are: | |- ‘NO_IMAGE’ – Will only return transaction data that does not include image data (to include signature data and check images) | |- ‘ONLY_IMAGE’ – Will only return transaction data that includes image data (to include signature data and check images) | |- ‘ALL’- will return transaction with or without image data | |- ‘CustomerID’ – specifies the customer ID value to search by. Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234” | |- ‘Amount’ – specifies the amount value of the transactions being searched for. In DDDDDD.CC format | |- ‘RegisterNum’ – specifies the register number, originally passed with the transaction, to search by | |- Timezone – Used to convert the input and output (where applicable) date/time values to the desired timezone. When specified, the same timezone is used to convert the begin/end date parameters as well as the Date and Last Update output values. This field is optional, and if omitted all date/time values are treated as UTC. Daylight savings time adjustments, where applicable, are handled automatically. Accepted values are: | | -- AKST – Alaskan Standard Time | | -- CST – Central Standard Time | | -- EST – Eastern Standard Time | | -- HST – Hawaiian Standard Time | | -- MST – Mountain Standard Time | | -- AZMST – Arizona | | -- PST – Pacific Standard Time # 4.2. GetCardTrxSummary The GetCardTrxSummary web service allows you to view summary data for one or more card transactions within a given date range. Optional filters allow you to collect summary data by card type, card owner, account number, register, settle or approval status, user, etc. ## Request GetCardTrxSummary(UserName, Password, RPNum, BeginDt, EndDt, ApprovalCode, Register, NameOnCard, CardNum, CardType, ExcludeVoid, User, SettleFlag, SettleMsg, SettleDt, TransformType, Xsl, ColDelim, RowDelim, IncludeHeader, ExtData) ``` TrxDetailSoapClient reporting = new TrxDetailSoapClient("TrxDetailSoap"); reportingResponse = reporting.GetCardTrxSummary("username", "password", "5", "7/11/2016", "7/11/2016", "", "", "", "", "", "true", "", "", "", "", "", "", "", "", "", ""); ``` ## Response ``` VISA 0.0000 0.0000 0.0000 0.0000 0.0000 57185.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0 0 0 0 0 11 0 0 0 0 0 11 ``` View [TrxDetail Response Fields.](#section/trxdetail-response-fields) ## GetCardTrxSummary Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |UserName| User name assigned in the payment server. The user must have an appropriate security permissions in order for the system to return transaction records. |Password| Password for the user name assigned in the payment server. |RPNum| Unique numeric value used to identify the merchant for the query. The RPNum is assigned by the gateway and acts as the primary key for the merchant table. ||Note: RPNum may also be called Merchant ID, Merchant Number, or Vendor Key. |BeginDt| Identifies the beginning date range for a group of transactions. |EndDt| Identifies the ending date range for a group of transactions. |ApprovalCode| The approval code is a 6-character string (alphanumeric) generated by the issuing bank. The code is used the card issuer to verify the specific authorization when transactions are being settled. This field may also be used by payment processors to return error messages. |Optional| Note: You may only query one approval code at a time; however, approval codes are not necessarily unique and there is potential (rare) for more than one record to be returned. |Register Optional| The register is a unique string used to identify the register where the transaction took place. If used, only transactions made with the matching register number will be returned. |NameOnCard Optional| If a card holder name is provided for this parameter, only those transactions with matching cardholder names will be returned. Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234” |CardNum Optional|If a card number is provided for this parameter, only those transactions with matching card numbers will be returned. Matching is done using wild cards. e.g. “test” will match “test”, “1test” and “1test234” |CardType| The card type identifies the type of card used to make the transaction. If one or more card types are provided, only transactions with matching CardType will be included in the results. |Optional| Valid entries are: || - Unused/blank returns summary information for all card types || - ‘AMEX’ – American Express card || - ‘CARTBLANCH’ – Carte Blanch card || - ‘DEBIT’ – Debit card || - ‘DINERS’ – Diners club card || - ‘DISCOVER’ – Discover card || - ‘EBT’ – Electronic benefit transfer || - ‘JAL’ – Japanese Airlines card || - ‘JCB’ – Japanese Commercial Bank card || - ‘MASTERCARD’ – Master card || - ‘VISA’ – Visa card || - ‘EGC’ – Gift card || Or any permutation of the above values, e.g. “’AMEX’,’MASTERCARD’” will pull all transactions with either AMEX or MASTERCARD payment types. || View [ExtData Field Definitions](#section/extdatadef) for more information. |ExcludeVoid| The ExcludeVoid parameter allows you to exclude voided transactions from the result set. ||Valid entries are ||- ‘TRUE’ – voided transactions are excluded from summary information ||- ‘FALSE’ – voided transactions are included from summary information |User| If provided, only transactions generated by users with a matching user ID will be included in the results. Matching is done using wild cards. |Optional| e.g. “test” will match “test”, “1test” and “1test234” |SettleFlag| The SettleFlag parameter allows you to choose whether settled or unsettled transactions are included in the results. |Optional|Valid entries are: ||- Unused/blank returns summary information for settled and unsettled transactions || - ‘1’ – returns only summary information for settled transactions || - ‘0’ – return only summary information for transactions that are not yet settled |SettleMsg Optional| The settlement message is an ID or message returned from the host upon settlement of a transaction. If provided, only the transaction that exactly matches the SettleMsg provided will be returned. |SettleDt Optional| If provided, only transactions that were settled on the same date will be included in the results. |TransformType| Indicates how the result set should be formatted. |Optional| Valid entries are: || - ‘XML’ – outputs a plain XML string || - ‘XSL’ – uses XSL to format the XML output. If ‘XSL’ is selected, use the Xsl parameter to identify the XSL string that will be used to format the output. ||- ‘DELIM’ – outputs records in a delimited format. If ‘DELIM’ is selected, you may also pass values for the ColDelim, RowDelim, and IncludeHeader parameters. |Xsl| This field is used only if the TransformType is XSL. |Optional| If provided, the resulting dataset will be transformed using this XSL. You may pass in a URL to the XSL file, or the XSL string itself. If this field is not empty, the Web Services will try to locate the file from the URL. If that also fails, it will treat it as an XSL string. In any case, the final XSL string will be loaded and validated against the XSL schema; if it passes, then that XSL will be used for transformation. A sample predefined XSL is included with this Web Services: ||_‘https://gateway.ibxpays.com/admin/ws/TabDelim.xsl’_ for a tab delimited transformation |ColDelim| This field is used only if the TransformType is DELIM. This defines the string that separates each column. |Optional| e.g. a value of ‘@’, would separate each column value with ‘@’ |RowDelim| This field is used only if the TransformType is DELIM. This defines the string that separates each row. |Optional| e.g. a value of ‘!’ would start each row with ‘!’ |IncludeHeader| This field is used only if the TransformType is DELIM. If TRUE, then field headers will be included in the first row using the same delimiter strings; must either be TRUE or FALSE |ExtData| The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. |Optional| Extended data in XML format. Valid values are: ||- NO_IMAGE’ – Will only return transaction data _thatdoes not_ include image data (to include signature data and check images) ||- ‘ONLY_IMAGE’ – Will only return transaction data that _includes_ image data (to include signature data and check images) ||- ‘ALL’- will return transaction with or without image data ||- ‘CustomerID’ – specifies the customer ID value to search by. Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234” ||- ‘Amount’ – specifies the amount value of the transactions being searched for. In DDDDDD.CC format ||- ‘_RegisterNum_’ – apecifies the register number, originally passed with the transaction, to search by ||-Timezone – Used to convert the input and output (where applicable) date/time values to the desired timezone. When specified, the same timezone is used to convert the begin/end date parameters as well as the Date and Last Update output values. This field is optional, and if omitted all date/time values are treated as UTC. Daylight savings time adjustments, where applicable, are handled automatically. Accepted values are: || -- AKST – Alaskan Standard Time || -- CST – Central Standard Time || -- EST – Eastern Standard Time || -- HST – Hawaiian Standard Time || -- MST – Mountain Standard Time || -- AZMST – Arizona || -- PST – Pacific Standard Time # 4.3. GetCheckTrx This web service returns one or more check transactions (with details) for a specific merchant. In addition to the basic transaction search function, the GetCheckTrx web service can help you to build a variety of custom reports, aid in data mining applications, and help to automate reconciliation. Custom reports, from customer billing histories to reports that help locate duplicate transactions, and data mining applications – for example, determining what percentage of sales come through a given payment type, are easily constructed by filtering for only the data that is needed. GetCheckTrx can also be used to automate the reconciliation process between the payment server and the point-of-sale (POS) system or register. ## Request GetCheckTrx(UserName, Password, RPNum, PNRef, BeginDt, EndDt, PaymentType, ExcludePaymentType, TransType, ExcludeTransType, ApprovalCode, Result, ExcludeResult, NameOnCheck, CheckNum, AcctNum, RouteNum, ExcludeVoid, User, InvoiceID, SettleFlag, SettleMsg, SettleDt, TransformType, Xsl, ColDelim, RowDelim, IncludeHeader, ExtData) ## Response Response here View [TrxDetail Response Fields.](#section/trxdetail-response-fields) ## GetCheckTrx Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |UserName| User name assigned in the payment server. The user must have appropriate security permissions in order for the system to return transaction records. |Password| Password for the user name assigned in the payment server. |RPNum| Unique numeric value used to identify the merchant for the query. The RPNum is assigned by the gateway and acts as the primary key for the merchant table. || Note: RPNum may also be called Merchant ID, Merchant Number, or Vendor Key. |PNRef| Unique payment reference number used to identify a single transaction within the system. The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created. |Optional| Note: If a PNRef is provided, all other query fields will be ignored. |BeginDt| Identifies the beginning date range for a group of transactions. |Required unless a value of PNRef is provided| |EndDt| Identifies the ending date range for a group of transactions. |Required unless a value of PNRef is provided| |PaymentType| The payment type identifies the payment venue. If one or more payment types are provided, only transactions with matching PaymentType will be included in the results; all other PaymentType values will be excluded. |Optional| Valid entries are: || - ‘ACH’ – Automated Clearing House || - ‘ECHECK’ – Electronic check || - ‘GUARANTEE’ – Guarantee check || - ‘PAYRECEIPT’ – receipt images uploaded to the server || - ‘SETTLE’ – transactions that have been finalized with the payment host || - ‘VERIFY’ – Pre-authorized checks || Note: The default value for this field is “All”. If no value is set, all payment types will be returned in the result set. || Or any permutation of the above values, e.g. “’ACH’,’ECHECK’” will pull all transactions with either ACH or ECHECK payment types. |ExcludePaymentType| The ExcludePaymentType parameter allows you to exclude certain payment types from the result set. Any valid entry (or combination) listed under the PaymentType parameter may be used. |Optional| Note: If you pass the same value in the PaymentType and ExcludePaymentType parameters, the entry in the ExcludePaymentType parameter will override the PaymentType and results of that type will be excluded. || This parameter accepts multiple values. |TransType| If provided, only those transactions matching the TransType will be included. |Optional| Valid values are || - ‘Authorization’ to retrieve previously-authorized (pre-auth) transactions || - ‘Capture’ to retrieve captured transactions || - ‘Credit’ to retrieve return transactions || - ‘ForceCapture’ to retrieve force-auth transactions || - ‘GetStatus’ to make an inquiry to the EBT or gift card’s balance || - ‘PostAuth’ to retrieve post-auth transactions || - ‘Purged’ to remove a transaction from the current batch due to an error || - ‘Receipt’ to retrieve receipt images that were uploaded to the payment server || - ‘RepeatSale’ to retrieve repeat-sale transactions || - ‘Sale’ to retrieve sale transactions || - ‘Void’ to retrieve void transactions || Or any permutation of the above values, e.g. “‘Credit’,’Sale'” will pull all transactions with either Credit or Sale transaction types. |ExcludeTransType| The ExcludeTransType parameter allows you to exclude certain transaction types from the result set. Any valid entry (or combination) listed under the TransType parameter may be used. |Optional| Note: If you pass the same value in the TransType and ExcludeTransType parameters, the entry in the ExcludeTransType parameter will override the TransType and results of that type will be excluded. || Note: A value of ‘Void’ in the ExcludeTransType parameter will be overridden by the ExcludeVoid if both parameters are used. ||This parameter accepts multiple values. |ApprovalCode| The approval code is a 6-character string (alphanumeric) generated by the issuing bank. The code is used the card issuer to verify the specific authorization when transactions are being settled. |Optional| Note: You may only query one approval code at a time; however, approval codes are not necessarily unique and there is potential (rare) for more than one record to be returned. |Result| The result indicates whether a transaction was approved (Result = 0) or declined (Result ≠ 0). |Optional| Valid entries are: || - Unused/blank returns both approved and declined transactions || - 0 – returns only approved transactions || Note: To return only declined transactions, leave this parameter blank and use the ExcludeResult parameter. |ExcludeResult| The result indicates whether a transaction was approved (Result = 0) or declined (Result ≠ 0). If provided, any transactions matching the ExcludeResult input will be excluded. |Optional| Note: To return a only declined transactions, set ExcludeResult = 0 |NameOnCheck Optional| If an owner’s name is provided for this parameter, only those transactions with matching names will be returned. Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234” |CheckNum Optional| If a check number is provided for this parameter, only those transactions with a matching check number will be returned. |AcctNum Optional| If a checking account number is provided, only those transactions with matching account numbers will be returned. Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234” |RouteNum Optional | If a route number (transit number) is provided, only those transactions with matching route numbers will be returned. Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234” |ExcludeVoid| The ExcludeVoid parameter allows you to exclude voided transactions from the result set. |Optional| Valid entries are: || - ‘TRUE’ – voided transactions are excluded || - ‘FALSE’ – voided transactions are included |User Optional| If provided, only transactions generated by users with a matching user ID will be included in the results. Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234” |InvoiceID Optional | The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice. If provided, only transactions with a matching invoice ID will be included in the results. Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234” |SettleFlag| The SettleFlag parameter allows you to choose whether settled or unsettled transactions are included in the results. |Optional| Valid entries are: || - Unused/blank returns all transactions || - ‘1’ – returns only settled transactions || - ‘0‘- return only transactions that are not yet settled |SettleMsg| The settlement message is an ID or message returned from the host upon settlement of a transaction. If provided, only the transaction that exactly matches the SettleMsg provided will be returned. |Optional| Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234” |SettleDt Optional| If provided, only transactions that were settled on the same date will be included in the results. |TransformType| Indicates how the result set should be formatted. |Optional | Valid entries are: || - ‘XML’ – outputs a plain XML string || - ‘XSL’ – uses XSL to format the XML output. If ‘XSL’ is selected, use the Xsl parameter to identify the XSL string that will be used to format the output. || - ‘DELIM’ – outputs records in a delimited format. If ‘DELIM’ is selected, you may also pass values for the ColDelim, RowDelim, and IncludeHeader parameters. |Xsl| This field is used only if the TransformType is XSL. |Optional| If provided, the resulting dataset will be transformed using this XSL. You may pass in a URL to the XSL file, or the XSL string itself. If this field is not empty, the Web Services will try to locate the file from the URL. If that also fails, it will treat it as an XSL string. In any case, the final XSL string will be loaded and validated against the XSL schema; if it passes, then that XSL will be used for transformation. A sample predefined XSL is included with this Web Services: || _‘https://gateway.ibxpays.com/admin/ws/TabDelim.xsl’_ for a tab delimited transformation |ColDelim| This field is used only if the TransformType is DELIM. This defines the string that separates each column. |Optional| e.g. a value of ‘@’, would separate each column value with ‘@’ |RowDelim| This field is used only if the TransformType is DELIM. This defines the string that separates each row. |Optional| e.g. a value of ‘!’ would start each row with ‘!’ |IncludeHeader | This field is used only if the TransformType is DELIM. |Optional| If TRUE, then field headers will be included in the first row using the same delimiter strings; must either be TRUE or FALSE. |ExtData| The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. |Optional| Extended data in XML format. Valid values are: ||- ‘NO_IMAGE’ – Will only return transaction data that _does not_ include image data (to include signature data and check images) || - ‘ONLY_IMAGE’ – Will only return transaction data that _includes_ image data (to include signature data and check images) || - ‘ALL’- will return transaction with or without image data || ‘_CustomerID_’ – specifies the customer ID value to search by. Matching is done using wild cards: e.g. “test” will match “test”, “1test” and “1test234” || ‘_Amount_’ – specifies the amount value of the transactions being searched for. In DDDDDD.CC format ||‘_RegisterNum_’ – apecifies the register number, originally passed with the transaction, to search by ||Timezone – Used to convert the input and output (where applicable) date/time values to the desired timezone. When specified, the same timezone is used to convert the begin/end date parameters as well as the Date and Last Update output values. This field is optional, and if omitted all date/time values are treated as UTC. Daylight savings time adjustments, where applicable, are handled automatically. Accepted values are: || -- AKST – Alaskan Standard Time || -- CST – Central Standard Time || -- EST – Eastern Standard Time || -- HST – Hawaiian Standard Time || -- MST – Mountain Standard Time || -- AZMST – Arizona || -- PST – Pacific Standard Time # 4.4. GetOpenBatchSummary This web service retrieves a payment type transaction summary of the current open batch for a specified merchant. ## Request GetOpenBatchSummary(username, password, rpNum, beginDt, endDt, extData) ## Response Response here View [TrxDetail Response Fields.](#section/trxdetail-response-fields) ## GetOpenBatchSummary Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |UserName| User name assigned in the payment server. The user must have appropriate security permissions in order for the system to return transaction records. |Password| Password for the user name assigned in the payment server. |RPNum| Unique numeric value used to identify the merchant for the query. The RPNum is assigned by the gateway and acts as the primary key for the merchant table. || Note: RPNum may also be called Merchant ID, Merchant Number, or Vendor Key. |BeginDt| Identifies the beginning date range for a group of transactions. |EndDt| Identifies the ending date range for a group of transactions. |ExtData| The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. |Optional| Extended data in XML format. Valid values are: ||Timezone – Used to convert the input and output (where applicable) date/time values to the desired timezone. When specified, the same timezone is used to convert the begin/end date parameters as well as the Date and Last Update output values. This field is optional, and if omitted all date/time values are treated as UTC. Daylight savings time adjustments, where applicable, are handled automatically. Accepted values are: || -- AKST – Alaskan Standard Time || -- CST – Central Standard Time || -- EST – Eastern Standard Time || -- HST – Hawaiian Standard Time || -- MST – Mountain Standard Time || -- AZMST – Arizona || -- PST – Pacific Standard Time # 4.5. TRXDetail Response Fields The following response fields may be part of the return value for web services using TrxDetail.asmx operations. These web services include: - GetCardTrx - GetCardTrxSummary - GetCheckTrx - GetOpenBatchSummary | Response Field and Data Value| Description |-----|----- |Account_Type_CH | Returns the card type of the transaction, e.g. VISA, Diners, EBT. |String up to 10 characters | |AccountNum_VC | Returns the check account number. |String up to 200 characters | This field will be masked out with asterisk (*) characters except for the last 4 digits if the System Security Level of the user is set to 1. |Acct_Num_CH | Returns credit card number. |String up to 200 characters | This field will be masked out with asterisk (*) characters except for the last 4 digits if the System Security Level of the user is set to 1. | Amount_MN| Returns the check’s total amount. |String representing a signed 64-bit real number | | Approval_Code_CH| Returns the response code from the payment processor. |String up to 50 characters | |Auth_Amt_MN | Returns the authorized amount of a card transaction. |String representing a signed 64-bit real number | |Authorization | Returns the dollar amount of all Authorization (PreAuth) transactions. |String representing a signed 64-bit real number | |Authorization_Cnt | Returns the transaction count of all Authorization (PreAuth) transactions. |String representing a signed 32-bit integer | |AVS_Resp_CH | Returns the address verification result code from the payment processor. |String up to 1 character | |AVS_Resp_Txt_VC | Returns the formatted response message when address verification is performed. |String up to 25 characters | |Batch_Number | Returns the batch number for the transaction that was returned by the payment processor. |String up to 10 characters | Not all payment processors support returning this data element. |Capture | Returns the dollar amount of all Capture transactions. |String representing a signed 64-bit real number | This value will always return “0”. | Capture_Cnt| Returns the transaction count of all Capture transactions. |String representing a signed 32-bit integer | This value will always return “0”. |Card_Info_Key | Returns the primary key of the CC_Info_T table in the database. |String representing a signed 32-bit integer | |Cash_Back_Amt_MN | Returns the cash back amount for a debit or EBT transaction. |String representing a signed 64-bit real number | |CheckNum_CH | Returns the check number. |String up to 10 characters | |Cnt | Returns the transaction count of all transactions. |String representing a signed 32-bit integer | |CustomerID | Returns the Customer ID of a customer to which the transaction belongs to |String up to 50 characters | |CV_Resp_CH | Returns the card verification result code from the payment processor. |String up to 1 character | |CV_Resp_Txt_VC | Returns the formatted response message when card verification is performed. |String up to 25 characters | |Date_DT | Returns the date on which the transaction is first made. |String representing a date and time | |ERROR |Returns an error message when a problem occurs during the transaction processing. |String up to 200 characters | |Exp_CH |Returns the credit card expiration date. |String up to 10 characters | |ForceCapture |Returns the dollar amount of all ForceCapture (ForceAuth) transactions. |String representing a signed 64-bit real number | |ForceCapture_Cnt | Returns the transaction count of all ForceCapture (ForceAuth) transactions. |String representing a signed 32-bit integer | |Host_Date_CH | Returns the payment processor’s date on which the transaction is performed. |String up to 10 characters | |Host_Ref_Num_CH | Returns a number which uniquely identifies the transaction for the payment processor. |String up to 30 characters | |Host_Time_CH | Returns the payment processor’s time at which the transaction was performed. |String up to 10 characters | |Invoice_ID | Returns the transaction’s Invoice number. |String up to 100 characters | |IP_VC | Returns the IP address of the client machine from which the transaction was processed. |String up to 15 characters | |Last_Update_DT | Returns the date and time on which the transaction is last modified. |String representing a date and time | |Manual | Returns the card was swiped or not. |String representing a Boolean value | |Merchant_Key | Returns a number which uniquely identifies a merchant. |String representing a signed 32-bit integer | |Name_on_Card_VC | Returns the name of the cardholder. |String up to 25 characters | |NameOnCheck_VC | Returns the check payer’s name on the check. |String up to 25 characters | | Orig_TRX_HD_Key| Returns the TRX_HD_Key on which the current transaction is based. |String representing a signed 32-bit integer | |Payment_Type_ID | Returns the payment type, e.g. ECHECK. |String up to 10 characters | |PostAuth | Returns the dollar amount of all PostAuth transactions. |String representing a signed 64-bit real number | |PostAuth_Cnt | Returns the transaction count of all PostAuth transactions. | String representing a signed 32-bit integer| | Processor_ID| Returns the name the payment processor, e.g. Vital. |String up to 10 characters | |Receipt |Returns the dollar amount of all transactions with a Receipt. |String representing a signed 64-bit real number |This value will always return “0”. |Receipt_Cnt | Returns the transaction count of all transactions with a Receipt. |String representing a signed 32-bit integer | This value will always return “0”. |Ref_Number_CH | Not currently used. |String | This field is not the unique transaction identifier (also called PNRef) of the Payment Server. See the field TRX_HD_Key for the PNRef value. |Register_Number_CH | Returns the register number of a transaction. |String up to 10 characters | |RepeatSale |Returns the dollar amount of all RepeatSale (Recurring Billing/Installment) transactions. |String representing a signed 64-bit real number | |RepeatSale_Cnt | Returns the transaction count of all RepeatSale (Recurring Billing/Installment) transactions. |String representing a signed 32-bit integer | | Reseller_Key| Returns the primary key of the Reseller_T table in the database. |String representing a signed 32-bit integer | |Result_CH | Returns the transaction processing result. | String up to 50 characters| e.g. 0, 12. “0” for approval, “12” for decline |Result_Msg_VC | Returns the check transaction’s processing result. |String up to 50 characters | |Result_Msg1_VC | Returns an extra formatted response message giving more information about the processed transaction. |String up to 50 characters | |Result_Msg2_VC | Returns an extra formatted response message giving more information about the processed transaction. |String up to 50 characters | | Result_Txt_VC| Returns the text message of either approval or decline for the transaction processing result. |String up to 150 characters | |Return | Returns the dollar amount of all Return (Credit) transactions. |String representing a signed 64-bit real number | |Return_Cnt | Returns the transaction count of all Return (Credit) transactions. |String representing a signed 32-bit integer | |Sale | Returns the dollar amount of all Sale transactions. |String representing a signed 64-bit real number | |Sale_Cnt | Returns the transaction count of all Sale transactions. | String representing a signed 32-bit integer| |Settle_Date_DT | Returns the date on which the transaction is settled. |String representing a date and time | |Settle_Flag_CH | Returns if the transaction is settled or not. | String representing value of |0=Not Settled | |1=Settled | |2=Rolled Back/Indeterminate | |5=In Progress | |StateCode_CH | Returns the state code. |String up to 10 characters | |Street_CH | Returns the billing street address of the credit card. |String up to 25 characters | |SureCharge_Amt_MN | Returns the sure charge amount of a transaction. |String representing a signed 64-bit real number | |Tip_Amt_MN | Returns the tip amount of a transaction. |String representing a signed 64-bit real number | |Trans_Type_ID | Returns the transaction type, e.g. Sale, Credit. |String up to 20 characters | |Transport_Method | Returns the Transportation Method. |String | Only for use with Dial-up transactions. |Transport_EndPoint | Returns the Transportation’s Ending Destination. |String | Only for use with Dial-up transactions. |TransitNum_VC | Returns the transit/routing number. |String up to 200 characters | This field will be masked out with asterisk (*) characters except for the last 4 digits if the System Security Level of the user is set to 1. |TRX_Card_Key | Returns the primary key of the TRX_Card_T table in the database. |String representing a signed 32-bit integer | |TRX_Check_Key | Returns the primary key of the TRX_Check_T table in the database. |String representing a signed 32-bit integer | |TRX_HD_Key | Returns the primary key of the TRX_Header_T table in the database. |String representing a signed 32-bit integer | This field is the unique transaction identifier (also called PNRef) of the Payment Server. Use its value when submitting transactions based on a previous transaction (i.e. Voids) through the Transact.asmx Web Service. | TRX_Settle_Key| Returns the primary key of the TRX_Settle_T table in the database. |String representing a signed 32-bit integer | |TRX_Settle_Msg_VC |Returns the transaction’s settlement message. |String up to 25 characters | |Type_CH | Returns the credit card type, e.g. VISA, MASTERCARD. |String up to 10 characters | |User_Name_VC | Returns the username, under which the transactions were made. |String up to 25 characters | |Void_Flag_CH | Returns the transaction is voided or not. |String representing a Boolean value | |Zip_CH | Returns the billing zip code of the credit card. |String up to 10 characters | |Auth_Amt_MN | Returns the authorized amount of a card transaction. |String representing a signed 64-bit real number | |Authorization | Returns the dollar amount of all Authorization (PreAuth) transactions. |String representing a signed 64-bit real number | | Authorization_Cnt| Returns the transaction count of all Authorization (PreAuth) transactions. |String representing a signed 32-bit integer | |AVS_Resp_CH | Returns the address verification result code from the payment processor. |String up to 1 character | |AVS_Resp_Txt_VC | Returns the formatted response message when address verification is performed. |String up to 25 characters | |Batch_Number | Returns the batch number for the transaction that was returned by the payment processor. |String up to 10 characters | Not all payment processors support returning this data element. |Capture | Returns the dollar amount of all Capture transactions. | String representing a signed 64-bit real number| This value will always return “0”. |Capture_Cnt | Returns the transaction count of all Capture transactions. |String representing a signed 32-bit integer | This value will always return “0”. |Card_Info_Key | Returns the primary key of the CC_Info_T table in the database. |String representing a signed 32-bit integer | |Cash_Back_Amt_MN | Returns the cash back amount for a debit or EBT transaction. |String representing a signed 64-bit real number | |CheckNum_CH | Returns the check number. |String up to 10 characters | |Cnt | Returns the transaction count of all transactions. |String representing a signed 32-bit integer | |CustomerID | Returns the Customer ID of a customer to which the transaction belongs to. |String up to 50 characters | |CV_Resp_CH | Returns the card verification result code from the payment processor. |String up to 1 character | | CV_Resp_Txt_VC| Returns the formatted response message when card verification is performed. |String up to 25 characters | |Date_DT | Returns the date on which the transaction is first made. |String representing a date and time | |ERROR | Returns an error message when a problem occurs during the transaction processing. |String up to 200 characters | |Exp_CH |Returns the credit card expiration date. |String up to 10 characters | |ForceCapture | Returns the dollar amount of all ForceCapture (ForceAuth) transactions. |String representing a signed 64-bit real number | |ForceCapture_Cnt | Returns the transaction count of all ForceCapture (ForceAuth) transactions. |String representing a signed 32-bit integer | | Host_Date_CH| Returns the payment processor’s date on which the transaction is performed. |String up to 10 characters | |Host_Ref_Num_CH | Returns a number which uniquely identifies the transaction for the payment processor. |String up to 30 characters | |Host_Time_CH | Returns the payment processor’s time at which the transaction was performed. |String up to 10 characters | |Invoice_ID |Returns the transaction’s Invoice number. |String up to 100 characters | |IP_VC | Returns the IP address of the client machine from which the transaction was processed. |String up to 15 characters | |Last_Update_DT | Returns the date and time on which the transaction is last modified. |String representing a date and time | |Manual | Returns the card was swiped or not. |String representing a Boolean value | |Merchant_Key | Returns a number which uniquely identifies a merchant. |String representing a signed 32-bit integer | |Name_on_Card_VC | Returns the name of the cardholder. |String up to 25 characters | |NameOnCheck_VC | Returns the check payer’s name on the check. |String up to 25 characters | |Orig_TRX_HD_Key |Returns the TRX_HD_Key on which the current transaction is based. |String representing a signed 32-bit integer | |Payment_Type_ID | Returns the payment type, e.g. ECHECK. |String up to 10 characters | |PostAuth | Returns the dollar amount of all PostAuth transactions. |String representing a signed 64-bit real number | |PostAuth_Cnt | Returns the transaction count of all PostAuth transactions. |String representing a signed 32-bit integer | |Processor_ID | Returns the name the payment processor, e.g. Vital. |String up to 10 characters | |Receipt | Returns the dollar amount of all transactions with a Receipt. |String representing a signed 64-bit real number | This value will always return “0”. |Receipt_Cnt | Returns the transaction count of all transactions with a Receipt. |String representing a signed 32-bit integer | This value will always return “0”. |Ref_Number_CH | Not currently used. |String | This field is not the unique transaction identifier (also called PNRef) of the Payment Server. See the field TRX_HD_Key for the PNRef value. | Register_Number_CH| Returns the register number of a transaction. |String up to 10 characters | |RepeatSale | Returns the dollar amount of all RepeatSale (Recurring Billing/Installment) transactions. |String representing a signed 64-bit real number | |RepeatSale_Cnt | Returns the transaction count of all RepeatSale (Recurring Billing/Installment) transaction. |String representing a signed 32-bit integer | |Reseller_Key | Returns the primary key of the Reseller_T table in the database. |String representing a signed 32-bit integer | |Result_CH | Returns the transaction processing result, e.g. 0, 12. “0” for approval, “12” for decline. |String up to 50 characters | |Result_Msg_VC | Returns the check transaction’s processing result. |String up to 50 characters | |Result_Msg1_VC | Returns an extra formatted response message giving more information about the processed transaction. |String up to 50 characters | |Result_Msg2_VC | Returns an extra formatted response message giving more information about the processed transaction. |String up to 50 characters | |Result_Txt_VC | Returns the text message of either approval or decline for the transaction processing result. |String up to 150 characters | |Return | Returns the dollar amount of all Return (Credit) transactions. | String representing a signed 64-bit real number| |Return_Cnt | Returns the transaction count of all Return (Credit) transactions. |String representing a signed 32-bit integer | |Sale | Returns the dollar amount of all Sale transactions. |String representing a signed 64-bit real number | |Sale_Cnt |Returns the transaction count of all Sale. |String representing a signed 32-bit integer | |Settle_Date_DT | Returns the date on which the transaction is settled. |String representing a date and time | |Settle_Flag_CH | Returns if the transaction is settled or not. |String representing a Boolean value | |StateCode_CH | Returns the state code. |String up to 10 characters | |Street_CH | Returns the billing street address of the credit card. |String up to 25 characters | |SureCharge_Amt_MN | Returns the sure charge amount of a transaction. |String representing a signed 64-bit real number | |Tip_Amt_MN | Returns the tip amount of a transaction. |String representing a signed 64-bit real number | |Total_Amt_MN | Returns the total amount of a transaction. |String representing a signed 64-bit real number | |Trans_Type_ID | Returns the transaction type, e.g. Sale, Credit. |String up to 20 characters | |Transport_Method | Returns the Transportation Method. |String | Only for use with Dial-up transactions. |Transport_EndPoint | Returns the Transportation’s Ending Destination. |String | Only for use with Dial-up transactions. |TransitNum_VC | Returns the transit/routing number. |String up to 200 characters | This field will be masked out with asterisk (*) characters except for the last 4 digits if the System Security Level of the user is set to 1. |TRX_Card_Key | Returns the primary key of the TRX_Card_T table in the database. |String representing a signed 32-bit integer | |TRX_Check_Key | Returns the primary key of the TRX_Check_T table in the database. |String representing a signed 32-bit integer | |TRX_HD_Key | Returns the primary key of the TRX_Header_T table in the database. |String representing a signed 32-bit integer | This field is the unique transaction identifier (also called PNRef) of the Payment Server. Use its value when submitting transactions based on a previous transaction (i.e. Voids) through the Transact.asmx Web Service. |TRX_Settle_Key | Returns the primary key of the TRX_Settle_T table in the database. |String representing a signed 32-bit integer | |TRX_Settle_Msg_VC | Returns the transaction’s settlement message. |String up to 25 characters | |Type_CH | Returns the credit card type, e.g. VISA, MASTERCARD.. |String up to 10 characters | |User_Name_VC | Returns the username, under which the transactions were made. |String up to 25 characters | |Void_Flag_CH |Returns the transaction is voided or not. |String representing a Boolean value | |Zip_CH | Returns the billing zip code of the credit card. |String up to 10 characters | # 5. Recurring Billing # 5.1. ManageCustomer This service is used to add, update, or delete a recurring billing customer record. Calling this service is the first step towards succesfully storing and initiating recurring payments. See Developer’s Notes for information about [Recurring Billing Web Services.](#section/recur) ## Request ManageCustomer(Username, Password, TransType, Vendor, CustomerKey, CustomerID, CustomerName, FirstName, LastName, Title, Department, Street1, Street2, Street3, City, StateID, Province, Zip, CountryID, Email, DayPhone, NightPhone, Fax, Mobile, Status, ExtData) ``` RecurringSoapClient recurring = new RecurringSoapClient("RecurringSoap"); recurringResult = recurring.ManageCustomer("username", "password", "ADD", "5", "", "Stonebreaker", "Rocks and Stones", "Barney", "Rubble", "Senior VP", "Countertops", "111 Bedrock Lane", "Suite 555", "", "Bedrock", "IL", "", "90210", "USA", "barney@rubble.net", "630-555-1212", "847-555-1212", "", "630-555-1313", "", ""); ``` ## Response ``` AuthCode null string CcInfoKey null string CheckInfoKey null string ContractKey null string CustomerKey "26" string ExtData null string Message null string PNRef null string Partner "" string Result null string Username "username" string Vendor "5" string code OK ResultCode error "OK" string ``` View [RecurringResult Response Fields.](#section/recurringresult-response-fields) ## ManageCustomer Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |Username | User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service. |Password | Password associated with the user name provided. |TransType | Indicates whether the contract is being added, updated, or deleted. | | Valid entries are: | | - ADD | | - UPDATE | | - DELETE | |**Important Note:** Passing in ‘NULL’ values to this service with a TransType of ‘UPDATE’ will override existing values to ‘NULL’. It is very important that all data be updated when making this web service call. | Vendor| Unique numeric value used to identify the merchant. | | Note: Vendor key may also be called Merchant ID, Merchant Number, or RPNum. To locate your Vendor key on the virtual terminal, click Password under the Preferences menu. |CustomerKey | Unique identifier assigned to the customer record by the system at the time the customer record is created. |Required when TransType=UPDATE | Note: The CustomerKey value can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerKey appears in the Key column. |CustomerID | Unique identifier assigned to the customer by the merchant at the time the customer record is created. | |Note: The CustomerID value can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerID appears in the Customer ID column. |CustomerName | Individual or customer business name. | |Note: The CustomerName can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerName appears in the Customer Name column. |FirstName | Customer contact first name. |Optional | |LastName | Customer contact last name. |Optional | |Title | Customer contact job or professional title. For example, “Business Unit Manager,” or “Dr.” |Optional | |Department | Customer contact department. For example, “Sales,” or “Operations.” |Optional | |Street1 | Customer contact street address – line 1. |Optional | |Street2 | Customer contact street address – line 2. |Optional | |Street3 | Customer contact street address – line 3. |Optional | |City | Customer contact city. |Optional | |StateID | Customer contact’s standard U.S. postal service two-character state code (U.S. customers only). |Optional | Note: Valid entries are standard U.S. Postal service two-character state codes. For more information, see [http://pe.usps.gov/text/pub28/28apb.htm.] |Province | Customer contact’s province (countries outside the U.S., only). |Optional | |Zip | Customer contact’s zip or postal code. |Optional | |CountryID | Customer contact’s three-character country code. For example, USA = United States or CAN = Canada. |Optional | |DayPhone | Customer contact’s daytime phone number. |Optional | |NightPhone | Customer contact’s after-hours phone number. |Optional | |Fax | Customer contact’s fax number. |Optional | |Email | Customer contact’s email address. |Optional | |Mobile |Customer contact’s mobile phone number. |Optional | |Status | Indicates whether the customer record is currently active or inactive. |Optional | Valid values are: | | - ACTIVE | | - INACTIVE | | - PENDING | | - CLOSED |ExtData | Reserved for future use. |Optional | # 5.2. ManageCreditCardInfo This service allows you to store a credit card number securely within the Payment Server database. Calling this service is the second step towards successfully storing and initiating recurring payments if a credit card is to be the preferred method of payment. See Developer’s Notes for information about [Recurring Billing Web Services.](#section/recur) ## Request ManageCreditCardInfo(Username, Password, TransType, Vendor, CustomerKey, CardInfoKey, CcAccountNum, CcExpDate, CcNameOnCard, CcStreet, CcZip, ExtData) Note: The customerKey in the call below is obtained in the response to the [ManageCustomer](#section/managecustomer) call. ``` RecurringSoapClient recurring = new RecurringSoapClient("RecurringSoap"); recurringResult = recurring.ManageCreditCardInfo( "username", "password", "ADD", "5", customerKey, "", "4012888888881881", "1216", "Barney Rubble", "", "90210", ""); ``` ## Response ``` AuthCode null string CcInfoKey "13581" string CheckInfoKey "" string ContractKey "" string CustomerKey "26" string ExtData null string Message null string PNRef null string Partner "100" string Result null string Username "username" string Vendor "5" string code OK ResultCode ``` View [RecurringResult Response Fields.](#section/recurringresult-response-fields) ## ManageCreditCardInfo Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |Username| User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service. |Password| Password associated with the user name provided. |TransType| Indicates whether the contract is being added, updated, or deleted. ||Valid entries are: || - ADD || - UPDATE || - DELETE |Vendor| Unique numeric value used to identify the merchant. || Note: Vendor key may also be called Merchant ID, Merchant Number, or RPNum. To locate your Vendor key on the virtual terminal, click Password under the Preferences menu. |CustomerKey| Unique identifier assigned to the customer record by the system at the time the customer record is created. ||Note: The CustomerKey value can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerKey appears in the Key column. |CardInfoKey| Numerical key value assigned to the payment method when it was added to the system. |Optional| |CcAccountNum| Credit card number used to uniquely identify the card owner’s account. |Optional| |CcExpDate| Credit card date of expiration in MMYY format. |CcNameOnCard| Card owner’s name as it appears on the card. |Optional| |CcStreet|Card owner’s billing address street name and number. |Optional| |CcZip| Card owner’s billing address postal/zip code. |Optional| |ExtData| Reserved for future use. |Optional| # 5.3. ManageCheckInfo This service allows you to store a checking account number securely within the Payment Server database. Calling this service is the second step towards successfully storing and initiating recurring payments if ACH or ECHECKs are to be the preferred method of payment. See Developer’s Notes for information about [Recurring Billing Web Services.](#section/recur) ## Request ManageCheckInfo(Username, Password, Vendor, TransType, CustomerKey, CheckInfoKey, CheckType, AccountType, CheckNum, MICR, AccountNum, TransitNum, RawMICR, SS, DOB, BranchCity, DL, StateCode, NameOnCheck, Email, DayPhone, Street1, Street2, Street3, City, StateID, Province, PostCode, CountryID, ExtData) ## Response Response here View [RecurringResult Response Fields.](#section/recurringresult-response-fields) ## ManageCheckInfo Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |Username | User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service. |Password | Password associated with the user name provided. |TransType | Indicates whether the contract is being added, updated, or deleted. | | Valid entries are: | | - ADD | | - UPDATE | | - DELETE |CustomerKey | Unique identifier assigned to the customer record by the system at the time the customer record is created. | | Note: The CustomerKey value can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerKey appears in the Key column. |CheckInfoKey | Numerical key value assigned to the payment method when it was added to the system. |Required when TransType=UPDATE or DELETE | |CheckType | Identifies the type of check as a personal or business check. | |Valid values are: | |- PERSONAL – Check is made from an individual (personal) checking account | | - BUSINESS – Check is made from a business checking account |AccountType | Indicates whether the funds come from a checking or savings account. | |Valid values are: | |- CHECKING – Check is made from a standard checking account or ACH | | - SAVINGS – Check is made from a savings account |CheckNum | Uniquely identifies an individual’s check. |Optional | |MICR | Magnetic Ink Check Reader data line. This data string includes the TransitNum and AccountNum. |Optional | Note: This parameter should be used if the developer knows the precise format for the MICR that is supported by the check processor. If the precise format is unknown, the raw MICR should also be included with the transaction. See the tag under the ExtData parameter for additional information. |AccountNum | Uniquely identifies the check owner’s bank account. | TransitNum| Uniquely identifies the bank holding funds. Also called routing number. |RawMICR | The raw MICR format certain check readers produce. |Optional | |SS | Check owner’s Social Security number. |Optional | |DOB | Check owner’s date of birth. |Optional | |BranchCity |City where the issuing bank branch is located. |Optional | |DL| Check owner’s driver’s license number. |Optional| |StateCode| Check owner’s standard U.S. postal service two-character state code or other standard province code. |Optional|Note: Valid entries should follow USPS two-character state code standards. For more information, see [http://pe.usps.gov/text/pub28/28apb.htm]. ||See [Invalid Character Processing.](#section/invalidchar) |NameOnCheck| Check owner’s name as it appears on the check. |Optional| See [Invalid Character Processing.](#section/invalidchar) |NameOnCheck| Check owner’s name as it appears on the check. |Email| Customer contact’s email address. |Optional| |DayPhone| Customer contact’s daytime phone number. |Optional| |Street1| Customer contact street address – line 1. |Optional| |Street2| Customer contact street address – line 2. |Optional| |Street3| Customer contact street address – line 3. |Optional| |City| Customer contact city. |Optional| |StateID| Customer contact’s standard U.S. postal service two-character state code (U.S. customers only). |Optional| |Province| Customer contact’s province (countries outside the U.S., only). |Optional| |PostCode| Customer contact’s zip or postal code. |Optional| |CountryID| Customer contact’s three-character country code. For example, USA = United States or CAN = Canada. |Optional| |ExtData| Reserved for future use. |Optional| # 5.4. ManageContract This service allows the integrator to add, update, or delete the terms and interval of a recurring billing contract. See Developer’s Notes for information about [Recurring Billing Web Services.](#section/recur) ## Request ManageContract(Username, Password, TransType, Vendor, CustomerKey, ContractKey, PaymentInfoKey, PaymentType, CustomerID, CustomerName, FirstName, LastName, Department, Street1, Street2, Street3, City, StateID, Province, Zip, CountryID, DayPhone, NightPhone, Fax, Email, Mobile, ContractID, ContractName, BillAmt, TaxAmt, TotalAmt, StartDate, EndDate, NextBillDt, BillingPeriod, BillingInterval, MaxFailures, FailureInterval, EmailCustomer, EmailMerchant, EmailCustomerFailure, EmailMerchantFailure, Status, ExtData) Note: The ccInfoKey in the call below is obtained in the response to the [ManageCreditCardInfo](#section/recur) call ``` RecurringSoapClient recurring = new RecurringSoapClient("RecurringSoap"); recurringResult = recurring.ManageContract( "username", "password", "ADD", "5", customerKey, "", ccInfoKey, "CC", "Stonebreaker1", "Rocks and Stones", "","","","","","","","","","","","","barney@rubble.com","", "", "", "", "Sidewalk deliveries ID", "Sidewalk deliveries name", "200.87", "1.37", "202.24", "7/1/2016", "12/1/2016", "8/1/2016", "MONTH", "1", "2", "", "TRUE", "FALSE", "TRUE", "FALSE", "", ""); ``` ## Response ``` AuthCode null string CcInfoKey "13581" string CheckInfoKey "" string ContractKey "8" string CustomerKey "26" string ExtData null string Message null string PNRef null string Partner "100" string Result null string Username "username" string Vendor "5" string code OK ResultCode error "OK" string ``` View [RecurringResult Response Fields.](#section/recurringresult-response-fields) ## ManageContract Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |Username | User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service. |Password | Password associated with the user name provided. |TransType | Indicates whether the contract is being added, updated, or deleted. | | Valid entries are: | | - ADD | | - UPDATE | | - DELETE |Vendor | Unique numeric value used to identify the merchant. | | Note: Vendor key may also be called Merchant ID, Merchant Number, or RPNum. To locate your Vendor key on the virtual terminal, click Password under the Preferences menu. |CustomerKey | Unique identifier assigned to the customer record by the system at the time the customer record is created. | | Note: The CustomerKey value can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerKey appears in the Key column. |ContractKey | Unique identifier assigned to the contract by the system at the time the contract record is created. |Required when TransType=UPDATE or DELETE | Note: The ContractKey value appears in the return results (see tags) when a new contract is added to the system. |PaymentInfoKey | Information passed in the PaymentInfoKey parameter will vary depending on the PaymentType value passed. |Required when TransType=ADD or UPDATE | - If a PaymentType of CC (credit card) is passed, send the CardInfoKey value | | - If a PaymentType of CK (check) is passed, send the CheckInfoKey value |PaymentType | Identifies the type of payment method used. |Required when TransType=ADD or UPDATE | Valid values are: | | - CC – Credit card | | - CK – Check/ACH | | Note: This parameter is case sensitive. Lower case entries will result in an error. |CustomerID | Unique identifier assigned to the customer by the merchant at the time the customer record is created. | |Note: The CustomerID value can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerID appears in the Customer ID column. |CustomerName | Individual or customer business name. | |Note: The CustomerName can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerName appears in the Customer Name column. |FirstName | Customer contact first name. |Optional | |LastName | Customer contact last name. |Optional | |Department | Customer contact department. For example, “Sales,” or “Operations.” | Optional| |Street1 | Customer contact street address – line 1. |Optional | |Street2 | Customer contact street address – line 2. |Optional | |Street3 | Customer contact street address – line 3. |Optional | |City | Customer contact city. |Optional | |StateID | Customer contact’s standard U.S. postal service two-character state code (U.S. customers only). |Optional | Note: Valid entries are standard U.S. Postal service two-character state codes. For more information, see [http://pe.usps.gov/text/pub28/28apb.htm.] |Province | Customer contact’s province (countries outside the U.S., only). |Optional | |Zip | Customer contact’s zip or postal code. |Optional | |CountryID | Customer contact’s three-character country code. For example, USA = United States or CAN = Canada. |Optional | |DayPhone | Customer contact’s daytime phone number. |Optional | |NightPhone | Customer contact’s after-hours phone number. |Optional | |Fax | Customer contact’s fax number. |Optional | |Email | Customer contact’s email address. |Optional | |Mobile |Customer contact’s mobile phone number. |Optional | |ContractID | Unique identifier assigned to the contract by the merchant at the time the contract record is created. | |Note: The ContractKey value can be found on the virtual terminal by accessing the View Contracts option under the Recurring Billing menu. Display a list of contracts by entering search criteria. The ContractKey appears in the Contract ID column. |ContractName | Name assigned to the contract (used for easier identification). |Optional | |BillAmt | Amount billed each time the contract comes due in DD.CCCC format. |TaxAmt | Additional tax amount applied to the BillAmt each time the contract comes due in DD.CCCC format. |Optional | |TotalAmt | Total amount billed each time the contract comes due in DD.CCCC format. | |BillAmt + TaxAmt = TotalAmt |StartDate | Date that the contract becomes effective in MM/DD/YYYY format. The start date must be greater than today’s date. | |The StartDate represents the first time the customer will be billed per the contract. Future bill dates are calculated using the BillingPeriod and BillingInterval parameters. |EndDate | Date that the contract is completed in MM/DD/YYYY format. The end date must be greater than the start date. |NextBillDt |Identifies the next time the contract will come due in MM/DD/YYYY format. |Required when TransType=ADD or UPDATE | Note: The NextBillDe can be found on the contract detail in the virtual terminal. Click View Contracts under the Recurring Billing menu and search for the contract you want to work with. Click the linked Contract ID and locate the Next Bill Date field. | |See also ManageContractAddDaysToNextBillDt for simplified processing where only NextBillDt will be updated. | BillingPeriod| This value is used in conjunction with the BillingInterval to compute the next bill date for a contract. | | Valid values are: | |- DAY | |- WEEK | |- MONTH | |- YEAR | |Note: The system will automatically account for 31 day months and/or leap years. For example: | | - Recurring billing is set to run once monthly | | - The contract start date is set for the 31st | | If the next month only has 30 days, recurring billing will automatically run the transaction on the 30th. | | Note: This parameter is case sensitive. | | Examples of billing cycles and how are shown in this table: | **Billing Cycle** | **BillingPeriod**| **BillingInterval** |Weekly |WEEK | 1 |Every Two Weeks |DAY | 14 |Every Four Weeks |DAY | 28 |Monthly |MONTH | 1 |Quarterly |YEAR | 4 |Twice Yearly |YEAR | 2 |Yearly |YEAR | 1 |BillingInterval | This value is used in conjunction with the BillingPeriod to compute the next bill date for a contract. | |Valid values are: | |- 1 | |- 2 | |- 4 | |- 14 | |- 21 | |- 28 |MaxFailures | The number of times the system will try to re-process a failed payment before the contract is placed in suspended state. Valid entries are integers 0-10. |Optional | If left blank, the default value is zero (0). A MaxFailure = 0 means that the system will not try to reprocess a failed payment. | | IMPORTANT: When a payment fails to process and the MaxFailures parameter is set to a value greater than zero (0), all future payments will be ignored until the failed payment is either successfully processed or the contract is suspended. |FailureInterval | Note: This parameter has been deprecated. |Optional | |EmailCustomer | Indicates whether the system will send an email to the customer after successfully processing a scheduled payment. |Optional | Valid values are: | | - TRUE – Email is sent to the customer after successful payment | | - FALSE – (default) Customer is not notified after successful payment | |Note: Email notifications can only be sent if a valid customer contact email has been provided in the customer record. |EmailMerchant | Indicates whether the system will send an email to the merchant after successfully processing a scheduled payment. |Optional |Valid values are: | |- TRUE – Email is sent to the merchant after successful payment | |- FALSE – (default) Merchant is not notified after successful payment |EmailCustomerFailure| Indicates whether the system will send an email to the customer after failing to process a scheduled payment. |Optional | Valid values are: | | - TRUE – Email is sent to the customer after failed payment | | - FALSE – (default) Customer is not notified after failed payment | |Note: mail notifications can only be sent if a valid customer contact email has been provided in the customer record. |EmailMerchantFailure | Indicates whether the system will send an email to the merchant after failing to process a scheduled payment. | |Valid values are: | |- TRUE – Email is sent to the merchant after failed payment | |- FALSE – (default) Merchant is not notified after failed payment | |Note: Email notifications can only be sent if a valid merchant contact email has been provided in the merchant record. | Status|Indicates whether the contract is currently active (reviewed each day for pending payments due) or inactive. |Optional |Valid values are: | |- ACTIVE – Contract is reviewed each day for pending payments | |- INACTIVE – Contract is not reviewed for pending payments | |- PENDING – Payment had failed to process | |- CLOSED – contract has been programmatically closed and is no longer used |ExtData | Reserved for future use. |Optional | # 5.5. MANAGECONTRACTADDDAYSTONEXTBILLDT This web service allows the integrator to update the NextBillDate in the event that a payment was declined and a contract suspended. See Developer’s Notes for information about [Recurring Billing Web Services.](#section/recur) ## Request ManageContractAddDaysToNextBillDt(Username, Password, Vendor, CustomerKey, ContractKey, NumOfDays, ExtData) ## Response Response here View [RecurringResult Response Fields.](#section/recurringresult-response-fields) ## ManageContractAddDaysToNextBillDt Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |Username | User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service. |Password | Password associated with the user name provided. |Vendor | Unique numeric value used to identify the merchant for the query. | |Note: Vendor key may also be called Merchant ID, Merchant Number, or RPNum. To locate your Vendor key on the virtual terminal, click Password under the Preferences menu. |CustomerKey | Unique identifier assigned to the customer record by the system at the time the customer record is created. | |Note: The CustomerKey value can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerKey appears in the Key column. |ContractKey | Unique identifier assigned to the contract by the system at the time the contract record is created. | |Note: The ContractKey value appears in the return results (see tags) when a new contract is added to the system. |NumOfDays | The number of days to be added to the NextBillDt field. This value must be a positive integer. |ExtData | Reserved for future use. |Optional | # 5.6. ADDRECURRINGCREDITCARD The AddRecurringCreditCard web service is a convenience function that allows an integrator to wrap the functionality of three separate calls into one. Rather than having to call ManageCustomer then ManageCreditCardInfo and finally ManageContract (while passing along various return values into subsequent calls) one can simply call AddRecurringCreditCard. ## Request AddRecurringCreditCard(Username, Password, Vendor, CustomerID, CustomerName, FirstName, LastName, Title, Department, Street1, Street2, Street3, City, StateID, Province, Zip, CountryID, Email, DayPhone, NightPhone, Fax, Mobile, ContractID, ContractName, BillAmt, TaxAmt, TotalAmt, StartDate, EndDate, BillingPeriod, BillingInterval, MaxFailures, FailureInterval, EmailCustomer, EmailMerchant, EmailCustomerFailure, EmailMerchantFailure, CcAccountNum, CcExpDate, CcNameOnCard, CcStreet, CcZip, ExtDat) ## Request Example ``` RecurringSoapClient recurring = new RecurringSoapClient("RecurringSoap"); recurringResult = recurring.AddRecurringCreditCard( "username", "password", "5","Stonebreaker2", "", "", "", "", "", "", "", "", "", "", "", "", "", "barney@rubble.com", "", "", "", "", "mycontract1", "Payment for stones", "234.11", "5.00", "239.11", "8/1/2016", "12/1/2016", "DAY", "1", "0", "", "TRUE", "FALSE", "TRUE", "FALSE", "4012888888881881", "1216", "Barney Rubble", "111 Bedrock Lane", "90210", ""); ``` ## Response AuthCode, CcInfoKey, CheckInfoKey, ContractKey, CustomerKey, ExtData, Message, PNRef, Partner, Result, Username, Vendor, code, error ``` AuthCode null string CcInfoKey "13582" string CheckInfoKey "" string ContractKey "9" string CustomerKey "27" string ExtData null string Message null string PNRef null string Partner "100" string Result null string Username "username" string Vendor "5" string code OK ResultCode error "OK" string ``` View [RecurringResult Response Fields.](#section/recurringresult-response-fields) ## AddRecurringCreditCard Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |Username | User name assigned in the payment server. The user must have the appropriate security permissions in order for the system to return transaction records. |Password | Password for the user name assigned in the payment server. |Vendor | Unique numeric value used to identify the merchant. |CustomerID |Uniques identifier assigned to the customer by the merchant at the time the customer record is created. |CustomerName | Individual or customer business name. |FirstName |Customer contact first name. |Optional | |LastName |Customer contact last name. |Optional | |Title | Customer contact job or professional title. For example, “Business Unit Manager,” or “Dr.” |Optional | |Department | Customer contact department. For example, “Sales,” or “Operations.” |Optional | |Street1 | Customer contact street address – line 1. |Optional | |Street2 |Customer contact street address – line 2. |Optional | |Street3 |Customer contact street address – line 3. |Optional | |City | Customer contact city. |Optional | |StateID | Customer contact’s standard U.S. postal service two-character state code (U.S. customers only). |Optional | |Province |Customer contact’s province (countries outside the U.S., only). |Optional | |Zip | Customer contact’s zip or postal code. |Optional | |CountryID | Customer contact’s three-character country code. For example, USA = United States or CAN = Canada. |Optional | |Email | Customer contact’s email address. |Optional | |DayPhone | Customer contact’s daytime phone number. |Optional | |NightPhone | Customer contact’s after-hours phone number. |Optional | |Fax |Customer contact’s fax number. |Optional | |Mobile |Customer contact’s mobile phone number. |Optional | |ContractID |Unique identifier assigned to the contract by the merchant at the time the contract record is created. |Optional | |ContractName |Name assigned to the contract (used for easier identification). |Optional | |BillAmt |Amount billed each time the contract comes due in DD.CCCC format. |Optional | |TaxAmt |Additional tax amount applied to the BillAmt each time the contract comes due in DD.CCCC format. |Optional | |TotalAmt | Total amount billed each time the contract comes due in DD.CCCC format. | |BillAmt + TaxAmt = TotalAmt |StartDate | Date that the contract becomes effective in MM/DD/YYYY format. The start date must be greater than today’s date. | |The Start Date represents the first time the customer will be billed per the contract. Future bill dates are calculated using the BillingPeriod and BillingInterval parameters. |EndDate | Date that the contract is completed in MM/DD/YYYY format. The end date must be greater than the start date. |BillingPeriod |This value is used in conjunction with the Billing Interval to compute the next bill date for a contract. | |Valid values are: | |- DAY | |- WEEK | |- MONTH | |- YEAR | |Note: The system will automatically account for 31 day months and/or leap years. For example: | | - Recurring billing is set to run once monthly | | - The contract start date is set for the 31st | |If the next month only has 30 days, recurring billing will automatically run the transaction on the 30th. | |Note: This parameter is case sensitive. | |Examples of billing cycles and how are shown in this table: |**Billing Cycle** |**BillingPeriod**|**BillingInterval** |Weekly |WEEK |1 |Every Two Weeks |DAY |14 |Every Four Weeks | DAY | 28 |Monthly | MONTH |1 |Quarterly |YEAR | 4 |Twice Yearly |YEAR |2 |Yearly |YEAR |1 | BillingInterval| This value is used in conjunction with the BillingPeriod to compute the next bill date for a contract. | |Value values are: | |-1 | |-2 | |-4 | |-14 | |-21 | |-28 |MaxFailures | The number of times the system will try to re-process a failed payment before the contract is placed in suspended state. Valid entries are integers 0-10. |Optional | If left blank, the default value is zero (0). A MaxFailure = 0 means that the system will not try to reporcess a failed payment. | |IMPORTANT: When a payment fails to process and the MaxFailures parameter is set to a value greater than zero (0), all future payments will be ignored until the failed payment is either successfull processed or the contract is suspended. |FailureInterval | Note: This parameter has been deprecated. |Optional | |EmailCustomer | Indicates whether the system will send an email to the customer after successfully processing a scheduled payment. |Optional | Valid values are: | |-TRUE – Email is sent to the customer after successful payment | |- FALSE – (default) Customer is not notified after successful payment | |Note: Email notification can only be sent if a valid customer contact email has been provided in the customer record. |EmailMerchant | Indicates whether the system will send an email to the merchant after successfully processing a scheduled payment. |Optional | Valid values are: | |-TRUE – Email is sent to the merchant after successful payment | |- FALSE – (default) Merchant is not notified after successful payment |EmailCustomerFailure | Indicates whether the system will send an email to the customer after failing to process a scheduled payment. |Optional | Valid values are: | |- TRUE – Email is sent to the customer after failed payment | |- FALSE – (default) Customer is not notified after failed payment | |Note: Email notification can only be sent if a valid customer contact email has been provided in the customer record. |EmailMerchantFailure | |Optional | Indicates whether the system will send an email to the merchant after failing to process a scheduled payment. | |Valid values are: | |- TRUE – Email is sent to the merchant after failed payment | |- FALSE – (default) Merchant is not notified after failed payment |CcAccountNum | Credit care number used to uniquely identify the card owner’s account. |Optional | |CcExpDate | Credit card date of expiration in MMYY format. |Optional | |CcNameOnCard | Card owner’s name as it appears on the card. |Optional | |CcStreet |Card owner’s billing address street name and number. |Optional | |CcZip |Card owner’s billing address postal/zip code. |Optional | |ExtData |Reserved for future use. |Optional | # 5.7. PROCESSCREDITCARD (RECURRING BILLING) This web service allows an integrator to process a Credit Card Transaction against a checking account that has been stored using ManageCreditCardInfo This web service is for processing ‘Sale’ transactions only. ## Request ProcessCreditCard(Username, Password, Vendor, CcInfoKey, Amount, InvNum, ExtData) Note: The CcInfoKey in the call below is obtained in the response to the [ManageCreditCardInfo](#section/recur) call ``` RecurringSoapClient recurring = new RecurringSoapClient("RecurringSoap"); recurringResult = recurring.ProcessCreditCard("username", "password", "5", CcInfoKey, "12.34", "888", ""); ``` ## Response ``` AuthCode null string CcInfoKey null string CheckInfoKey null string ContractKey null string CustomerKey null string ExtData "VISA 1881 1216" string Message "Duplicate transaction" string PNRef "13621" string Partner null string Result "110" string Username null string Vendor null string code OK ResultCode error "DECLINED" string ``` View [Transaction Response Fields.](#section/transaction-response-fields) ## ProcessCreditCard Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |Username | User name assigned in the payment server. The user must have an appropriate level of access in order to utilize the web service. |Password | Password associated with the user name provided. |Vendor | Unique numeric value used to identify the merchant for the query. The Vendor key is assigned by the gateway and acts as the primary key for the merchant table. | |Note: Vendor key may also be called Merchant ID, Merchant Number, or RPNum. To locate your Vendor key on the virtual terminal, click Password under the Preferences menu. |CcInfoKey | Numerical key value assigned to the payment method when it was added to the system. | |This value appears in the return result when a new payment method is added (see tags) or can be found in the result set from the InfoCustomer web service. |Amount |Total transaction amount in DDDD.CC format. |InvNum | The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice. | Optional| View [ExtData Field Definitions](#section/extdatadef) for more information. |ExtData | Reserved for future use. |Optional | # 5.8. PROCESSCHECK (RECURRING BILLING) This web service allows an integrator to process a Check Transaction against a checking account that has been stored using ManageCheckInfo. This web service is for processing ‘Sale’ transactions only. ## Request ProcessCheck(Username, Password, Vendor, CheckInfoKey, Amount, InvNum, ExtData) ## Response Response here View [Transaction Response Fields.](#section/transaction-response-fields) ## ProcessCheck Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |Username | User name assigned in the payment server. The user must have an appropriate level of access in order to utilize the web service. |Password | Password associated with the user name provided. |Vendor | Unique numeric value used to identify a specific gateway account. | |Note: Vendor key may also be called Merchant ID, Merchant Number, or RPNum. To locate your Vendor key on the virtual terminal, click Password under the Preferences menu. |CheckInfoKey | Numerical key value assigned to the payment method when it was added to the system. | |This value appears in the return result when a new payment method is added using ManageCheckInfo (see tags) or can be found in the result set from the InfoCustomer web service. |Amount |Total transaction amount in DDDD.CC format. |InvNum | The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice. | Optional| View [ExtData Field Definitions](#section/extdatadef) for more information. |ExtData | Reserved for future use. |Optional | # 5.9. RECURRINGRESULT RESPONSE FIELDS The following response fields may be part of the return value for web services using Recurring Billing operations. These web services include: - ManageCustomer - ManageCreditCardInfo - ManageCheckInfo - ManageContract - ManageContractAddDaysToNextBillDt - AddRecurringCreditCard | Response Field | Data Value |-----|----- |AuthCode | String |CcInfoKey | String |CheckInfoKey | String |code | Result Code object |ContractKey |String |CustomerKey | String |error | String |ExtData |Reserved for future use. |Message |String |Partner |String |PNRef |String |Result |String |Username |String |Vendor |String # 6. CARD SAFE # 6.1. STORECARD This service is used to add a stored payment method to an existing customer record. Calling this service is the first step towards succesfully storing and initiating recurring payments. See Developer’s Notes for information about [Card Safe Web Services.](#section/cardsafe) ## Request StoreCard(UserName, Password, TokenMode, CardNum, ExpDate, CustomerKey, NameOnCard, Street, Zip, ExtData) ## Response Response example View [StoreCardResult Response Fields.](#section/storecardresult-response-fields) ## StoreCard Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |Username | User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service. |Password | Password associated with the user name provided. |TokenMode |Indicates what type of token will be returned when calling the service. | | - DEFAULT – Returns a numeric CcInfoKey | | - CARDFORMAT – Returns a randomly generated number in the format of a credit card matching the card type of the actual card | | - JSTOKEN – Returns a 64 digit alphanumeric token that doesn’t have to be tied to a specific customer |CardNum | Credit card number used to uniquely identify the card owner’s account. | ExpDate| Credit card date of expiration in MMYY format. |CustomerKey | Unique identifier assigned to the customer record by the system at the time the customer record is created. | | Note: The CustomerKey value can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerKey appears in the Key column. This field is optional when using JSTOKEN mode |NameOnCard | Card owner’s name as it appears on the card. |Optional | |Street |Card owner’s billing address street name and number. |Optional | |Zip | Card owner’s billing address postal/zip code. |Optional | |ExtData | Reserved for future use. |Optional | # 6.2. STORECARDFROMPNREF This service is used to add a stored payment method to an existing customer record using a previous transaction as the basis. See Developer’s Notes for information about [Card Safe Web Services.](#section/cardsafe) ## Request StoreCardFromPNRef(UserName, Password, TokenMode, PnRef, CustomerKey, Street, Zip, ExtData) ``` safeResponse = safe.StoreCardFromPNRef("username", "password", "DEFAULT", "34586", "876565", "", "", ""); ``` ## Response Response example View [StoreCardResult Response Fields.](#section/storecardresult-response-fields) ## StoreCardFromPNRref Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |Username | User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service. |Password | Password associated with the user name provided. |TokenMode |Indicates what type of token will be returned when calling the service. | | - DEFAULT – Returns a numeric CcInfoKey | | - CARDFORMAT – Returns a randomly generated number in the format of a credit card matching the card type of the actual card |PnRef | Unique payment reference number used to identify a single transaction within the system. The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created. Provide the PNRef that was created by the original transaction that you want to convert to a CardSafe entry |CustomerKey | Unique identifier assigned to the customer record by the system at the time the customer record is created. | | Note: The CustomerKey value can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerKey appears in the Key column. |Street |Card owner’s billing address street name and number. |Optional | |Zip | Card owner’s billing address postal/zip code. |Optional | |ExtData | Reserved for future use. |Optional | # 6.3. PROCESSCREDITCARD This web service allows an integrator to process a Credit Card Transaction against an account that has been stored using AddCard See Developer’s Notes for information about [Card Safe Web Services.](#section/cardsafe) ## Request ProcessCreditCard(UserName, Password, TransType, CardToken, TokenMode, Amount, InvNum, PNRef, ExtData) ## Response Response example View [StoreCardResult Response Fields.](#section/storecardresult-response-fields) ## ProcessCreditCard Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |Username | User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service. |Password | Password associated with the user name provided. |TransType |Identifies the type of credit card transaction being made. | | Valid values are: | | - Sale – make a purchase using a credit card | | - Auth – authorize the amount on a credit card | | - Return – credits the card holder’s account | | - Void – undo an unsettled transaction | | - Force – force an Auth transaction in to the current batch (PostAuth) or place a transaction not processed through the payment server into the current batch (ForceAuth). | | Note: When using this transaction type for a ForceAuth, you must include an AuthCode under the ExtData parameter. | | - RepeatSale – perform a recurring billing or installment payment transaction. | | Processors supporting the restaurant adjustment function only: | | - Adjustment – used to modify an existing tip amount for an original sale To call the service. |CardToken | Numerical key value assigned to the payment method when it was added to the system. | TokenMode| The type of token that is being used for the transaction. | | - DEFAULT – Returns a numeric CcInfoKey | | - CARDFORMAT – Returns a randomly generated number in the format of a credit card matching the card type of the actual card | | - JSTOKEN – Randomly generated string of characters returned when JavaScript Tokenization is requested. |Amount | Total transaction amount in DDDD.CC format. |InvNum Optional | The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice. | PNRef| Unique payment reference number used to identify a single transaction within the system. The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created. |Required when TransType=Return, Void, Force, RepeatSale, and Adjustment| |ExtData | Reserved for future use. |Optional | # 6.4. STORECARDRESULT RESPONSE FIELDS The following response fields may be part of the return value for web services using Card Save operations. These web services include: - StoreCard - ProcessCreditCard | Response Field | Data Value |-----|----- |AuthorizedAmount | String |Balance | String |Result | String |RespMSG | String |Message |String |Message1 | String |Message2 | String |AuthCode | String |PNRef |String |HostCode |String |HostURL |String |ReceiptURL |String |GetAVSResult |String |GetAVSResultTXT |String |GetStreetMatchTXT |String |GetZipMatchTxt |String |GetCVResult |String |GetCVResultTXT |String |GetGetOrigResult |String |GetCommercialCard |String |WorkingKey |String |KeyPointer |String |ExtData |String # 7. BATCH REPORTING # 7.1. GETBATCHDETAIL This web service retrieves details about the batch based on a batch number. ## Request GetBatchDetail(UserName, Password, BatchNumber, SettleDate, PaymentType, ExtData) ## Request Example ``` var svc = new BatchInfoService.BatchInfoSoapClient("BatchInfoSoap"); var result = svc.GetBatchDetail("username", "password", "0", "4/24/2017", "Credit", ""); ``` ## Response Response example ``` 0 Batch Detail Retrieved 15276 ``` ## View [GetBatch Response Fields.](#section/GetBatch-Response-Fields) ## GetBatchDetail Input Fields Unless noted otherwise, the parameter is required. | Parameter Name| Description |-----|----- |UserName (string) | User name assigned in the payment server. The user must have appropirate security permissions in order for the system to return transaction records. |Password (string) | Password for the user name assigned in the payment server. |BatchNumber (string) | Current batch number for transactions, settlement, and batch inquiries. |SettleDate (string) | The date of settlement. |PaymentType (string) | The payment type identifies the payment venue. If one or more payment types are provided, only transactions with matching PaymentType will be included in the results; all other Payment Type values will be excluded. | | Valid entries are: | | - ‘ACH’ – Automated Clearing House | | - ‘ECHECK’ – Electronic check | | - ‘GUARANTEE’ – Guarantee check | | - ‘PAYRECEIPT’ – receipt images uploaded to the server | | - ‘SETTLE’ – transactions that have been finalized with the payment host | | - ‘VERIFY’ – Pre-authorized checks | |Note: The default value for this field is “ALL”. If no value is set, all payment types will be returned in the result set. | |Or any permutation of the above values, e.g. “’ACH’,’ECHECK’” will pull all transactions with either ACH or ECHECK payment types. |ExtData (string, optional) | The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. | |Extended data in XML format. Valid values are: | |- Timezone – Used to convert the input and output (where applicable) date/time values to the desired timezone. When specified, the same timezone is used to convert the begin/end date parameters as well as the Date and Last Update output values. This field is optional, and if omitted all date/time values are treated as UTC. Daylight savings time adjustments, where applicable, are handled automatically. Accepted values are: | |- AKST – Alaskan Standard Time | |- CST – Central Standard Time | |- EST – Eastern Standard Time | |- HST – Hawaiian Standard Time | |- MST – Mountain Standard Time | |- AZMST – Arizona | |- PST – Pacific Standard Time # 7.2. GETBATCHNUMBERS This web service retrieves all the batch numbers between start and end dates based on a payment type. ## Request GetBatchNumbers(UserName, Password, StartDate, EndDate, PaymentType, ExtData) ## Request Example ``` var svc = new BatchInfoService.BatchInfoSoapClient("BatchInfoSoap"); var result = svc.GetBatchNumbers("username", "password", "4/24/2015", "5/1/2017","Credit", ""); ``` ## Response Response example ``` 0 Batch Numbers Retrieved 0 ``` ## View [GetBatch Response Fields.](#section/GetBatch-Response-Fields) ## GetBatchNumbers Input Fields Unless noted otherwise, the parameter is required. | Parameter Name| Description |-----|----- |UserName (string) | User name assigned in the payment server. The user must have appropirate security permissions in order for the system to return transaction records. |Password (string) | Password for the user name assigned in the payment server. |EndDate (string) | Last date to end the search. |PaymentType (string) | The payment type identifies the payment venue. If one or more payment types are provided, only transactions with matching PaymentType will be included in the results; all other Payment Type values will be excluded. | | Valid entries are: | | - ‘ACH’ – Automated Clearing House | | - ‘ECHECK’ – Electronic check | | - ‘GUARANTEE’ – Guarantee check | | - ‘PAYRECEIPT’ – receipt images uploaded to the server | | - ‘SETTLE’ – transactions that have been finalized with the payment host | | - ‘VERIFY’ – Pre-authorized checks | |Note: The default value for this field is “ALL”. If no value is set, all payment types will be returned in the result set. | |Or any permutation of the above values, e.g. “’ACH’,’ECHECK’” will pull all transactions with either ACH or ECHECK payment types. |ExtData (string, optional) | The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. | |Extended data in XML format. Valid values are: | |- Timezone – Used to convert the input and output (where applicable) date/time values to the desired timezone. When specified, the same timezone is used to convert the begin/end date parameters as well as the Date and Last Update output values. This field is optional, and if omitted all date/time values are treated as UTC. Daylight savings time adjustments, where applicable, are handled automatically. Accepted values are: | |- AKST – Alaskan Standard Time | |- CST – Central Standard Time | |- EST – Eastern Standard Time | |- HST – Hawaiian Standard Time | |- MST – Mountain Standard Time | |- AZMST – Arizona | |- PST – Pacific Standard Time # 7.3. GETBATCHSTATUS The web service retrieves the status of a batch based on a batch number and payment type. ## Request GetBatchStatus(UserName, Password, BatchNumber, SettleDate, PaymentType, ExtData) ## Request Example ``` var svc = new BatchInfoService.BatchInfoSoapClient("BatchInfoSoap"); var result = svc.GetBatchStatus("username", "password", "0", "4/24/2017", "Credit", ""); ``` ## Response ## Response example ``` 0 Batch Status Retrieved Settled DEMO851 ``` ## View [GetBatch Response Fields.](#section/GetBatch-Response-Fields) ## GetBatchStatus Input Fields Unless noted otherwise, the parameter is required. | Parameter Name| Description |-----|----- |UserName (string) | User name assigned in the payment server. The user must have appropirate security permissions in order for the system to return transaction records. |Password (string) | Password for the user name assigned in the payment server. |BatchNumber (string) | Current batch number for transactions, settlement, and batch inquiries. |SettleDate (string) |The date of settlement. |PaymentType (string) | The payment type identifies the payment venue. If one or more payment types are provided, only transactions with matching PaymentType will be included in the results; all other Payment Type values will be excluded. | | Valid entries are: | | - ‘ACH’ – Automated Clearing House | | - ‘ECHECK’ – Electronic check | | - ‘GUARANTEE’ – Guarantee check | | - ‘PAYRECEIPT’ – receipt images uploaded to the server | | - ‘SETTLE’ – transactions that have been finalized with the payment host | | - ‘VERIFY’ – Pre-authorized checks | |Note: The default value for this field is “ALL”. If no value is set, all payment types will be returned in the result set. | |Or any permutation of the above values, e.g. “’ACH’,’ECHECK’” will pull all transactions with either ACH or ECHECK payment types. |ExtData (string, optional) | The ExtData parameter allows you to pass additional information to the web service that is not covered under the input parameters. ExtData values need not be placed in any particular order; however, they must be properly formatted using XML tags. | |Extended data in XML format. Valid values are: | |- Timezone – Used to convert the input and output (where applicable) date/time values to the desired timezone. When specified, the same timezone is used to convert the begin/end date parameters as well as the Date and Last Update output values. This field is optional, and if omitted all date/time values are treated as UTC. Daylight savings time adjustments, where applicable, are handled automatically. Accepted values are: | |- AKST – Alaskan Standard Time | |- CST – Central Standard Time | |- EST – Eastern Standard Time | |- HST – Hawaiian Standard Time | |- MST – Mountain Standard Time | |- AZMST – Arizona | |- PST – Pacific Standard Time # 7.4. GETBATCH RESPONSE FIELDS The following response fields may be part of the return value for web services using Get Batch operations. These web services include: - GetBatchDetail - GetBatchNumbers - GetBatchStatus ## GetBatch Response Fields | Parameter Name| Description |-----|----- |AuthorizedAmount (string) | |Balance (string) | |Result integer | |RespMSG (string) | |Message (string)| |Message1 (string) | |Message2 (string)| |AuthCode (string)| |PNRef (string) | |HostCode (string) | |HostURL (string) | |ReceiptURL (string) | |GetAVSResult (string) | |GetAVSResultTXT (string)| |GetStreetMatchTXT (string)| |GetZipMatchTxt (string) | |GetCVResult (string) | |GetCVResultTXT (string) | |GetGetOrigResult (string) | |GetCommercialCard (string) | |WorkingKey (string)| |KeyPointer (string)| |ExtData (string) | # 8. CUSTOM FIELDS # 8.1. ADDCUSTOMFIELD This web service allows an integrator to add custom fields programmatically to a gateway account. The data in these fields is not passed to the processor. See Developer’s Notes for information about [Adding Custom Fields.](#section/addcus) ## Request AddCustomField(UserName, Password, RPNum, FieldName, IsNumeric, DecimalPlaces, MaxLength, RegEx, IsRequired, Description, MinValue, MaxValue, DisplayOnReceipt) ## Request Example ``` CustomFieldsSoapClient custom = new CustomFieldsSoapClient("CustomFieldsSoap"); customResponse = custom.AddCustomField("username", "password", "5", "CocoaPebbles", false, "", "10", "", false, "Barney's treat", "", "", true, "All out"); ``` ## Response Response example ``` RespMSG "Field added successfully." string Result 0 int ``` ## View [ AddCustomField Response Fields.](#section/addcustomfield-response-fields) ## AddCustomField Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |UserName | User name assigned in the payment server. The user must have the appropriate security permissions in order for the system to return transaction records. |Password | Password for the user name assigned in the payment server. |RPNum | Unique value assigned to each gateway account used as a third credential to ensure security. | |Note: RPNum may also be called Merchant ID, Merchant Number, or Vendor Key. |FieldName | The name of the field. This value must be unique and will be used to programmatically access the field when passing additional data using the ProcessCreditCard web service. |IsNumeric Optional |This is a boolean parameter. It is only necessary to pass in a value if the integrator wishes to allow only numeric data to be passed as input values. |DecimalPlaces | Integer value indicating the number of decimal places the integrator wishes this field to contain. For accurate storage of the value “2.79” the integrator would want to pass in a value of ‘2’. For accurate storage of the value “2.99999” the integrator would want to pass in a value of ‘5’. |Optional | Leave this field ‘Null’ if not keeping track of numeric values |MaxLength Optional| Maximum string length allowed in the field being added. Default value is ‘25’. |RegEx Optional| Enter any regular expressions needed to validate that the values being submitted to this field conform to a specific data type and/or format. |Description | This is the human readable description that will display in the virtual terminal and on the cardholder receipt. |MinValue | Minimum numeric value |Optional | |MaxValue | Maximum numeric value |Optional | |DisplayOnReceipt | This is a boolean parameter. Indicates whether or not the field will display on the cardholder receipt. |Optional | # 8.2. GETCUSTOMFIELDS The GetCustomFields web service allows an integrator to retrieve the custom fields that have been programmatically added to a gateway account. The response contains an XML definition of the field, type, etc. ## Request ``` CustomFieldsSoapClient custom = new CustomFieldsSoapClient("CustomFieldsSoap"); customResponse = custom.GetCustomFields("username", "password", "5"); ``` ## Response The response to this call is contained as an XML string within the ExtData field. Response example ``` 2 FruityPebbles 5 true 0 25 false 1 The number of Fruity Pebbles Bad Fruity Pebbles. 0 42 1 true false false false 3 CocoPebbles 5 false 0 10 false 1 Barney's treat All out 0 0 2 true " ``` ## View [ AddCustomField Response Fields.](#section/addcustomfield-response-fields) ## GetCustomFields Input Parameters Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- |UserName| User name assigned in the payment server. The user must have the appropriate security permissions in order for the system to return transaction records. |Password| Password for the user name assigned in the payment server. |RPNum| Unique value assigned to each gateway account used as a third credential to ensure security. ||Note: RPNum may also be called Merchant ID, Merchant Number, or Vendor Key. # 8.3. AddCustomField Response Fields The following response fields may be part of the return value for web services using Add Custom Field operations. These web services include: - AddCustomField - GetCustomFields |Response Field | Data Value |-----|----- |Result | Integer |RespMSG | String |Message | String |Message1 | String |Message2 | String |AuthCode | String |PNRef | String |HostCode | String |HostURL | String |ReceiptURL | String |GetAVSResults | String |GetAVSResultsTXT | String |GetStreetMatchTXT | String |GetZipMatchTXT | String |GetCVResult | String |GetGetOrigResult | String |GetCommercialCard | String |WorkingKey | String |KeyPointer | String |ExtData | String # 9. Developer Notes ## Invalid Character Processing Some parameters and XML tags contain data that will automatically remove invalid characters from the user-entered data. These parameters and tags include: - MagData - NameOnCard - DL - SS - DOB - InvNum - Zip - Street - StateCode - RegisterNum - ExtData: - Extdata: - ExtData: - ExtData: - ExtData: - ExtDate: - ExtData: - ExtData: - ExtData: - ExtData: - ExtData: - ExtData: ## Reversal Transactions ## Credit Card Reversals Reversal is supported for Visa and MasterCard transactions made within the direct marketing and ecommerce industries. Reversals must be processed within 24 hours of the original credit card transaction. ## Debit Card Reversals All reversals must be processed as card-present transactions. Reversal is supported for supported issuers for all debit card issuers. The supported industries are only retail and restaurant. Reversals must be processed within 2 hours of the original debit card transaction. TIP: Requires the debit card number and expiration date along with the original sale PNREF number to process reversals. ## PIN-less Debit Transactions In some cases, debit transactions can be processed without the customer’s entering a PIN number (a “PIN-less” debit transaction). Essentially, the same information is sent as in a typical PIN-based debit transaction, with the exception of the encrypted PIN-block and key serial number. This transaction type is currently only available with BuyPass and Global Payments processors. If the designated processor is BuyPass or Global, the transaction will be accepted either with both the PIN-block and key serial number (interpreted as a PIN-based debit transaction) or accepted with neither piece of data (interpreted as a PIN-less debit transaction). If the above requirements are met for a transaction, PIN-less debit transactions will be allowed through the Payment Server. However, when working with BuyPass, additional setup is required to ensure that the transaction is accepted by the processor: - **Application ID Setup** – To process PIN-less debit through BuyPass, the application ID sent must identify the application in use. Contact your administrator for additional details. ## Register Number and Terminal ID Setup When processing transactions with BuyPass, the Payment Server will attempt to match the RegisterNum passed from the client-side with the register number set up in the merchant account. Once it has made the match, it will send the corresponding terminal ID assigned to that register number to BuyPass. When no terminal ID is sent to BuyPass, the default value is sent (usually terminal ID “01”). If you are also doing VRU (phone-originated) transactions, a separate terminal ID must be set up in the registers on the merchant account and submitted in your request through the web service. If the merchant will be doing both internet and VRU transactions at the same time, the terminal ID value will be required to differentiate between the two. For example, you may set up “01” for Internet and “02” for VRU. The request sent through the ProcessDebitCard operation must then send the appropriate register number to reflect the appropriate transaction type. ## Fuel Purchases: Debit Card Use Debit card processing for fuel purchases is now available through BuyPass only. This functionality allows for fuel purchases with standard debit cards (Visa, MasterCard, etc.). Debit fuel purchases (TransTypes Sale and Force) require item-level purchase information. If all the required information for a certain purchase is not provided, the transaction will be rejected and an error message generated. The main implication for the developer is that additional data must be passed to the gateway in order for fuel purchases to process correctly. Item-level debit fuel purchase information is passed inside the tag in ExtData. Fuel purchases are differentiated at the gateway from other purchases by the Fuel designation placed within the tag in item. In effect, a transaction will only be treated as a fuel transaction if at least one of the items within is designated as category Fuel. ## Date Formats Dates entered through input parameters are automatically formatted to YYYY-MM-DDThh:mm:ss (time is in 24-hour format using Coordinated Universal Time (UTC). Valid entry formats are: - MM/DD/YYYY - YYYY-MM-DD - YYYY-MM-DDThh:mm:ss ## Date Query String The query string used to obtain transactions in a date range is constructed as follows: (Date DT >=BeginDt) AND (Date DT Sample String Data 8675309 All data passed through the custom fields parameters will be returned in the GetCardTrx web service call following the same format. In order for the data to be passed in correctly, the FieldName must reflect EXACTLY the field name of the custom field as it was added via the AddCustomField web service (see the Reporting Web Services portion of the API for additional information) or the Custom Fields menu in the virtual terminal. The < /CustomFields> tag must be passed in the ExtData field of the web service you are consuming. The tag must contain no spaces, and must conform to XML standards. Adding a custom field creates a new column in the Transaction Reports grid and any data passed into this field by an integrator or in the virtual terminal will be stored in that column and accessible through the GetCardTrx web service. # 9.1. Implementation Examples The following examples (cURL, PHP, Node.js, and Ruby) can be used when you are not using a SOAP based, .NET service. The examples show similar ways of doing the same thing in each environment. Note that we also have a postman collection that can quickly bring you up to speed for basic transaction processing using our easy HTTP GET/POST wrapper for our SOAP API as well as REST APIs. Once you open the link below look for the “IBX Beginner Collection”. [![Run in Postman](https://run.pstmn.io/button.svg)](https://www.getpostman.com/run-collection/dd06f5a44925cb0e1b3a) ## CURL How to execute the call: ``` curl "https://sandbox.ibxpays.com/paygate/ws/trxdetail.asmx/GetCardTrxSummary?UserName=username&Password=password&RPNum=5&BeginDt=7/11/2016&EndDt=7/11/2016&ApprovalCode=&Register=2&NameOnCard=&CardNum=&CardType=&ExcludeVoid=true&User=&invoiceId=&SettleFlag=&SettleMsg=&SettleDt=&TransformType=&Xsl=&ColDelim=&RowDelim=&IncludeHeader=true&ExtData=" | sed -e "s/>/>/g" | sed -e "s/</ VISA 0.0000 0.0000 0.0000 0.0000 0.0000 11564.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0 0 0 0 0 3 0 0 0 0 0 3 ``` ## PHP PHP w/SOAP: ``` __setLocation("https://sandbox.ibxpays.com/vt/ws/trxdetail.asmx"); $params = array( 'UserName' => "username", 'Password' => "password", 'RPNum' => "5", 'BeginDt' => "7/11/2016", 'EndDt' => "7/11/2016", 'ApprovalCode' => "", 'Register' => "", 'NameOnCard' => "", 'CardNum' => "", 'CardType' => "", 'ExcludeVoid' => "true", 'User' => "", 'SettleFlag' => "", 'SettleMsg' => "", 'SettleDt' => "", 'TransformType' => "", 'Xsl' => "", 'ColDelim' => "", 'RowDelim' => "", 'IncludeHeader' => "true", 'ExtData' => "" ); $response = $client->GetCardTrxSummary($params); $xml = new SimpleXmlElement($response->GetCardTrxSummaryResult); print("Count: "); // Have to cast to get underlying element as a object you want print_r((int)$xml->PaymentMethod->Cnt); print ("\n"); // How to iterate through them all // See: http://php.net/manual/en/class.simplexmlelement.php for more foreach ($xml->PaymentMethod->children() as $node) { print ("node=".$node->getName()); // get the name of this element print (" value=".$node); // get the value of this element // $arr = $node->attributes(); // returns an array if we needed attrbutes // print ("attribute=".$arr["ID"]); // get the value of this attribute print ("\n"); } //echo $xml->asXML(); ?> ``` PHP w/cURL: ``` PaymentMethod->Cnt); print ("\n"); // How to iterate through them all // See: http://php.net/manual/en/class.simplexmlelement.php for more foreach ($xml->PaymentMethod->children() as $node) { print("node=".$node->getName()); // get the name of this element print(" value=".$node); // get the value of this element // $arr = $node->attributes(); // returns an array if we needed attrbutes // print ("attribute=".$arr["ID"]); // get the value of this attribute print("\n"); } } else { print("Error: " . curl_error($handle)); print ("\n"); } curl_close($handle); ?> ``` How to execute the code: ``` php ibx-example.php ``` Sample Results: ``` Count: 3 node=Payment_Type_ID value=VISA node=Authorization value=0.0000 node=Capture value=0.0000 node=ForceCapture value=0.0000 node=PostAuth value=0.0000 node=Return value=0.0000 node=Sale value=11564.0000 node=Receipt value=0.0000 node=RepeatSale value=0.0000 node=Activate value=0.0000 node=Deactivate value=0.0000 node=Reload value=0.0000 node=Authorization_Cnt value=0 node=Capture_Cnt value=0 node=ForceCapture_Cnt value=0 node=PostAuth_Cnt value=0 node=Return_Cnt value=0 node=Sale_Cnt value=3 node=Receipt_Cnt value=0 node=RepeatSale_Cnt value=0 node=Activate_Cnt value=0 node=Deactivate_Cnt value=0 node=Reload_Cnt value=0 node=Cnt value=3 ``` ## Node.js You can [try our npm package.](https://www.npmjs.com/package/payroc_ibx) It supports a basic subset of transactions and can be easily modified for additional transactions. Note that if you use RunKit to run the examples it is required to remove the “use strict” command from the example as RunKit doesn’t currently support that. Node.js w/SOAP: ``` var soap = require('soap'); var parseString = require('xml2js').parseString; var url = 'https://sandbox.ibxpays.com/vt/ws/trxdetail.asmx'; var wsdlurl = url + '?wsdl'; var soap_client_options = {}; var CardTrxSummaryParameters = { 'UserName': "username", 'Password': "password", 'RPNum': "5", 'BeginDt': "7/11/2016", 'EndDt': "7/11/2016", 'ApprovalCode': "", 'Register': "", 'NameOnCard': "", 'CardNum': "", 'CardType': "", 'ExcludeVoid': "true", 'User': "", 'SettleFlag': "", 'SettleMsg': "", 'SettleDt': "", 'TransformType': "", 'Xsl': "", 'ColDelim': "", 'RowDelim': "", 'IncludeHeader': "true", 'ExtData': "" } // Give the createClient Method the WSDL as the first argument soap.createClient(wsdlurl, soap_client_options, function(err, client){ // We use SSL accelerator so make sure the right url is set manually if you find you're hitting non-secure site which isn't listening // client.setEndpoint(url); // The Client now has all the methods of the WSDL. Use it to get cardtrxsummary feeding it the JSON Payload client.GetCardTrxSummary(CardTrxSummaryParameters, function(err, result, body) { console.log('Result:'); console.log(result); console.log('\n'); parseString(result.GetCardTrxSummaryResult, function(err, result){ console.log('ParsedResult:'); console.log(result); console.log('\n'); console.log('Count is:'); console.log(result.CardTrxSummary.PaymentMethod[0].Cnt[0]); console.log('\n'); }); }); }); ``` How to execute the code: ``` node ibx-example.js ``` Sample Results: ``` { GetCardTrxSummaryResult: '\r\n \r\n VISA \r\n 0.0000\r\n 0.0000\r\n 0.0000\r\n 0.0000\r\n 0.0000\r\n 11564.0000\r\n 0.0000\r\n 0.0000\r\n 0.0000\r\n 0.0000\r\n 0.0000\r\n 0\r\n 0\r\n 0\r\n 0\r\n 0\r\n 3\r\n 0\r\n 0\r\n 0\r\n 0\r\n 0\r\n 3\r\n \r\n' } ParsedResult: { CardTrxSummary: { PaymentMethod: [ [Object] ] } } Count is: 3 ``` ## Ruby Ruby w/SOAP: How to execute the code: ``` ruby ibx-example.rb ``` Sample Results: ``` "[:get_open_batch_summary, :get_card_trx, :get_card_trx_summary, :get_check_trx]" #(Element:0x2ad888d14724 { name = "CardTrxSummary", children = [ #(Text "\n "), #(Element:0x2ad888d13bd0 { name = "PaymentMethod", children = [ #(Text "\n "), #(Element:0x2ad888d12f8c { name = "Payment_Type_ID", children = [ #(Text "VISA ")] }), #(Text "\n "), #(Element:0x2ad888d1217c { name = "Authorization", children = [ #(Text "0.0000")] }), #(Text "\n "), #(Element:0x2ad888d0d370 { name = "Capture", children = [ #(Text "0.0000")] }), #(Text "\n "), #(Element:0x2ad888d0c650 { name = "ForceCapture", children = [ #(Text "0.0000")] }), #(Text "\n "), #(Element:0x2ad888d07984 { name = "PostAuth", children = [ #(Text "0.0000")] }), #(Text "\n "), #(Element:0x2ad888d06890 { name = "Return", children = [ #(Text "0.0000")] }), #(Text "\n "), #(Element:0x2ad888cfb8dc { name = "Sale", children = [ #(Text "11564.0000")] }), #(Text "\n "), #(Element:0x2ad888cfa25c { name = "Receipt", children = [ #(Text "0.0000")] }), #(Text "\n "), #(Element:0x2ad888cf9528 { name = "RepeatSale", children = [ #(Text "0.0000")] }), #(Text "\n "), #(Element:0x2ad888cf87e0 { name = "Activate", children = [ #(Text "0.0000")] }), #(Text "\n "), #(Element:0x2ad888cf7a48 { name = "Deactivate", children = [ #(Text "0.0000")] }), #(Text "\n "), #(Element:0x2ad888cf6c9c { name = "Reload", children = [ #(Text "0.0000")] }), #(Text "\n "), #(Element:0x2ad888cf7994 { name = "Authorization_Cnt", children = [ #(Text "0")] }), #(Text "\n "), #(Element:0x2ad888b3e5bc { name = "Capture_Cnt", children = [ #(Text "0")] }), #(Text "\n "), #(Element:0x2ad888b2b78c { name = "ForceCapture_Cnt", children = [ #(Text "0")] }), #(Text "\n "), #(Element:0x2ad888b2781c { name = "PostAuth_Cnt", children = [ #(Text "0")] }), #(Text "\n "), #(Element:0x2ad888b26750 { name = "Return_Cnt", children = [ #(Text "0")] }), #(Text "\n "), #(Element:0x2ad888b25620 { name = "Sale_Cnt", children = [ #(Text "3")] }), #(Text "\n "), #(Element:0x2ad888b246a8 { name = "Receipt_Cnt", children = [ #(Text "0")] }), #(Text "\n "), #(Element:0x2ad888b237f8 { name = "RepeatSale_Cnt", children = [ #(Text "0")] }), #(Text "\n "), #(Element:0x2ad888b2295c { name = "Activate_Cnt", children = [ #(Text "0")] }), #(Text "\n "), #(Element:0x2ad888b1f324 { name = "Deactivate_Cnt", children = [ #(Text "0")] }), #(Text "\n "), #(Element:0x2ad888b1e410 { name = "Reload_Cnt", children = [ #(Text "0")] }), #(Text "\n "), #(Element:0x2ad888b18f24 { name = "Cnt", children = [ #(Text "3")] }), #(Text "\n ")] }), #(Text "\n")] }) "3" ``` ## Installation for Examples These are the basic steps you will need to install and run the examples on an Ubuntu 16.04 base install. ## For cURL: The curl is already installed by default. Curl command has two piped commands at the end that turn the XML into a non-escaped more readable format. (this bit: | sed -e “s/>/>/g” | sed -e “s/</ Security. In the example below, you can see the Merchant Token is provided at the top of the Security Settings page. (In the example, the token has been blurred out for security purposes.) ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/merchant-token.png) ## Simple and Advanced Modes The JTL can operate in two modes. The Simple mode, which should be usable by the vast majority of developers, allows for one merchant token to be passed and a single payment token to be returned. The Advanced mode provides the ability to get back multiple payment tokens for different merchants with a single capture of credit card or check information. In Advanced mode, there is also the ability to force the value of the charge on the server to match the value of the data being sent for single use tokens. Note that the Advanced mode requires some additional JavaScript coding while the simple mode requires just a single JS call to the JTL. In Advanced mode you can call IBX.setMerchantToken and IBX.setAmount which takes as parameters either a single value or an array of values for each element. This allows for charging two different merchants on the back end with only a single capture of credit card information (for example, when you have a merchant that handles insurance or shipping but you also have the original charge for merchandise). The array is ordered and the returned paymentTokens (a different token per merchant) will be returned in the order of the merchantTokens supplied. Similarly the amounts, if enforced, will be in order of merchantToken as well. ## Design a UI Form Below is an example of a simple form designed to collect payment and customer information. You can design a form customized for your purpose. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/custom-screen.png) ## Create a Form With a design for your form in mind, you can create the form by entering the input elements. Below is example code for the first four fields (refer to the design example above). Note that the form elements must **not** have a “name” attribute – this is what prevents the data from being submitted back to your server. This is **very** important. **Failure to follow the guideline will put your software into PCI scope** as the fields will be returned to your server. Note that form elements do have a data-ibx attribute with values that denote what that attribute is. This allows the JTL to identify which form element contains what card information. ```
``` ## JTL Form Parameters The following is the list of parameters that can be used for the form input elements and passed via the data-ibx attribute. Note that these input elements can be of type hidden as well as in the example code below. ``` ``` You can also use the JSToken for recurring payments. You simply need to set the hidden value to false as in the example code below. ``` ``` ### Credit Card Parameters | Attribute Name| Description |-----|----- | cardNumber| The number on the card. |nameOnCard | The name on the card. |expirationDate |The expiration date on the card in MMYY, MM/YY, MM/YYYY format. |cvv | The card verification value. This is typically a three or four digit number on the back of the card. |street | The street address for the card owner (required for validateCard). |zipcode | The zipcode for the card owner (required for validateCard). |amount | The amount the token will be charged (enforced if the merchant level setting to enforce token amounts is true). |merchantToken |The publicly shareable merchant token that is used as input to the API to determine which merchant to associate this token with. |validateCard | Requests both address verification, cvv check, and an auth be attempted against the card to validate it. ### Check Parameters | Attribute Name| Description |-----|----- |checkNumber|Uniquely identifies an individual’s check. |nameOnCheck|Check owner’s name as it appears on the check. |routingNumber|Uniquely identifies the bank holding funds. This is also referred to as transit number. |accountNumber|Uniquely identifies the check owner’s bank account. |driversLicenseNumber|Check owner’s driver’s license number. |driversLicenseState|Check owner’s standard U.S. postal service two-character state code or other standard province code. |ssn|Check owner’s Social Security number. |checkType|Identifies the type of check. | |Valid values are: | |PERSONAL - Check is made from an individual (personal) checking account | |CORPORATE - Check is made from a business checking account | |GOVERNMENT - Check is made from a government checking account |amount|The amount the token will be charged (enforced if the merchant level setting to enforce token amounts is true). |merchantToken|The publicly shareable merchant token that is used as input to the API to determine which merchant to associate this token with. ## Add JavaScript Library Code to Form After you design and create your form, you insert the JavaScript library reference to the of your HTML page. ``` ``` This creates an object called IBX that you can reference in your page to create the token and for advanced usage set the merchant tokens and amounts to be used (see below for advanced usage) ## Submit a Form When the form is submitted, a call is made to create a token. The form is scanned for those data-ibx attributes and a callback for when the data returns. After the token is created, the results are posted back to the form. The form can be any type of page that you want to create using any technology. The example we provide to signed developers uses php but you could just as easily choose any other web technology such as aspx, node, ruby, etc. When presenting the user with the ability to submit the created form, you first want to call the IBX.createToken method. Typically, you will want to prevent form submission, call createToken, and then handle the response in a callback writing the token values to your form, and finally submitting that form. For example, a jQuery example might look like the following code (ignoring any error handling and user safeguards like preventing double clicks on submission). ``` function() { var $form = $('#payment') $form.submit(function(event) { IBX.createToken($form, ISVIBXResponseHandler); event.preventDefault(); }); }); ``` Here we use jQuery to find our payment form and create an event handler that calls createToken via the JTL globally created IBX object and prevent the form from actually being submitted. We pass in the jQuery form (or this can be the default JavaScript DOM form object) and a callback for when the createToken call completes. The following is a sample of a response that is returned from a call to createToken, the callback takes a single response argument where the response object has the following format. ``` 
{
     form: Object,
     result: true,
     error: Object,
     token: "WhatAnAwesomeToken",
     tokens: ["WhatAnAwesomeToken"],
     cardData: {
         cardBrand: "VISA",
         nameOnCard: "Freddie Flintstone",
         expirationDate: "1218",
         lastFour: "4242",
         cardType: "Credit"
         cardCategory: "Gold"
     },
     validationData: {
         avsResponse: "U - Address Match Unavailable",
         cvvResponse: "M - Match",
         authMessage: "",
         authReturnCode: 0
         }
     }
``` ## CreateTokenResponse Parameters | Parameter Name| Description |-----|----- |form (object)| The JavaScript form DOM object passed to createToken. |token (string) |Unique payment token generated to represent the payment information. |tokens (string, array) |In advanced mode this contains the array of unique payment tokens. |message (string) | A brief description of the result of the request for a token or tokens. |result (boolean) | A boolean which signifies the result of the request for a token or tokens. |cardData | See [ResponseCardData.](#section/ResponseCardData) |validationData | See [ResponseValidationData.](#section/ResponseValidationData) ## ResponseCardData Parameters | Parameter Name| Description |-----|----- |cardBrand (string)| The brand of the card being charged, for example VISA, MasterCard, American Express. |nameOnCard (string) |Card owner’s name as it appears on the card. |expirationDate (string) |Date the card expires as it appears on the card. |lastFour (string) |The last four digits of the card number. |cardType (string) |The type of card being charged, for example Credit or Debit. |cardCategory (string) | The card category if it has one, for example Gold, Platinum, etc. ## ResponseValidationData Parameters | Parameter Name| Description |-----|----- |avsResponse (string)| Result of an AVS (Address Verification System) check when the AdminGetToken request parameter validateCard is set to true/yes. ||View the [AVS Response Fields.](#section/avs-response-fields) |cvvResponse (string) |Result of a CVV check when the AdminGetToken request parameter validateCard is set to true/yes. | |View the [CV Response Fields.](#section/cv-response-fields) |authMessage (string) |Message indicating the status of the authorization request. |authReturnCode (interger) |Code indicating the status of the authorization request. ## Complete the Transaction The IBX library only generates a token and you need to finish charging the card on your server. When the token is posted back to your page, you can do what you like with the response data but typically you will want to create named form elements for at least the payment token that was returned and then submit the actual form itself to your endpoint. For example, your code to capture the payment token in JS could look like the following simple jQuery example where we take the payment token, last four digits of the card, and the name on the card and return it to our endpoint via hidden fields posted via the actual form submit. ``` function ISVIBXResponseHandler(response) { var $form = $('#payment'); if (response.result) { $form.append($('').val(response.token)); $form.append($('').val(response.cardData.lastFour)); $form.append($('').val(response.cardData.nameOnCard)); // Submit the form: $form.get(0).submit(); } else { // Show the errors on the form: $form.append($('').val(response.error.message)); } }; ``` You will then use the existing SOAP API for Card Safe [processCreditCard](#section/processCreditCard) with the TokenMode “JSTOKEN” to actually use the card. (Refer to Card Safe processCreditCard for more information.). ``` safeResponse = safe.ProcessCreditCard("username", "password", "sale", "paymentToken", "jstoken", "amount", "", "", ""); ``` As a final note, be aware that you can and must use your merchant token (which can be shared publicly) for this API however when it comes time to charge the card on your server you must use your private SOAP API credentials (definitely never share these) to actually charge the card. # 10.2. Hosted Page ## Introduction The Hosted Page is a ‘Cloud Based’ integration solution that dramatically reduces the burden of PCI DSS compliance for merchants, and “de-scopes” POS software solutions from the onerous PA-DSS standard. This solution is fully ‘brand able’ and requires minimal programming knowledge/effort to implement. There are two primary methods for implementing this page. - Traditional ‘Redirect/Post Back’ (Simple) Methodology ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/hosted1.jpg) - iFrame/Hosted Form (Advanced) Methodology: ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/hosted2.png) ## Configuration Configuration of the Hosted Page was designed to allow for maximized branding capability with little to no advanced programming knowledge. Our Hosted Page application branding is generated dynamically, and can be customized straight out of the Virtual Terminal interface. Simply navigate to ‘Tools’ and then ‘Hosted Page’ from within the Virtual Terminal to access the configuration utility **Note: If you do not have access to the Hosted Page configuration, please verify that your user account has sufficient privileges to view the configuration utility. If your user account has sufficient privileges, please contact technical support to enable the Hosted Page in your gateway account. The Hosted Page Configuration Utility is broken up into 5 tabs listed and explained in the sections below. ## Options This tab allows you to activate and name your Hosted Page. Options on this page are as follows: **_Page Title:_** This field allows you to name the Hosted Page. The name is what will appear at the top of the Card Holder’s browser window if you are utilizing the ‘Redirect Methodology’ when implementing the hosted page. **_Page is Active:_** This checkbox indicates whether the Hosted Page has been activated. This check box must be enabled prior to moving forward with additional configuration of the Hosted Page. **_Restrict Referring Host:_** This checkbox indicates that whether or not the Hosted Page will be IP Limited.**Important: If you are using the Hosted Page for anything other than collecting donations, it is STRONGLY recommended that you enable this option to ensure that you are protected against ‘man in the middle’ type attacks. **_Allowed Host:_** This field indicates the IP address of the web page that will be initiating requests against your Hosted Page. If ‘Restrict Referring Host’ is selected, and no valid value is entered in this field, the Hosted Page will not be accessible from any external page. **_Email Pay Notification:_** This checkbox indicates whether or not you would like email notifications of payments collected on your Hosted Page sent to members of your staff. This is necessary if utilizing the Hosted Receipt page, or if you cannot programmatically interpret response values generated by the Hosted Page. If selected, a new field will appear allowing you to add the email addresses at which you would like to receive notifications that payments have been collected. Simply enter the desired email address and select ‘Add.’ You can add as many email addresses as you like. ## Fields This tab allows you to dictate what fields display on your hosted page, as well as control what URL’s you want the hosted page to interact with. **_Customer Specifies Amount:_** This checkbox indicates whether or not you will allow the cardholder to enter the amount or if you will pass the amount value for the transaction in the request to load the page. Do not select this option unless you are allowing the cardholder to designate the amount of the transaction they are going to run. **_Submit Button URL:_** This field indicates the URL that the ‘Submit’ button on the Hosted Page will point to. This option is ignored if you select ‘Use Hosted Receipt.’ **_Use Hosted Receipt:_** This checkbox indicates whether or not you would like the response values displayed on our Hosted Receipt page. **_Error URL:_** This field indicates the URL you would like the Hosted Page to redirect to should an unexpected error arise. **_Continue URL:_** This field indicates the URL you would like the Hosted Page to redirect to when the continue button is selected on the Hosted Receipt Page. **_Field Visibility:_** This series of checkboxes indicates what panels – outside of the credit card panel – and what fields contained within those panels are to be displayed. This will change considerably if you have custom fields enabled and configured in your hosted page, but the configuration of these options is very straight forward. Simply check the box of the panel which contains the fields you want to display, and then select the fields you want to display within that panel. **_Show Donation Amounts:_** This checkbox indicates whether or not your Hosted Page will display suggested donation amounts. **_Amount Options:_** This field allows you to set suggested donation amounts on your Hosted Page. See the following example: This configuration: ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/hosted-page-donation-amount-1.png) Yields the following in the Hosted Page: ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/hosted4-300x89.png) Simply enter an amount in the ‘Amount Options’ field and then select ‘Add Option’, and the amount that you enter will be reflected as an option on the hosted page. If you would like to remove an option, select it from the list and select the ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/hosted5.png) and the amount will be removed from the list. ## Appearance This tab allows you to alter the look and feel of the Hosted Page to have it match your web site or POS application. **_Font Color:_** This dropdown indicates the color that the primary text of the page will be displayed in. **_Page Background Color:_** This dropdown indicates the color of the background of the page. **_Panel Background Color:_** This dropdown indicates the background color of each panel. **_Font:_** This dropdown allows you to set the type face that the primary text of the page will be displayed in. **_Font Size:_** This slide bar allows you to set the size of the type face that the primary text of the page will be displayed in. **_Header Background Color:_** This dropdown indicates the color of the panel header. **_Header Font:_** This dropdown indicates the type face that the panel header text will be displayed in. **_Header Font Size:_** This slide bar indicates the size of the type face that the panel header text will be displayed in. **_Header Font Color:_** This dropdown indicates the color of the type face that the panel header text will be displayed in. **_Panel Width Configuration:_** The options shown below will allow you to control the width of each panel by either pixel count or percentage of the total size of the page. See below: ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/hosted-page-panel-width-300x150.png) If you select ‘Panel Width = Header Width’ the panel width will be set to equal the width of any banner that has been uploaded for the page. **_Control Skin:_** This dropdown allows you to configure the way the form decorator will display text boxes and buttons on the hosted page. **_The Page Banner:_** Hit select to open the image uploader. Select a ‘.jpg’ file of the banner you would like to display and select ‘Open.’ Currently the Hosted Page only supports ‘.jpg’ format images. **_Hide Banner:_** This checkbox allows you to hide a banner if one has been uploaded, but you do not wish to display a banner on the hosted page. **_Preview:_** The ‘Preview’ button allows you generate a preview of how the Hosted Page will appear. ## Security This tab holds the button that will generate Hosted Page credentials. This will generate a new secure username and password combo each time you select the button, so only select this if you have reason to believe that your credentials were compromised. This token will allow you to access your hosted page programmatically, but are only useful within the context of the Hosted Page. This secure token will not allow access through our web services API, and will not allow access to the virtual terminal. The credentials that are generated are required to properly generate the hosted page. ## Button This tab allows you to generate a button that will display the Hosted Page preconfigured with a given amount. Simply enter an amount in the ‘Amount’ field, and select ‘Generate HTML.’ This will create the HTML necessary to load your hosted page and is helpful for processing static single transactions for a given amount. This HTML can be copied and pasted into your web site, and will allow you to process a simple transaction with virtually no knowledge of HTML or web programming. ## Field Definitions ## Service Location https://gateway.ibxpays.com/ws/hosted.aspx ## Hosted Page Input Parameters These values must all be separated by the ‘&’ character and appended to the service location of the hosted page. _Example (to be used as a formatting reference only):_ **https://gateway.ibxpays.com/ws/hosted.aspx? Username=tUhbZ8%2bhVy2pvrHUvXA%3d%3d&Password=76%2fP0EP7La9Go6dn4OgLH9lI5zT0fykgUKAyTi3KbNlhGAf%2fLsNpimtPqqN9&MerchantKey=11111** Unless noted otherwise, the parameter is **required.** | Parameter Name| Description |-----|----- | UserName| The Username parameter generated in the security tab of the Hosted Page configuration utility. |Password | The Password parameter generated in the security tab of the Hosted Page configuration utility. |MerchantKey | This is the Gateway ID of the gateway account you are trying to connect to. This value is also referred to as the Vendor Key or RPNumber. | CustomerName| This is the card holder name value. |Optional | |ShippingAddress1 | Identifies the first line of the card holder’s shipping address. |Optional | |ShippingAddress2 |Identifies the second line of the card holder’s shipping address. |Optional | | ShippingState| Identifies the State of the card holder’s shipping address. |Optional | |ShippingCity |Identifies the City of the card holder’s shipping address. |Optional | |ShippingZip | Identifies the Zip code of the card holder’s shipping address. |Optional | |ShippingIsBilling Optional | A Boolean field which allows the integrator to specify that the shipping address and billing address are equivalent. If this field is passed in and set to ‘True’, all billing address information passed to the hosted page will be ignored. |BillingAddress1 | Identifies the first line of the card holder’s billing address. |Optional | |BillingAddress2 | Identifies the second line of the card holder’s billing address. |Optional | |BillingState | Identifies the State of the card holder’s billing address. |Optional | |BillingCity | Identifies the City of the card holder’s billing address. |Optional | |BillingZip | Identifies the Zip code of the card holder’s billing address. |Optional | |Amount | Amount of the transaction you are trying to run. This value is required if you are not allowing the customer to specify the amount. |Required if not allowing customer to specify amount | |InvNum | Invoice Number to be associated with the current transaction. |Optional | |CustomerID | The Customer ID value to be associated with the current transaction. |Optional | |TaxAmount | The Tax Amount to be associated with the current transaction. |Optional | |ShippingAmount | The Shipping Amount to be associated with the current transaction. |Optional | ## Hosted Page Response Fields All response fields will match the existing response field definitions. The following additional information will be returned with the authorization response to allow you to accurately store and handle the token response from the gateway | Parameter Name| Description |-----|----- | LastFour| The last four digits of the credit card number that was collected on the Hosted Page. |ExpDate | The expiration date of the credit card number that was collected on the Hosted Page. |InvNum | The invoice number of the transaction for reconciliation purposes. # 11. Gateway Emulator ## Introduction The Gateway Emulator is a translation layer API that allows an integrator to leverage existing development work against another Payment Gateway application and communicate with our web services API. The utility is fairly simple, and functions as a field mapping utility that translates from one message format to another. This utility is designed to accommodate any HTTP POST or GET format quickly and easily, and can be used with any Open Source shopping cart to quickly allow a merchant to adapt the shopping cart integration to our gateway. Send all requests from your existing integration to the following URL: **_https://gateway.ibxpays.com/emulator/handler.ashx?EmulatorID=nn_** The emulator ID “nn” should match the Emulator ID that has been assigned by the Emulator Configuration Utility. ## Configuration Configuration of the emulator is very simple, and allows the integrator to map the fields from one request format to those of our standard API, and map the responses generated by the gateway to a format that the integrator is already expecting. Simply navigate to ‘Tools’ and then ‘Emulator’ from within the Virtual Terminal to access the configuration utility. **Note: If you do not have access to the Emulator configuration, please verify that your user account has sufficient privileges to view the configuration utility. If your user account has sufficient privileges, please contact technical support to enable the Emulator in your gateway account. The Emulator Configuration Utility is explained below. ## Adding a New Emulator To add a new emulator click ‘Add New’ in the top left hand corner of the grid on the ‘Emulator’ page. From here you will be brought to the ‘Global Settings’ tab. These settings must be completed in order to add a new emulator. **_Method:_** This radio button selects the HTTP method that the new emulator will accept requests in. You can select from HTTP GET, or HTTP POST **_Description:_** This is the name of the emulator that you are creating. This field is ‘user define’ and can be whatever the integrator chooses it to be. It is best to choose a name that accurately reflects the gateway/integration method that you are emulating **_Source IP:_** The source IP address should be set to the IP address that you will be accessing the emulator from. This field is critical if you are not able to pass an emulator ID into the url of the request. It is recommended for security purposes that you add the source IP to ensure that you are restricting access to the API to trusted sources only. Click ‘Save’ once you have properly configured this tab. ## Field Mapping Configuration **_Template:_** The template drop down allows you to select from ‘pre-populated’ emulation templates. If you do not see the template that you are looking for, please contact technical support. Click ‘Load’ to generate the fields of a pre-configured emulation ## Add Field Mapping To add a new request field, simply click the ‘Add field mapping’ button, and follow the steps below: 1. Enter the name of the Source Field. The source field should match the name of the field that you are sending in your current integration. 2. Then select the corresponding field that you would like the emulator to map to from the ‘Destination Field’ drop down menu. 3. Click ‘Insert’ to save the field or click ‘Cancel’ to remove the field. 4. Repeat these steps until all fields from your existing integration have been mapped. Any fields that do not have a corresponding field in our Gateway API can be disregarded as the Emulator will simply ignore any additional fields that have not been declared in the ‘Add Field Mapping utility. Repeat these same steps for the ‘Response Field Mapping’ to map out the response fields returned by the gateway. The order will be reversed, however. Here you will first select the response field generated by the gateway, and map it to a field that your integration is expecting. Continue this process until all response fields that are expected by your existing integration are being generated by the emulator. ## Prebuilt Templates ## Configuring Magento for The Gateway Using the Emulator 1. With a working install of Magento, enable the Authorize.net (AIM) payment module. There are 4 settings in the module configuration that will be relevant to enabling traffic to the emulator a. Enabled: Enables/disables the module in Magento. This must be True for the module to work. b. API Login ID: This will be a username (must be an API user) in The Gateway. c. Transaction Key: This is the password for the user entered in the Login ID field. d. Gateway URL: This is directly configurable in the Magento UI and will point to the emulator on the The Gateway servers. https://gateway.ibxpays.com/Emulator/handler.ashx?EmulatorID= magento payment method ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/magento-payment-method.png) 2. Create an emulator in The Gateway that will be used for this integration. Save the values on the first screen, which will enable the fields tab. a. Method: Authorize.net AIM for Magento uses Post b. Description: Any value recognizable to the user c. Source IP: An advanced option, allowing The Gateway to determine which Emulator profile to load based on the client ip address, as opposed to supplying an Emulator ID in the request ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/magento-global-settings-2.png) 3. Load the Authorize.net (Magento/OSCommerce) template. This will create a number of pre-mapped request and response fields needed to match the Authorize.net response and request to the The Gateway request and response. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/authorize-net-request-field-mapping.png) 4. Finally, several of the Authorize.net fields do not have a direct value conversion to The Gateway. For example, an approval on The Gateway will have a Result Code of 0. On Authorize.net, an approval will have a Response Code of 1. It is not enough to simply map the Result Code of The Gateway to the Response Code of Authorize.net – 0 has no meaning for this field on Authorize.net. In addition to mapping the field, The Gateway’s Emulator will also use a Value Map to properly handle this field (found under Advanced properties of a field mapping) ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/value-map-result-code.png) This particular map will convert a result of 0 from The Gateway to a 1 for Authorize.net. Additionally, it will convert a value of 12 (decline) from The Gateway to a 2 for Authorize.net. Additional value maps can be added as needed. Value Maps are also important for the Transaction Type field in the request. Similar to the Response Code, the conversion is not straight across. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/value-map-response-code-300x114.png) These values are preloaded with the Authorize.net template. ## Configuring OSCommerce for The Gateway Using the Emulator 1. With a working install of OSCommerce, enable the Authorize.net (AIM) payment module. There are 4 settings in the module configuration that will be relevant to enabling traffic to the emulator. a. Enable Authorize.Net (AIM) Module: Enables/disables the module in OSCommerce. This must be True for the module to work. b. Login ID: This will be a username (must be an API user) in The Gateway. c. Transaction Key: This is the password for the user entered in the Login ID field. d. MD5 Hash: This can be a value of the user’s choice, but it must match exactly (case-sensitive) the value entered in The Gateway (see below). ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/authorize-net.jpg) ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/authorize-net-AIM.png) e. You may need to edit the includes/modules/payment/authorizenet2.php file that exists in the installation directory of OS Commerce. You can access the installation files on the server where OS Commerce was installed. Then locate the directory for the Auth.net plugin and do a search of the files in that directory for anything containing secure.authorize.net and replace those URLs with the gateway’s emulator URL. 2. Create an emulator in The Gateway that will be used for this integration. Save the values on the first screen, which will enable the fields tab. a. Method: Authorize.net AIM for OSCommerce uses Post b. Description: Any value recognizable to the user c. Source IP: An advanced option, allowing The Gateway to determine which Emulator profile to load based on the client ip address, as opposed to supplying an Emulator ID in the request d. Hash value: This corresponds to the Hash Value entered in Authorize.net (AIM) payment module ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/emulator-oscommerce-global-settings-1.png) 3. Load the Authorize.net (Magento/OSCommerce) template. This will create a number of pre-mapped request and response fields needed to match the Authorize.net response and request to the The Gateway request and response. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/authorize-net-ZEN-request-code-1.png) 4. The Authorize.net AIM spec has several features which, although optional to Authorize.net, are required by OSCommerce. a. MD5 hash in the response: Authorize.net supports a hash of a pre-defined hash value, username, transaction id and amount returned in the response. OSCommerce will calculate this value and expect a match in the response from the The Gateway emulator. This is accomplished via the Field Formula in the Advanced Options of the Response field. As the screenshot below shows, the fields HashValue, Username, Transaction ID and Amount are included in a call to a MD5 function (all surrounded in parenthesis). Each value enclosed in square brackets is intended to be replaced with the actual value from that field. For example, [HashValue] will be replaced with the value specified in the previous steps (abcd in this example). This allows the return value of a given field to be dynamic, depending on the actual request and response values of a given transaction. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/adv-field-mapping-MD5.png) b. Amount in the response: Similar to MD5 this value depends on a FieldFormula, but it is very simple. This formula will simply be replaced with the Amount value passed in the request. No other modifications will be made. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/oscomm-field-code-1.png) 5. Finally, several of the Authorize.net fields do not have a direct value conversion to The Gateway. For example, an approval on The Gateway will have a Result Code of 0. On Authorize.net, an approval will have a Response Code of 1. It is not enough to simply map the Result Code of The Gateway to the Response Code of Authorize.net – 0 has no meaning for this field on Authorize.net. In addition to mapping the field, The Gateway’s Emulator will also use a Value Map to properly handle this field (found under Advanced properties of a field mapping) ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/value-map-result-code.png) This particular map will convert a result of 0 from The Gateway to a 1 for Authorize.net. Additionally, it will convert a value of 12 (decline) from The Gateway to a 2 for Authorize.net. Additional value maps can be added as needed. Value Maps are also important for the Transaction Type field in the request. Similar to the Response Code, the conversion is not straight across. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/value-map-response-code.png) These values are preloaded with the Authorize.net template. ## Configuring ShopSite for The Gateway Using the Emulator 1. ShopSite provides a custom payment provider called Gateway Emulator. Select this in the payment configuration of the store, and click Configure Processor. There will be 5 settings to configure to enable the ShopSite store to process with The Gateway. a. Host: This is simply the domain name of the gateway b. Port: 443, for SSL c. Authorize Script: /emulator/handler.ashx?EmulatorID= where is the identifier from the The Gateway UI after an Emulator Profile is created (see below) d. API Login ID: This will be a username (must be an API user) in The Gateway. e. Transaction Key: This is the password for the user entered in the Login ID field. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/select-processor.png) ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/gateway-emulator-settings.png) 2. Create an emulator in The Gateway that will be used for this integration. Save the values on the first screen, which will enable the fields tab. a. Method: Authorize.net AIM for ShopSite uses Post b. Description: Any value recognizable to the user c. Source IP: An advanced option, allowing The Gateway to determine which Emulator profile to load based on the client ip address, as opposed to supplying an Emulator ID in the request ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/emulator-shopsite-global-settings.png) 3. Load the Authorize.net (Magento/OSCommerce) template. This will create a number of pre-mapped request and response fields needed to match the Authorize.net response and request to the The Gateway request and response. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/authorize-net-request-field-mapping-1.png) 4. Finally, several of the Authorize.net fields do not have a direct value conversion to The Gateway. For example, an approval on The Gateway will have a Result Code of 0. On Authorize.net, an approval will have a Response Code of 1. It is not enough to simply map the Result Code of The Gateway to the Response Code of Authorize.net – 0 has no meaning for this field on Authorize.net. In addition to mapping the field, The Gateway’s Emulator will also use a Value Map to properly handle this field (found under Advanced properties of a field mapping) ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/value-map-result-code.png) This particular map will convert a result of 0 from The Gateway to a 1 for Authorize.net. Additionally, it will convert a value of 12 (decline) from The Gateway to a 2 for Authorize.net. Additional value maps can be added as needed. Value Maps are also important for the Transaction Type field in the request. Similar to the Response Code, the conversion is not straight across. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/value-map-response-code.png) These values are preloaded with the Authorize.net template. ## Configuring VirtueMart for The Gateway Using the Emulator 1. With a working install of VirtueMart, enable the Authorize.net (AIM) payment module. There are 3 settings in the module configuration that will be relevant to enabling traffic to the emulator a. Enable Authorize.Net (AIM) Module: Enables/disables the module in VirtueMart. This must be True for the module to work. b. Login ID: This will be a username (must be an API user) in The Gateway. c. Transaction Key: This is the password for the user entered in the Login ID field. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/virtuemart-config-tab.png) 2. Create an emulator in The Gateway that will be used for this integration. Save the values on the first screen, this will enable the fields tab. a. Method: Authorize.net AIM for VirtueMart uses Post b. Description: Any value recognizable to the user c. Source IP: An advanced option, allowing The Gateway to determine which Emulator profile to load based on the client IP address, as opposed to supplying an Emulator ID in the request ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/virtuemart-global-settings-1.png) 3. Load the Authorize.net (VirtueMart) template. This will create a number of pre-mapped request and response fields needed to match the Authorize.net response and request to the The Gateway request and response. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/authorize-net-virtuemart-global-settings-1.png) 4. Several of the Authorize.net fields do not have a direct value conversion to The Gateway. For example, an approval on The Gateway will have a Result Code of 0. On Authorize.net, an approval will have a Response Code of 1. It is not enough to simply map the Result Code of The Gateway to the Response Code of Authorize.net – 0 has no meaning for this field on Authorize.net. In addition to mapping the field, The Gateway’s Emulator will also use a Value Map to properly handle this field (found under Advanced properties of a field mapping) ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/value-map-result-code.png) This particular map will convert a result of 0 from The Gateway to a 1 for Authorize.net. Additionally, it will convert a value of 12 (decline) from The Gateway to a 2 for Authorize.net. Additional value maps can be added as needed. Value Maps are also important for the Transaction Type field in the request. Similar to the Response Code, the conversion is not straight across. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/value-map-response-code.png) These values are preloaded with the Authorize.net template. ## Configuring Zencart for The Gateway Using the Emulator 1. With a working install of Zencart, enabled the Authorize.net (AIM) payment module. There are 4 settings in the module configuration that will be relevant to enabling traffic to the emulator a. Enable Authorize.Net (AIM) Module: Enables/disables the module in Zencart. This must be True for the module to work. b. Login ID: This will be a username (must be an API user) in The Gateway. c. Transaction Key: This is the password for the user entered in the Login ID field. d. MD5 Hash: This can be a value of the user’s choice, but it must match exactly (case-sensitive) the value entered in The Gateway (see below). ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/zencart-auth-net.png) 2. Create an emulator in The Gateway that will be used for this integration. Save the values on the first screen, this will enable the fields tab. a. Method: Authorize.net AIM for Zencart uses Post b. Description: Any value recognizable to the user c. Source IP: An advanced option, allowing The Gateway to determine which Emulator profile to load based on the client IP address, as opposed to supplying an Emulator ID in the request d. Hash value: This corresponds to the Hash Value entered in the Authorize.net (AIM) payment module. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/zencart-global-settings-3.png) 3. Load the Authorize.net (Zencart) template. This will create a number of pre-mapped request and response fields needed to match the Authorize.net response and request to the The Gateway request and response. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/zencart-request-fields-1.png) 4. The Authorize.net AIM spec has several features which, although optional to Authorize.net, are required by Zencart. a. MD5 hash in the response: Authorize.net supports a hash of a pre-defined hash value, username, transaction id and amount returned in the response. Zencart will calculate this value and expect a match in the response from the The Gateway emulator. This is accomplished via the Field Formula in the Advanced Options of the Response field. As the screenshot below shows, the fields HashValue, Username, Transaction ID and Amount are included in a call to a MD5 function (all surrounded in parenthesis). Each value enclosed in square brackets is intended to be replaced with the actual value from that field. For example, [HashValue] will be replaced with the value specified in the previous steps (abcd in this example). This allows the return value of a given field to be dynamic, depending on the actual request and response values of a given transaction. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/zencart-adv-field-map-1.png) b. Amount in the response: Similar to MD5 this value depends on a FieldFormula, but it is very simple. This formula will simply be replaced with the Amount value passed in the request. No other modifications will be made. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/zencart-field-formula-1.png) 5. Finally, several of the Authorize.net fields do not have a direct value conversion to The Gateway. For example, an approval on The Gateway will have a Result Code of 0. On Authorize.net, an approval will have a Response Code of 1. It is not enough to simply map the Result Code of The Gateway to the Response Code of Authorize.net – 0 has no meaning for this field on Authorize.net. In addition to mapping the field, The Gateway’s Emulator will also use a Value Map to properly handle this field (found under Advanced properties of a field mapping) ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/value-map-result-code.png) This particular map will convert a result of 0 from The Gateway to a 1 for Authorize.net. Additionally, it will convert a value of 12 (decline) from The Gateway to a 2 for Authorize.net. Additional value maps can be added as needed. Value Maps are also important for the Transaction Type field in the request. Similar to the Response Code, the conversion is not straight across. ![alt sample](https://www.payroc.com/Common/Images/Custom/5982/api-docs/value-map-response-code.png) These values are preloaded with the Authorize.net template. version: 1.0.0 title: SOAP APIs termsOfService: 'https://www.payroc.com/privacy-policy' contact: url: 'https://www.integritypays.com/contact/' license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' x-logo: url: 'https://www.payroc.com/Common/Images/Custom/5982/Payroc_LOGO_Orange.png' produces: - application/json consumes: - application/json paths: /GetCardTrxSummary: get: tags: - Endpoints summary: GetCardTrxSummary description: | The following examples (cURL, PHP, Node.js, and Ruby) can be used when you are not using a SOAP based, .NET service. The examples show similar ways of doing the same thing in each environment. Note that we also have a postman collection that can quickly bring you up to speed for basic transaction processing using our easy HTTP GET/POST wrapper for our SOAP API as well as REST APIs. Once you open the link below look for the “IBX Beginner Collection”. [![Run in Postman](https://run.pstmn.io/button.svg)](https://www.getpostman.com/run-collection/dd06f5a44925cb0e1b3a) operationId: PaymentMethod parameters: - name: UserName in: query description: User name type: string required: true - name: Password in: query description: Password type: string required: true - name: RPNum in: query description: RPNum type: integer required: true - name: BeginDt in: query description: BeginDt type: string required: true - name: EndDt in: query description: EndDt type: string required: true - name: ApprovalCode in: query description: Approval Code type: integer required: false - name: Register in: query description: Register type: integer required: true - name: NameOnCard in: query description: Name On Card type: integer required: false - name: CardNum in: query description: Card Num type: integer required: false - name: Card Type in: query description: Card Type type: string required: false - name: ExcludeVoid in: query description: Exclude Void type: boolean required: true - name: User in: query description: User type: string required: true - name: invoiceId in: query description: invoice Id type: integer required: false - name: SettleFlag in: query description: Settle Flag type: integer required: false - name: SettleMsg in: query description: Settle Msg type: string required: false - name: SettleDt in: query description: Settle Dt type: string required: false - name: TransformType in: query description: Transform Type type: string required: false - name: Xsl in: query description: Xsl type: string required: false - name: ColDelim in: query description: Col Delim type: string required: false - name: RowDelim in: query description: Row Delim type: string required: false - name: IncludeHeader in: query description: Include Header type: boolean required: true - name: ExtData in: query description: ExtData type: string required: false produces: - application/json responses: '200': description: Success schema: $ref: '#/definitions/paymentMethod' definitions: paymentMethod: type: object description: standard transaction response fields properties: Payment_Type_ID: type: string Authorization: type: number Capture: type: number ForceCapture: type: number PostAuth: type: number Return: type: number Sale: type: number Receipt: type: number RepeatSale: type: number Activate: type: number Deactivate: type: number Reload: type: number Authorization_Cnt: type: number Capture_Cnt: type: number ForceCapture_Cnt: type: number PostAuth_Cnt: type: number Return_Cnt: type: number Sale_Cnt: type: number Receipt_Cnt: type: number RepeatSale_Cnt: type: number Activate_Cnt: type: number Deactivate_Cnt: type: number Reload_Cnt: type: number Cnt: type: number