Home

SureGate API Documentation

Contents

1. 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 s
2. Returns the name of ANS isane ecane NameOnCheck_VC A string value upto Returns the check 25 characters payer s name on the check Orig TRX_HD_ Key A string value Returns the representing a TRX_HD_Key on signed 32 bit which the current integer transaction is based Payment_Type_ID A string value up to Returns the 10 characters payment type e g Page 88 of 103 SureGate API Documentation a HET PostAuth A string value Returns the representing a dollar amount signed 64 bit real of all PostAuth number transactions PostAuth_Cnt A string value Returns the representing a transaction count signed 32 bit of all PostAuth integer transactions Processor_ID A string value up to Returns the name 10 characters the payment processor e g Vital Receipt A string value Returns the dollar This value will always return 0 representing a amount of all signed 64 bit real transactions with a number Receipt Receipt_Cnt A string value Returns the This value will always return 0 representing a transaction count of signed 32 bit all transactions with integer a Receipt Ref_Number_CH A string Not currently used 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 A string value up to Returns the register 10 characters number of a transaction RepeatSale A string value Returns the representing a dollar amount si
3. SureGate SureGate API Documentation ProcessCreditCard Service Location For SOAP connections https secure suregate net ws transact asmx o0p ProcessCreditCard For standard HTTPS connections https secure suregate net ws transact asmx ProcessCreditCard Description This web service is used whenever a transaction is completed via customer credit card The transaction types supported by this web service include e Sale make a purchase using a credit card e Auth authorize the amount on a credit card e Return credits the card holder s account e Void undo an unsettled transaction e 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 e RepeatSale perform a recurring billing or installment payment transaction Processors supporting the restaurant or retail tip adjustment function only e Adjustment used to modify an existing tip amount for an original sale Terminal based processors only e Capture settle a single transaction in the current batch Terminal based processors and host based processors supporting the batch release feature only e CaptureAll settle all transactions in the current batch Global TSYS and First Data North only e Reversal perform a manual full reversal on a credit card or repeat sale within 24 hours of the original transaction Developer Notes Invali
4. SureGate SureGate API Documentation training mode is active and transactions are processed for local loop back testing lt TrainingMode gt F lt TrainingMode gt where F false indicates that training mode is inactive and transactions should be treated normally Key Serial Number required for all non PIN less debit transactions PIN pad serial number Valid format is e lt KeySerialNumber gt KeySerialNumber lt KeySerialNumber gt where KeySerialNumber is the PIN pad serial number used in managing DUKPT PIN pads Force optional This is an indicator that specifies whether or not duplicate transactions will be processed Valid formats are e lt Force gt T lt Force gt where T true indicates that duplicate transactions are accepted e lt Force gt F lt Force gt where F false indicates that duplicate transactions are not accepted Note Some processors including BuyPass will not recognize this tag and reject duplicate transactions GLOBAL Interac Specific Tags The Global Canadian platform and does not require the US standard KeySerialNumber tag In its place this platform uses the Canadian MAC specific tags listed below All of the tags within the lt MAC gt lt MAC gt tags are required to process Canadian debit transactions Opreg CO lt TID gt TID Value lt TID gt TID or terminal Identification number is configured based on the PIN pad used as assigned by the processor These tags are required by the AddRever
5. CustomFields gt 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 lt CustomFields gt tag must be passed in the ExtData field of the web service you are consuming The lt CustomFields gt tag must contain no spaces and must conform to XML standards Page 42 of 103 SureGate SureGate API Documentation ManageCustomer Service Location For SOAP connections https secure suregate net admin ws recurring asmx 0p ManageCustomer For standard HTTPS connections https secure suregate net admin ws recurring asmx ManageCustomer Description 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 Developer Notes It is very important to understand that this web service is used for storing data and is not for querying previously stored data It is the responsibility of the integrator to store and maintain all returned Info Keys for later use When calling this service with a TransType value of UPDATE it is also
6. Page 15 of 103 SureGate SureGate API Documentation ProcessDebitCard Service Location For SOAP connections https secure suregate net ws transact asmx op ProcessDebitCard For standard HTTPS connections https secure suregate net ws transact asmx ProcessDebitCard Description This web service is used whenever a transaction is completed via customer debit card The processes supported by this web service include e Sale make a purchase using a debit card e Return credits the card holder s account BuyPass fuel transactions only e Auth authorize the amount on a debit card e Force force an Auth transaction in to the current batch PostAuth Terminal based processors only e Capture settle a single transaction in the current batch Terminal based processors and host based processors supporting the batch release feature only e CaptureAll settle all transactions in the current batch Global Canadian Debit only e 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 Global TSYS and First Data North only e Reversal perform a manual full reversal on a debit card sale within 24 hours of the original trans
7. SureGate API Documentation Page 97 of 103 SureGate SureGate API Documentation Result Response Field Definition Top Response Field Definitions Description Transaction NOT Processed Generic Host Error Approved User Authentication Failed Invalid Transaction Page 98 of 103 SureGate API Documentation 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 Duplicate Transaction a fe m2 ews O Page 99 of 103 SureGate API Documentation ExtData Field Definitions Top BatchNum Current batch number for Not all payment processors support returning this transactions settlement and data element batch inquiries CardType Credit card type VISA This value is not returned for Check ACH MASTERCARD etc or payment payments method Debit EBT or EGC for card based payments Invoice number for the transaction that was originally sent in the request to the Payment Server Page 100 of 103 SureGate SureGate API Documentation AVS Response Field Definitions top Description Exact Address and nine digit Zip match Yes Address and five digit Zip match A Address Address matches Zip does not Z W_
8. 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 Global TSYS and First Data North only e 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 ee payment processor the merchant account is configured for See Developer Notes for additional information Debit card number used to uniquely identify the owner s account Debit card date of expiration in MMYY format Data located the magnetic strip on the back of the card The format of Page 18 of 103 SureGate SureGate API Documentation NameOnCard PNRef the MagData is CardNum ExpDate followed by the service date and checksum For example 36438999960016 05121015432112345678 Please ensure you have parsed out the Card Number and the Expire date from the Track data Refer to sample in useful tips Card owner s name as it appears on the card Total transaction amount in DDDD CC format 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 Unique payment reference number used to identify a single transaction within the system The payment reference number PNRef is
9. Whole zp saiet Zie marches aaresto OOOO N__ RerNetheraddrssnordipmates CS U Uraalaber adres iformationnorwaiable Ci a Unavaabe Adres internation not avaiable for niewatonalwanacion R Retry Retry System unavailable or time out unavailable or time out Error Transaction unintelligible Se AVS or edit error found in the message that prevents AVS from being performed 5 NetSinrored suer doente means OOOO a sist aah Sreet adresses reich for ternational nsacton ik posal ode doet o Maih street aderessesand postal codesmatchforinterationalansadion 1 Not vee Address formation not verified for ieratonalwansacion Festa Merh Postal codes match for international transaction but street address doesnt Co eee OO OSOSOSCSCSCSCSCSCSCSC dY Page 101 of 103 SureGate API Documentation CV Response Field Definitions top Description CW2 CVC2 CID Match CVV2 CVC2 CID No Match eT Not Processed S Issuer indicates that the CV data should be present on the card but the merchant has indicated a eee ara o rrn e U Unknown Issuer has not certified for CV or issuer has not provided Visa MasterCard with the Ee ie Server Provider did not respond Page 102 of 103 SureGate API Documentation Technical Support Top If you are experiencing an issue that you are unable to resolve please contact us using the below customer service information SureGate LLC 115 Pelham Commons Blvd Greenville SC 29615 Telep
10. 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 Leave this field Null if not keeping track of numeric values MaxLength aa Maximum string length allowed in the field being added Default value is 25 RegEx Enter any regular expressions needed to validate that the values being submitted to this field conform to a specific data type and or format IsRequired Boolean indicating whether or not the integrator wishes this field to be required for all transactions Valid values are True and Falese Description This is the human readable description that will display in the virtual terminal and on the cardholder receipt MinValue Minimum numeric value MaxValue i Maximum numeric value DisplayOnReceipt This is a boolean parameter Indicates whether or not the field will display on the cardholder receipt Page 59 of 103 SureGate SureGate API Documentation GetCardTrx Service Location For SOAP connections https secure suregate net admin ws trxdetail asmx op GetCardTrx For standard HTTPS connections https secure suregate net admin ws trxdetail asmx GetCardTrx Description 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 e Build a variety of custom r
11. 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 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 Valid values are Page 71 of 103 SureGate SureGate API Documentation 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 fro
12. Page 45 of 103 SureGate SureGate API Documentation ManageCreditCardInfo Service Location For SOAP connections https secure suregate net admin ws recurring asmx o0p ManageCreditCardInfo For standard HTTPS connections https secure suregate net admin ws recurring asmx ManageCreditCardinfo Description 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 Developer Notes The service returns a CCInfoKey value which takes the place of the cardholder data with which it is associated It is the responsibility of the integrator to keep track of and store these keys An unlimited number of credit card profiles can be stored for any given customer Input Parameters O Optional R Required one UserName User name assigned in the payment server The user must have an Password TransType appropriate level of access within the system in order to utilize the web service Password associated with the user name provided Indicates whether the payment type is being added updated or deleted Valid entries are ADD UPDATE DELETE 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 acces
13. Required on Force and Capture transactions RS Required on all swiped card transactions Parameter Opt Req Description me r P UserName User name assigned in the payment server The user must have an D a ee Password TransType Password associated with the user name provided ae Identifies the type of debit card transaction being made Valid values are e 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 EBT card number used to uniquely identify the owner s account EBT card date of expiration in MMYY format Data located on the magnetic strip on the back of the card The format NameOnCard of the MagData is CardNum ExpDate followed by the service code and checksum F
14. 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 Additionally in the sample code section of this API review both the PHP and ASP classic examples as they have a good example of a properly formed HTTPS request 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 Page 4of 103 SureGate SureGate API Documentation Useful Tips top The API documentation is quite comprehensive however we have a few items to pay special attention as it will reduce the time to integrate into the API solution Parameters This applies to all functions you MUST pass ALL parameters in each request Even if the parameter does not apply to what you are doing example Passing a credit card number when already sending a transaction id This will save you considerable debugging and triaging problems Parameter names are NOT CASE SENSITIVE Track1 Track2 Data When submitting Track1 or Track2 data to the SureGate gateway there is a very important item to note You must parse out the CREDIT CARD and EXPIRE DATE from the track data The credit card and expire date parameters you will be sendi
15. for 31 day months and or leap years For example e Recurring billing is set to run once monthly e 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 BillingInterval This value is used in conjunction with the BillingPeriod to compute the next bill date for a contract Valid values are 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 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 Failurelnterval FO Note This parameter has been deprecated EmailCustomer Indicates whether the system will send an email to the customer after successfully processing a scheduled payment Valid values are e TRUE Email is sent to the customer after successful payment Page 54 of 103 SureGate SureGate API Documentation e FALSE default Customer is not notified after successful payment Note Email notifications can only be sent if a valid customer contact email has been provide
16. for invalid character processing Note This parameter may be required depending on the merchant s setup Page 9of 103 SureGate API Documentation a e SureGate Card owner s billing address street name and number See Developer Notes for invalid character processing Note This parameter may be required depending on the merchant s setup Card verification number Note This parameter may be required depending on the merchant s setup 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 The following information may be added via the ExtData parameter Authorization Code required when TransType Force Original authorization approval code Valid format is e lt AuthCode gt AuthorizationCode lt AuthCode gt where Authorization Code is the original authorization or approval code Customer Code optional Customer or purchase order PO number used with Level Il information forGlobal Payments only if using another processor that supports Level Il use the PO Number to pass this information instead See Developer Notes for invalid character processing Valid format is e lt CustCode gt CustomerCode lt CustCode gt where Customer Code is the number assigned to identify the customer or the PO number Convenience
17. important to note that any values that are left NULL will overwrite existing data with a NULL value Input Parameters O Optional R Required R Required only when TransType UPDATE Opt Red UserName Password TransType 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 associated with the user name provided Indicates whether the contract is being added updated or deleted Valid entries are e ADD e UPDATE e DELETE 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 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 Vendor under the Preferences menu CustomerKey R 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 Page 43 of 103 SureGate SureGate API Documentation 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 Customer ID Unique identifier as
18. optional This is an indicator that specifies whether or not duplicate transactions will be processed Valid formats are e lt Force gt T lt Force gt where T true indicates that duplicate transactions are accepted lt Force gt F lt Force gt 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 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 e lt TimeOut gt TimeOut lt TimeOut gt where TimeOut is the processor time out value in seconds Register Number optional This is unique identifier for the register terminal or computer used to process the gift card transaction Valid format is e lt RegisterNum gt RegisterNum lt RegisterNum gt where RegisterNum is equal to the register identification number stored on the merchant s account record Paymentech Tampa Onl Force Authorization optional Places a previously authorized transaction TransType Redeem Reload or Activate into the current batch Opie Ko a Page 34of 103 SureGate API Documentation erat lt AuthCode gt AuthCode lt Where AuthCode is the AuthCode gt previously obtained authorization code from Paymentech Tampa Ee a Page 35 of 103 SureGate SureGate API Documentation
19. parameter Time out optional Processor time out value in seconds The default SureChargeAmt CashBackAmt ExtData value for the parameter is 30 seconds for a transaction and 300 seconds for a settlement transaction Valid format is e lt TimeOut gt TimeOut lt TimeOut gt 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 e lt TrainingMode gt T lt TrainingMode gt where T true indicates that training mode is active and transactions are processed for local loop back testing lt TrainingMode gt F lt TrainingMode gt where F false indicates that training mode is inactive and transactions should be treated normally Key Serial Number required for all non PIN less debit transactions PIN pad serial number Valid format is e lt KeySerialNumber gt KeySerialNumber lt KeySerialNumber gt where KeySerialNumber is the PIN pad serial number used in managing DUKPT PIN pads Page 30 of 103 SureGate SureGate API Documentation Force optional This is an indicator that specifies whether or not duplicate transactions will be processed Valid formats are e lt Force gt T lt Force gt where T true indicates that duplicate transactions are accepted e lt Force gt F lt Force gt where F false indicates that duplicate transactions are no
20. 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 ExcludePaymentTy The ExcludePaymentType parameter allows you to exclude certain payment pe types from the result set Any valid entry or combination listed under the Page 61 of 103 SureGate API Documentation ExcludeTransType ApprovalCode E SureGate PaymentType parameter may be used 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 If provided only those transactions matching the TransType will be included 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
21. stored 2 custom fields one named SampleFieldName1 and the other named SampleFieldName2 lt CustomFields gt lt SampleFieldName1 gt Sample String Data lt SampleFieldName1 gt lt SampleFieldName2 gt 8675309 lt SampleFieldName2 gt lt CustomFields gt All data passed through the custom fields parameters will be returned in the GetCardTrx web service call following the same format Input Parameters O Optional R Required R Required based on dependencies UserName User name assigned in the payment server The user must have the apporpriate security permissions in order for the system to return transaction records aaa 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 FieldName The name of the field This value must be unique and will be used to oe programmatically access the field when passing additional data using the Page 58 of 103 SureGate SureGate API Documentation a a ProcessCreditCard web service IsNumeric 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
22. supported in the future Card Verification Presence optional except for First Data transactions Indicates whether card verification CV CVV2 CVC2 or CID has been sent along with the request Valid formats are Page 12 of 103 SureGate SureGate API Documentation lt CVPresence gt 1 lt CVPresence gt where 1 indicates that no CV was provided lt CVPresence gt 2 lt CVPresence gt where 2 indicates that the CV was not submitted i e the card was key entered lt CVPresence gt 3 lt CVPresence gt where 3 indicates that the CV was submitted lt CVPresence gt 4 lt CVPresence gt where 4 indicates that the CV is illegible lt CVPresence gt 5 lt CVPresence gt where 5 indicates that the CV was not present on the card Card Presence optional Indicates whether the card was present for the transaction Valid formats are e lt Presentation gt lt CardPresent gt True lt CardPresent gt lt Presentation gt where True indicates that the card was present at the time of the transaction lt Presentation gt lt CardPresent gt False lt CardPresent gt lt Presentation gt where False indicates that the card was not present at the time of the transaction lt Presentation gt lt CardPresent gt Unknown lt CardPresent gt lt Presentation gt where Unknownindicates that the card may or may not have been present at the time of the transaction Entry Mode optional Indicates how the values for payment information were obtained Va
23. tags Extended data in XML format Valid values are e lt IMAGE_TYPE gt NO_IMAGE lt IMAGE_TYPE gt Will only return transaction data that does not include image data to include signature data and check images lt IMAGE_TYPE gt ONLY_IMAGE lt IMAGE_TYPE gt Will only return transaction data that includes image data to include signature data and check images lt IMAGE_TYPE gt ALL lt IMAGE_TYPE gt will return transaction with or without image data lt CustomerlD gt CustomerlD lt Customer D gt specifies the customer ID value to search by Matching is done using wild cards e g test will match test 1test and 1test234 lt Amount gt Amount lt Amount gt specifies the amount value of the transactions being searched for e lt RegisterNum gt RegisterNum lt RegisterNum gt apecifies the register number originally passed with the transaction to search by Page 69 of 103 SureGate SureGate API Documentation GetCheckTrx Service Location For SOAP connections https secure suregate net admin ws trxdetail asmx op GetCheckTrx For standard HTTPS connections https secure suregate net admin ws trxdetail asmx GetCheckTrx Description 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
24. 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 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 e https lt PMN assigned host name gt 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 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 e g a value of would start each row with I 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 mus
25. the file size Any PKZip compatible Zip compressor and decompressor will work Note IPWorks www ipworks com is a third party provider of software tools and they have a product called IPWorks Zip that can simplify the programmatic compression 4 Base64 encode the image This ensures that the binary based information transported can be converted properly into text based characters to send in the SignatureData parameter of ProcessSignature 5 Input the compressed base64 encoded image data into the SignatureData parameter of ProcessSignature and send it to the Payment Server Input Parameters O Optional R Required 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 PR Password associated with the user name provided SignatureType PR Identifies the format of the signature data being provided Valid values Page 36 of 103 SureGate SureGate API Documentation 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 y14x2 y24xN yN Where is the coordin
26. values are e PERSONAL Check is made from an individual personal checking account e BUSINESS Check is made from a business checking account AccountType Indicates whether the funds come from a checking or savings account Valid values are e CHECKING Check is made from a standard checking account or ACH e SAVINGS Check is made from a savings account CheckNum fo Uniquely identifies an individual s check MICR Magnetic Ink Check Reader data line This data string includes the TransitNum and AccountNum 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 lt RawMICR gt tag under the ExtData parameter for additional information aecouraun R Uniquely identies the check owners baraco Trensum R Uniquely erties the bankholding funds Ao called routne number s fo Gheckowners sosai securiy umber o C 0 theckowners detecting Banna o Gy where the sung berkbranchsloaem for fo Checkownersversieense number StateCode Check owner s standard U S postal service two character state code or other standard province code Note Valid entries should follow USPS two character state code standards For more information see http www usps com ncsc lookups usps_abbreviations html Note See Developer Notes for invalid character processing Nam
27. 0 characters payment processor s time at which the transaction was performed Invoice_ID A string value up to Returns the 100 characters transaction s Invoice number IP_VC A string value up to Returns the IP 15 characters address of the client machine from which the transaction was processed Manual A string value Returns the card was representing a swiped or not Boolean value Merchant_Key A string value Returns a number representing a which uniquely signed 32 bit identifies a integer merchant Name_on_Card_VC Astring value upto Returns the name of NameOnCheck_VC A string value up to Returns the check 25 characters payer s name on the check Orig TRX_HD_Key A string value Returns the representing a TRX_HD_Key on signed 32 bit which the current integer transaction is based Last_Update_DT A string value Returns the date and representing a date time on which the and time transaction is last modified Page 81 of 103 SureGate API Documentation Payment_Type_ID PostAuth_Cnt Ref_Number_CH Register_Number_CH RepeatSale RepeatSale_Cnt A string value up to 10 characters A string value representing a signed 64 bit real number A string value representing a signed 32 bit integer A string value up to 10 characters A string value representing a signed 64 bit real number A string value representing a signed 32 bit integer A string A string value up to 10 characters A s
28. Amount optional Allows the merchant to add a flat fee to the total transaction to recoup the costs of offering the credit card transaction convenience This function may be used by utility companies government agencies and schools Valid format is e lt ConvenienceAmt gt Amount lt ConvenienceAmt gt where Amount is the value to be added to the total transaction in DDDD CC format Tip Amount optional Allows the customer to add a dollar amount to the total transaction for the purpose of tipping Valid format is e lt TipAmt gt Amount lt TipAmt gt where Amount is the value to be added to 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 e lt TaxAmt gt Amount lt TaxAmt gt where Amount is the value to be added to the total transaction in DDDD CC format Sequence Number optional Identifies the payment order with a repeat sale or installment transaction For example payment 1 of 4 Valid format is e lt SequenceNum gt SequenceNum lt SequenceNum gt where SequenceNum is any positive integer less than or equal to the Page 10 of 103 SureGate SureGate API Documentation 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 e lt SequenceCoun
29. Capture and CaptureAll transactions R Required except for CaptureAll transactions R1 Required on Force and Capture transactions RS Required on all swiped card transactions Parameter Opt Req Description Fa cl UserName User name assigned in the payment server The user must have an ens E Password Rs Password associated with the user name provided TransType Identifies the type of check 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 e Capture settle a single transaction in the current batch e 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 Uniquely identifies the bank holding funds Also called routing number AccountNum R Uniquely identifies the check owner s bank account Amount R o e Total transaction value in DDDD CC format MICR RS Magnetic Ink Check Read
30. Documentation SureGate item In effect a transaction will only be treated as a fuel transaction if at least one of the items within lt Items gt is designated as category Fuel Input Parameters O Optional R Required R Required except in Capture and CaptureAll transactions R Required except for CaptureAll transactions R1 Required on Force and Capture transactions RS Required on all swiped card transactions Parameter Opt Req Description Name UserName Password TransType User name assigned in the payment server The user must have an appropriate level of access in order to utilize the web service Password associated with the user name provided es Identifies the type of debit card transaction being made Valid values are e Sale make a purchase using a debit card e Return credits the card holder s account BuyPass fuel transactions only e Auth authorize the amount on a debit card e Force force an Auth transaction in to the current batch PostAuth Terminal based processors only e Capture settle a single transaction in the current batch Terminal based processors and host based processors supporting the batch release feature only e CaptureAll settle all transactions in the current batch Global Canadian Debit only e 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
31. ProcessSignature Service Location For SOAP connections https secure suregate net ws transact asmx op ProcessSignature For standard HTTPS connections https secure suregate net ws transact asmx ProcessSignature Description 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 Developer Notes It is possible to send a receipt image file through the ProcessSignature web service operation from a client side application in order to associate it with a transaction Due to the overall complexity of creating a receipt image with ProcessSignature here is a general list of steps your client side application must perform in order to send images to the payment server 1 Get image file from hardware device etc and convert image to TIFF image format if it isn t already in that format 2 Perform an LZW compression on the image data to reduce the file size the payment server will only accept image data up to 25KB Note LZW compression decompresses and decompresses without information loss achieving compression ratios up to 5 1 It may be somewhat slower to compress and decompress than the PackBits scheme 3 Compress the file itself with Zip compression to reduce
32. ResultTXT Do NOT use this when programmatically validating a Page 93 of 103 SureGate API GetCommercialCard GetCVResult GetCVResult TXT GetStreetMatchTXT up to 25 characters A string value representing a Boolean value A string value up to 1 character A string value up to 25 characters A string value up to 25 characters Documentation formatted response message when address verification is performed Returns the payment processor s response indicator that specifies if the card is a commercial card Returns the card verification result code from the payment processor Returns the formatted response message when card verification is performed Returns the formatted response message when street number address verification SureGate transaction s AVS result please see GetAVSResult field 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 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
33. SureGate API Documentation Implementation Guide SOAP Implementation Name Value Pairs Implementation Useful Tips Transaction Processing Web Services ProcessCreditCard ProcessDebitCard ProcessCheck ProcessEBTCard ProcessGiftCard ProcessSignature ProcessCheck Recurring Billing ProcessCreditCard Recurring Billing Custom Fields Documentation Recurring Billing Web Services ManageCustomer ManageCreditCardInfo ManageCheckInfo ManageContract ManageContractAddDaysToNextBillDt ReportingWebServices AddCustomField GetCardTrx GetCardTrxSummary GetCheckTrx GetOpenBatchSummary Response Field Definitions Reporting Services Response Processing Service Responses Result Response Field Definitions ExtData Field Definitions AVS Response Field Definitions CV Response Field Definitions Support Downloads Technical Support Page 1 of 103 SureGate API Documentation Download PHP Sample code Download NET Sample Code Page 2 of 103 SureGate SureGate API Documentation SOAP Implementation top 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 meth
34. 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 lt ContractKey gt lt ContractKey gt tags when a new contract is added to the system PaymentInfoKey Information passed in the PaymentinfoKey parameter will vary PaymentType depending on the PaymentType value passed e Ifa PaymentType of CC credit card is passed send the CardInfoKey value If a PaymentType of CK check is passed send the CheckinfoKey value Identifies the type of payment method used Valid values are e CC Credit card e CK Check ACH Note This parameter is case sensitive Lower case entries will result in an error 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 Customer contact first name Customer contact last name Customer contact job or professional title For example Business CustomerName Department Unit Manager or Dr Customer contact department For example Sales or Operations Customer ID 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
35. action The expected behavior of this transaction type is defined by the type of the payment processor the merchant account is configured for See Developer Notes for additional information Developer Notes Invalid Characters Some parameters and XML tags contain data that will automatically remove invalid characters from the user entered data These parameters and tags include e MagData e NameOnCard e InvNum e RegisterNum Page 16 of 103 SureGate SureGate API Documentation Reversal Transactions Reversal is only for the following payment processors TSYS GlobalEast and First Data North CES All reversals must be processed as card present transactions e For TSYS The 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 TSYS requires the debit card number and expiration date along with the original sale PNREF number to process reversals e For First Data North The supported industries are retail and restaurant This is also supported for retail and restaurant and reversals must be processed within 24 hours of the original credit card transaction e For Global East This is supported for all debit card issuers It is supported retail and restaurant industries It is required that the reversal be processed within the open batch time period It restores debit bank account funds immediately
36. actions Returns the transaction count of all Return Credit transactions Returns the dollar amount of all Sale transactions Page 90 of 103 SureGate API Documentation representing a transaction count of signed 32 bit all Sale transactions integer Settle_Date_DT A string value Returns the date representing a date on which the and time transaction is settled Settle Flag CH A string value Returns if the representing a transaction is settled Boolean value or not StateCode_CH A string value up to Returns the state pM iwona one O Street_CH A string value upto Returns the billing 25 characters street address of the credit card SureCharge Amt_MN A string value Returns the sure representing a charge amount of a signed 64 bit real transaction number Tip_Amt_MN A string value Returns the tip representing a amount of a signed 64 bit real transaction number Total_Amt_MN A string value Returns the total representing a amount of a signed 64 bit real transaction number Trans_Type_ID A string value up to Returns the 20 characters transaction type e g Sale Credit Transport_Method A string Returns the Only for use with Dial up transactions Transportation Method Transport_EndPoint Astring Returns the Only for use with Dial up transactions Transportation s Ending Destination TransitNum_VC A string value up to Returns the transit This field will be masked out with asterisk 200 characters routing number characte
37. ainst the XSL schema if it passes then that XSL will be used for transformation A sample predefined XSL is included with this Web Services e https lt PMN assigned host name gt 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 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 e g a value of l 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 Extended data in XML format Valid values are e lt IMAGE_TYPE gt NO_IMAGE lt IMAGE_TYPE gt Will only return transaction data thatdoes not include image data to include signature data and check images Page 64 of 103 SureGate SureGate API Documentation lt IMAGE_TYPE gt ONLY_IMAGE lt IMAGE_TYPE gt Will only return transaction data that includes image data to includ
38. are a few idiosyncrasies 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 Asa 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 lf afield 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 labeld For standard HTTPS
39. assigned by the payment server at the time the transaction is created SureChargeAmt CashBackAmt ExtData A string that uniquely identifies the register terminal or computer on The amount in DDDD CC format charged by a merchant in exchange for The amount in DDDD CC format requested by the card holder in cash 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 The following information may be added via the ExtData parameter 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 e lt TimeOut gt TimeOut lt TimeOut gt 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 R The encrypted PIN block returned by the PIN pad Note The transaction will fail if an unencrypted PIN is used Note This information is not required for PIN less debit transactions See Developer Notes for additional information on pin less debit transactions e lt TrainingMode gt T lt TrainingMode gt where T true indicates that Page 19 of 103
40. ate 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 For additional information on compression and encoding see the Developer Notes 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 Valid entries are e 1 true transaction was approved e 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 E authorization when transactions are being settled 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 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 e lt TrainingMode gt T lt TrainingMode gt where T true indicate
41. cluded 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 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 Valid entries are Unused blank returns all transactions 1 returns only settled transactions O 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 Matching is done using wild cards e g test will match test 1test and 1test234 If provided only transactions that were settled on the same date will InvoicelD 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 SettleDt Page 73 of 103 SureGate SureGate API Documentation Oooo O beneame SSS y O TransformType Indicates how the result set should be formatted Valid entries are e XML outputs a plain XML string e XSL uses XSL to format
42. ction that was returned by the payment processor Capture A string value Returns the dollar This value will always return 0 representing a amount of all signed 64 bit real Capture transactions number Capture_Cnt A string value Returns the This value will always return 0 representing a transaction count signed 32 bit of all Capture integer transactions Card_Info_Key A string value Returns the primary representing a key of the CC_Info_T signed 32 bit table in the database integer Cash_Back_Amt_MN A string value Returns the cash representing a back amount for signed 64 bit real a debit or EBT number transaction CheckNum_CH A string value up to Returns the check 10 characters number Cnt A string value Returns the representing a transaction count of signed 32 bit all transactions integer Page 86 of 103 SureGate API Documentation CustomerID A string value up to Returns the 50 characters Customer ID of a customer to which the transaction belongs to CV_Resp_CH A string value up to Returns the card 1 character verification result code from the payment processor CV_Resp_Txt_VC A string value up to Returns the 25 characters formatted response message when card verification is performed Date_DT A string value Returns the date representing a date on which the and time transaction is first made Exp_CH A string value up to Returns the credit 10 characters card expiration date ForceCapture A strin
43. d Characters Some parameters and XML tags contain data that will automatically remove invalid characters from the user entered data These parameters and tags include e MagData e NameOnCard e InvNum e Zip e Street e ExtData lt CustCode gt e Extdata lt RegisterNum gt Page 7 of 103 SureGate SureGate API Documentation e ExtData lt City gt e ExtData lt BillToState gt e ExtData lt PONum gt Reversal Transactions Reversal is only supported for payment processors TSYS Global and First Data North CES e For TSYS 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 e For First Data North Supported industries are retail and restaurant Reversals must be processed within 24 hours of the original credit card transaction e For Global Supported for all credit card issuers for transactions made within all industries Reversals must be processed within the open batch time period Completed reversals will act as a void host Input Parameters O Optional R Required R Required except in Capture and CaptureAll transactions R Required except for CaptureAll transactions R1 Required on Force and Capture transactions RS Required on all swiped card transactions Parameter Opt Req Description ame e R UserName User name assigned in the payment server The use
44. d in the customer record EmailMerchant Indicates whether the system will send an email to the merchant after successfully processing a scheduled payment Valid values are e TRUE Email is sent to the merchant after successful payment e 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 Valid values are e TRUE Email is sent to the customer after failed payment e 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 e TRUE Email is sent to the merchant after failed payment e 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 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 n
45. d to identify the register where the transaction took place If used only transactions made with the matching register number will be returned NameOnCard 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 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 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 IAL 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 ExcludeVoid The ExcludeVoid parameter allows you to exclude voided transactions from the result s
46. e signature data and check images lt IMAGE_TYPE gt ALL lt IMAGE_TYPE gt will return transaction with or without image data lt CustomerlD gt CustomerlD lt CustomerlD gt specifies the customer ID value to search by Matching is done using wild cards e g test will match test 1test and 1test234 lt Amount gt Amount lt Amount gt specifies the amount value of the transactions being searched for In DDDDDD CC format lt RegisterNum gt RegisterNum lt RegisterNum gt apecifies the register number originally passed with the transaction to search by Page 65 of 103 SureGate SureGate API Documentation GetCardTrxSummary Service Location For SOAP connections https secure suregate net admin ws trxdetail asmx op GetCardTrxSummary For standard HTTPS connections https secure suregate net admin ws trxdetail asmx GetCardTrxSummary Description 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 Developer Notes Date Formats Dates entered through input parameters are automatically formatted to YYYY MM DDThh mm ss time is in 24 hour format using Pacific Standard Time PST zone Valid entry formats are e MM DD YYYY e YYYY MM DD e YYYY MM DDThh mmi ss Date Q
47. e target transaction ID for the original transaction you wish to void without the use of a PNRef Valid format is e lt Target gt TransactionIidentifierValue lt Target gt where TransactionldentifierValue 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 e lt Force gt T lt Force gt where T true indicates that duplicate transactions are accepted lt Force gt F lt Force gt where F false indicates that duplicate transactions are not accepted Page 11 of 103 SureGate SureGate API Documentation Note Some processors including Concord EFS will not recognize this tag and delete duplicate transactions Register Number optional Unique identifier for a specific register See Developer Notes for invalid character processing Valid format is e lt RegisterNum gt RegisterNum lt RegisterNum gt where RegisterNum is a valid unique identifier assigned to a specific register City Depending on processor used this may be required City name for the card owner s billing address See Developer Notes for invalid character processing Valid format is e lt City gt City lt City gt where City is the card owner s city name Bill To State Depending on processor used this may be required Two character state code for the card owner s bill to address See Develop
48. eOnCheck Check owner s name as it appears on the check errs LP rete setcccenonateinelecerceroeecing emai Cstomercontacreemaladaress OOOO Parone Gustomercontactsphonenumber OOOO i sree customer contactstreeradaress inet o i sree Gustomercontactsreetaderess ine O Page 49 of 103 SureGate SureGate API Documentation Street3 o Customer contact street address line 3 StatelD Customer contact s standard U S postal service two character state code U S customers only Province fo Customer contact s province countries outside the U S only PostCode fo Customer contact s zip or postal code CountrylD Customer contact s three character country code For example USA United States or CAN Canada ExtDate FO Reserved for future use Page 50 of 103 SureGate SureGate API Documentation ManageContract Service Location For SOAP connections https secure suregate net admin ws recurring asmx 0p ManageContract For standard HTTPS connections https secure suregate net admin ws recurring asmx ManageContract Description This service allows the integrator to add update or delete the terms and interval of a recurring billing contract Developer Notes It is very important to understand that this web service is used for storing data and is not for querying previously stored data It is the responsibility of the integrator to store and maintain all returned Info Keys
49. egate net ws transact asmx ProcessEBTCard Description 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 This web service is used whenever a transaction is completed via customer EBT card The processes supported by this web service include e FoodStampSale make a purchase on an EBT cardholder s food stamp account e FoodStampReturn credit to an EBT cardholder s food stamp account e CashBenefitSale make a purchase on an EBT cardholder s cash benefit account e Inquire check the balance on an EBT card e Capture settle a single transaction in the current batch only for terminal based processors e CaptureAll settle all transactions in the current batch only for terminal based processors or host based processors that support a batch release feature e Force Voucher Clear allow a merchant to pass a voucher number which is a reference number on the voucher slip to clear the transaction along with the authorization code obtained via a voice approval This means that you can perform a pin less EBT sale with the authorization code along with the voucher reference number De
50. ent to BuyPass the default value is sent usually terminal ID O1 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 lt Items gt tag in ExtData Fuel purchases are differentiated at the gateway from other purchases by the Fuel designation placed within the lt Category gt tag in Page 17 of 103 SureGate API
51. ent transactions Raw Magnetic Ink Check Reader data line from the check reader Valid format is e lt RawMICR gt RawMICR lt RawMICR gt 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 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 Valid format is e lt InvNum gt nvNum lt InvNum gt 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 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 e lt TrainingMode gt T lt TrainingMode gt where T true indicates that training mode is active and transactions are processed for local loop back testing e lt TrainingMode gt F lt TrainingMode gt where F false indicates that training mode is inactive and transactions should be treated normally Alliance Number optional Check alliance number Valid format is e lt AllianceNum gt AllianceNum lt AllianceNum gt whereAllianceNum is the check s alliance number Accoun
52. eports from customer billing histories to reports that help locate duplicate transactions e 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 e Automate the reconciliation process between the payment server and the point of sale POS system or register Developer Notes Date Formats Dates entered through input parameters are automatically formatted to YYYY MM DDThh mm ss time is in 24 hour format using Pacific Standard Time PST zone Valid entry formats are e MM DD YYYY e YYYY MM DD e YYYY MM DDThh mmi ss Date Query String The query string used to obtain transactions in a date range is constructed as follows Date DT gt BeginDt AND Date DT lt EndDt Date DT is the transaction timestamp Parameters Accepting Multiple Values Some parameters for example PaymentType and TransType will accept multiple values and return results using an either or filter When inputting multiple parameter values use the following format VALUE1 VALUE2 VALUE3 Important When entering any values in parameters accepting multiple entries the values must be enclosed in single quotes to be accepted Values are not case sensitive For example the following values entered in the PaymentType parameter would return result
53. er A string value representing a signed 64 bit real Returns the primary key of the Reseller_T table in the database Returns the transaction processing result e g 0 12 0 for approval 12 for decline Returns the check transaction s processing result Returns an extra formatted response message giving more information about the processed transaction Returns an extra formatted response message giving more information about the processed transaction Returns the text message of either approval or decline for the transaction processing result Returns the dollar amount of all Return Credit transactions Returns the transaction count of all Return Credit transactions Returns the dollar amount of all Sale transactions Page 83 of 103 SureGate SureGate API Documentation a Sale_Cnt A string value Returns the representing a transaction count of signed 32 bit all Sale transactions integer Settle_Date_DT A string value Returns the date representing a date on which the and time transaction is settled Settle Flag CH A string value Returns if the representing a transaction is settled Boolean value or not StateCode_CH A string value up to Returns the state ee ae deo Street_CH A string value upto Returns the billing 25 characters street address of the credit card SureCharge_ Amt_MN A string value Returns the sure representing a charge amount of a signed 64 bit real tran
54. er Notes for invalid character processing Valid format is e lt BillToState gt BillToState lt BillToState gt where BillToState is the two character state code for the card owner s bill to address Customer ID optional Identification number assigned to the customer by the merchant Valid Format is e lt CustomerlD gt CustomerlD lt CustomerlD gt where CustomerID is the customer s assigned customer ID Purchase Order PO Number optional Customer or PO number used with Level II information See Developer Notes for invalid character processing Valid format is e lt PONum gt PONum lt PONum gt 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 optional 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 Valid formats are e lt BillPayment gt T lt BillPayment gt where T true indicates that the transaction is being used to pay a utility bill e lt BillPayment gt F lt BillPayment gt 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
55. er data line This data string includes the TransitNum and AccountNum 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 Page 24 of 103 SureGate SureGate API Documentation NameOnCheck R Check owner s name as it appears on the check See Developer Notes for invalid character processing Note This parameter may be required depending on the merchant s processor setup DL Check owner s driver s license number See Developer Notes for invalid Pong o eee aa SS Check owners Social Security number See Developer Notes for invalid character iA pos f Check owners date of birth See Developer Notes for date formats StateCode Check owner s two character state code See Developer Notes for invalid character processing Note This parameter may be required depending on the merchant s we processor setup CheckType Identifies the type of check used in the transaction Valid values are e Personal e Corporate e Government ExtData The ExtData parameter allows you to pass additional i
56. er processing Valid format is e lt BillToState gt BillToState lt BillToState gt where BillToState is the two character state code for the check owner s bill to address Bill To Postal Code Depending on merchant setup this may be required for TransType Sale or Return Postal Zip code for the check owner s bill to address See Developer Notes for invalid character processing Valid format is e lt BillToPostalCode gt BillToPostalCode lt BillToPostalCode gt where BillToPostalCode is the street name for the check owner s bill to address Bill To Country optional Country name for the check owners bill to address See Developer Notes for invalid character processing Valid format is e lt BillToCountry gt BillToCountry lt BillToCountry gt whereBillToCountry is the country name for the check owner s bill to address Customer ID optional Identification number assigned to the customer by the merchant Valid Format is e lt CustomerlD gt CustomerlD lt CustomerlD gt whereCustomer D is the customer s assigned customer ID Card Type optional For use with image uploads specific to the processor RDM_ITMS Valid format is e lt CardType gt IMAGE lt CardType gt Page 27 of 103 SureGate SureGate API Documentation ProcessEBTCard Service Location For SOAP connections https secure suregate net ws transact asmx op ProcessEBTCard For standard HTTPS connections https secure sur
57. et Valid entries are e TRUE voided transactions are excluded from summary information FALSE voided transactions are included from summary information Page 67 of 103 SureGate SureGate API Documentation User SettleFlag 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 The SettleFlag parameter allows you to choose whether settled or unsettled transactions are included in the results Valid entries are e Unused blank returns summary information for settled and unsettled transactions 1 returns only summary information for settled transactions O return only summary information for transactions that are not yet settled The settlement message is an ID or message returned from the host upon settlement of a transaction If provided only the transaction that SettleMsg exactly matches the SettleMsg provided will be returned If provided only transactions that were settled on the same date will be included in the results e XML outputs a plain XML string e 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 RowDeli
58. f provided only those transactions created by the matching User will be included Matching is done using wild cards e g test will match test 1test and 1test234 The invoice ID that was included in the original transaction If provided only those transactions with matching invoiceld will be included Matching is done using wild cards e g test will match test 1test and 1test234 The SettleFlag parameter allows you to choose whether settled or unsettled transactions are included in the results Valid entries are e Unused blank returns all transactions Page 63 of 103 SureGate SureGate API Documentation e T returns only settled transactions e Q returns only transactions that are not yet settled SettleMsg ka The settlement ID or message returned from the host TransformType The type of format to transform the data into Leave the field blank to default to XML e XM will output the plain XML string e XSL will use XSL to transform the XML output e DELIM uses ColDelim and RowDelim to format the output Xsl This field is used only if the TransformType is XSL 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 ag
59. f the MagData is CardNum ExpDate followed by the service code and checksum For example 36438999960016 05121015432112345678 Total transaction amount in DDDD CC format Note This amount includes the CashBackAmt and SureChargeAmt 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 R1 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 Page 33 of 103 SureGate SureGate API Documentation 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 The following information may be added via the ExtData parameter 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 e lt TrainingMode gt T lt TrainingMode gt where T true indicates that training mode is active and transactions are processed for local loop back testing lt TrainingMode gt F lt TrainingMode gt where F false indicates that training mode is inactive and transactions should be treated normally Force
60. 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 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 This value will typically be Match for correctly matching the street address or No Match for an incorrect street address Page 94 of 103 SureGate SureGate API Documentation is performed GetZipMatchTXT A string value Returns the This value will typically be Match for correctly matching up to 25 formatted the zip code or No Match for an incorrect zip code characters response message when zip code address verification is performed HostCode A string value Typically This value may not be returned for all payment processors up to 30 returns a characters number which uniquely identifies the transaction in the payment processor Message A string value Returns a This value will typically be APPROVAL for approved up to 50 formatted transactions or an error message for declined characters response transactions Do NOT use this when programmatically message validating a transaction s result please see Result field concerning below the processed transaction Messagel A string value Returns The Payment Server will only populate th
61. for later use When calling this service with a TransType value of UPDATE it is also important to note that any values that are left NULL will overwrite existing data with a NULL value If the desired effect is to simply update the next bill date call ManageContractAddDaysToNextBillDt Input Parameters O Optional R Required R Required for TransType UPDATE or DELETE RS Required for TransType ADD or UPDATE ona 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 TR Password associated with the user name provided TransType Indicates whether the contract is being added updated or deleted Valid entries are e ADD e UPDATE e 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 Page 51 of 103 SureGate SureGate API Documentation menu Display a list of customers by entering search criteria The CustomerKey appears in the Key column ContractKey R
62. g value Returns the dollar representing a amount of all signed 64 bit real ForceCapture number ForceAuth transactions ForceCapture_Cnt A string value Returns the representing a transaction count signed 32 bit of all ForceCapture integer ForceAuth transactions Host_Date_CH A string value up to Returns the 10 characters payment processor s date on which the transaction is ERROR A string value up to Returns an 200 characters error message when a problem occurs during the transaction processing performed Page 87 of 103 SureGate API Documentation Host_Ref_Num_CH Astring value upto Returns a number 30 characters which uniquely identifies the transaction for the payment processor Host_Time_CH A string value up to Returns the 10 characters payment processor s time at which the transaction was performed Invoice_ID A string value up to Returns the 100 characters transaction s Invoice number IP_VC A string value upto Returns the IP 15 characters address of the client machine from which the transaction was processed Last_Update_DT A string value Returns the date and representing a date time on which the and time transaction is last modified Manual A string value Returns the card was representing a swiped or not Boolean value Merchant_Key A string value Returns a number representing a which uniquely signed 32 bit identifies a integer merchant Name_on_Card_VC Astring value upto
63. gned 64 bit real of all RepeatSale number Recurring Billing Installment transactions RepeatSale_Cnt A string value Returns the representing a transaction count signed 32 bit of all RepeatSale integer Recurring Billing Installment transactions Reseller_Key A string value Returns the primary representing a key of the Reseller_T Page 89 of 103 SureGate API Documentation signed 32 bit table in the database integer Result_CH Result_Msg_ VC Result_Msg1_ VC Result_Msg2_ VC Result_Txt_VC Return_Cnt Sale Sale_Cnt A string value Returns the A string value up to 50 characters A string value up to 50 characters A string value up to 50 characters A string value up to 50 characters A string value up to 150 characters A string value representing a signed 64 bit real number A string value representing a signed 32 bit integer A string value representing a signed 64 bit real number Returns the transaction processing result e g 0 12 0 for approval 12 for decline Returns the check transaction s processing result Returns an extra formatted response message giving more information about the processed transaction Returns an extra formatted response message giving more information about the processed transaction Returns the text message of either approval or decline for the transaction processing result Returns the dollar amount of all Return Credit trans
64. he web service Password associated with the user name provided 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 lt CclnfoKey gt lt CclnfoKey gt tags or can be found in the result set from the InfoCustomer web service CheckinfoKey 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 Reserved for future use eT 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 es ExtData Page 40 of 103 SureGate API Documentation Page 41 of 103 SureGate API Documentation Custom Fields Documentation Top To pass in custom field data to any transactional web service please observe the following field format The following example assumes that the integrator has stored 2 custom fields one named SampleFieldName1 and the other named SampleFieldName2 lt CustomFields gt lt SampleFieldName1 gt Sample String Data lt SampleFieldName1 gt lt SampleFieldName2 gt 8675309 lt SampleFieldName2 gt lt
65. hone 877 298 0455 Email info suregate net NOTE Please ensure you provide your merchant ID Business name when contacting us Page 103 of 103
66. 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 Developer Notes Date Formats Dates entered through input parameters are automatically formatted to YYYY MM DDThh mm ss time is in 24 hour format using Pacific Standard Time PST zone Valid entry formats are e MM DD YYYY e YYYY MM DD e YYYY MM DDThh mmiss Date Query String The query string used to obtain transactions in a date range is constructed as follows Date DT gt BeginDt AND Date DT lt EndDt Date DT is the transaction timestamp Parameters Accepting Multiple Values Some parameters for example PaymentType and TransType will accept multiple values and return results using an either or filter When inputting multiple parameter values use the following format VALUE1 VALUE2 VALUE3 Important When entering any values in parameters accepting multiple entries the values must be enclosed in single quotes to be accepted Values are not case sensitive For example the following values entered in the PaymentType
67. is field when up to 50 an extra there is applicable information from the payment characters formatted processor to return response message giving more information about the processed transaction Page 95 of 103 SureGate API PNRef RespMSG A string value up to 50 characters A string value representing a signed 32 bit integer A string value up to 50 characters A string value representing a signed 32 bit integer Documentation Returns an extra formatted response message giving more information about the processed transaction Returns a number which uniquely identifies the transaction in the payment gateway Returns the response message concerning the processed transaction Returns the transaction result code from the payment gateway which signifies the result of the transaction i e approved decline etc SureGate The Payment Server will only populate this field when there is applicable information from the payment processor to return This value is typically either Approved or Declined Do NOT use this when programmatically validating a transaction s result please see Result field below 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 Fields Definitions section for a full list of result values and descriptions Page 96 of 103
68. it card number used to uniquely identify the card owner s account Credit card date of expiration in MMYY format MagData Track data encoded in the magnetic stripe of a credit card The data will follow the following format B51496122222222294FDCS TEST CHECK CARD 12041011234567 440 5149612222222229 12041011234567440 This parameter must contain the full magnetic read in order to be classified as a card present transaction Note This input is required for processing swiped card present transactions Please ensure you have parsed out the Card Number and the Expire date from the Track data Refer to sample in useful tips NameOnCard Card owner s name as it appears on the card See Developer Notes for invalid character processing Note This parameter may be required depending on the merchant s processor setup 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 See Developer Notes for invalid character processing PNRef R 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 You should save this identifier in your system as it is important for other functions Void Return etc Zip Card owner s billing address five digit postal zip code See Developer Notes
69. k of and store these keys An unlimited number of checking account profiles can be stored for any given customer Input Parameters O Optional R Required R Required for TransType values of UPDATE and DELETE Parameter Opt Req Description a ae UserName User name assigned in the payment server The user must have an ee appropriate level of access within the system in order to utilize the web service Password RO Password associated with the user name provided 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 TransType Indicates whether the payment type is being added updated or deleted Valid entries are e ADD e UPDATE e 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 Page 48 of 103 SureGate SureGate API Documentation eppearsinthekey column O O O O O OSSOS O ChecklnfoKey R Numerical key value assigned to the payment method when it was added Se T emam en oneee eena CheckType Identifies the type of check as a personal or business check Valid
70. l parameters available through ExtData for this service Page 77 of 103 SureGate API Documentation SureGate Reporting TrxDetail asmx top The following response fields may be part of the return value for web services using transact asmx operations These web services include Applicable Web Services e GetCardTrx e GetCardTrxSummary e GetCheckTrx e GetOpenBatchSummary Response Field Definitions Response Field Data Type Value Description Account_Type_CH AccountNum_VC Acct_Num_CH Approval_Code_CH Auth_Amt_MN Authorization A string value up to 10 characters A string value up to 200 characters A string value up to 200 characters A string value representing a signed 64 bit real number A string value up to 50 characters A string value representing a signed 64 bit real number A string value representing a signed 64 bit real Returns the card type of the transaction e g VISA Diners EBT Returns the check This field will be masked out with asterisk account number characters except for the last 4 digits if the System Security Level of the user is set to 1 Returns credit card This field will be masked out with asterisk number characters except for the last 4 digits if the System Security Level of the user is set to 1 Returns the check s total amount Returns the response code from the payment processor Returns the authorized amount of a card transacti
71. lid formats are e lt EntryMode gt UNKNOWN lt EntryMode gt where unknown indicates that the mode of entry is unknown lt EntryMode gt MANUAL lt EntryMode gt where manual indicates that the payment values were manually entered lt EntryMode gt MagneticStripe lt EntryMode gt where MagneticStripe indicates that the payment values were entered via magnetic stripe card reader swiped card lt EntryMode gt ICC lt EntryMode gt where ICC indicates that the mode of entry is Instant Card Clearing lt EntryMode gt PROXIMITY lt EntryMode gt 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 Valid formats are e lt Phase gt Confirm lt Phase gt where Confirm indicates that the batch is ready to settle e lt Phase gt Submit lt Phase gt where Submit indicates that the batch has Page 13 of 103 SureGate SureGate API Documentation been submitted to the payment processor e lt Phase gt None lt Phase gt 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 IAS Fields specific to First Data North IIAS Indicator optional Identifies whether the current transaction was authorized for submission by an aut
72. m and IncludeHeader parameters This field is used only if the TransformType is XSL 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 ColDelim 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 e g a value of would start each row with IncludeHeader O This field is used only if the TransformType is DELIM If TRUE then field that XSL will be used for transformation This field is used only if the TransformType is DELIM This defines the string that separates each column TransformType B Indicates how the result set should be formatted Valid entries are Page 68 of 103 SureGate SureGate API Documentation 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
73. m 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 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 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 The result indicates whether a transaction was approved Result 0 or declined Result 0 Valid entries are e Unused blank re
74. nal R Required R Required except in Capture and CaptureAll transactions R Required except for CaptureAll transactions R1 Required on Force and Capture transactions RS Required on all swiped card transactions Parameter Opt Req Description Name UserName User name assigned in the payment server The user must have an appropriate level of access in order to utilize the web service Page 32 of 103 SureGate SureGate API Documentation TransType Password associated with the user name provided i Identifies the type of gift card transaction being made Valid values are Redeem make a purchase ona 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 e Force place a transaction not processed through the payment server into the current batch ForceAuth Terminal based processors only e Capture settle a single transaction in the current batch only for terminal based processors Processors supporting the batch release feature only e CaptureAll settle all transactions in the current batch Bo so Gift card number used to uniquely identify the owner s account Gift card date of expiration in MMYY format Data located the magnetic strip on the back of the card The format o
75. ned 64 bit real number This field is the unique transaction identifier also called PNRef of the Payment Server Use its value when Returns the primary key of the TRX_Check_T table in the database Returns the primary key of the TRX_Header_T table in the database submitting transactions based on a previous transaction i e Voids through the Transact asmx Web Service Returns the primary key of the TRX_Settle_T table in the database Returns the transaction s settlement message Returns the credit card type e g VISA MASTERCARD Returns the username under which the transactions were made Returns the transaction is voided or not Returns the billing zip code of the credit card Returns the authorized amount of a card transaction Returns the dollar amount of all Authorization PreAuth transactions Page 85of 103 SureGate API Documentation Authorization_Cnt A string value Returns the representing a transaction count signed 32 bit of all Authorization integer PreAuth transactions AVS_Resp_CH A string value up to Returns the address 1 character verification result code from the payment processor AVS_Resp_Txt_VC A string value up to Returns the 25 characters formatted response message when address verification is performed Batch_Number A string value upto Returns the batch Not all payment processors support 10 characters number for the returning this data element transa
76. nformation 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 The following information may be added via the ExtData parameter Time out optional Processor time out value in seconds The default value for the parameter is 30 seconds Valid format is e lt TimeOut gt TimeOut lt TimeOut gt where TimeOut is the processor time out value in seconds PNRef required for TransType Return Void Force or Capture 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 Valid format is e lt PNRef gt PNRef lt PNRef gt where PNRef is the valid payment reference number assigned to the transaction that is to be returned voided forced or captured Phone optional Check owner s phone number See Developer Notes for invalid character processing Valid format is e lt Phone gt Phone lt Phone gt where Phone is the check owner s phone number Email Address optional Check owner s email address See Developer Notes for invalid character processing Valid format is e lt Email gt Email lt Email gt where Email is the check owner s email Page 25 of 103 SureGate SureGate API Documentation address Raw MICR Required for check consumer pres
77. ng with the request data Example Before SstrTrack2 5454545454545454 14151015432112345678 Example After SstrTrack2 1015432112345678 PNRef Certain functions such as Return Void etc require a transaction Id of a previously approved transaction The PNRef parameter you send to the gateway MUST contain the transaction id of the approved transaction Permissions Live Test account Make sure your account is in TEST mode when you are integrating your account Refer to SureGate Customer service info at the end of this document The userid pwd combination is case sensitive and make sure no leading trailing spaces Once you are satisfied that you are properly integrated into the gateway contact SureGate customer service to enable your account in LIVE mode 404 Errors If you are following the API documentation and or using the code samples and are getting a 404 error code this could mean the following e You are NOT passing ALL required parameters Even if a parameter does not apply and it is NULL Please ensure you specify it e g amp parameter value or amp parameter null e You are passing improper login credentials or your account is not properly configured If your account is not configured please contact support for assistance Page 5of 103 SureGate API Documentation VScom e You specified an incorrect secure URL to the Suregate gateway Please double check it matches that specified in the API Page 6 of 103
78. ntract comes due in DD CCCC D TaxAmt Additional tax amount applied to the BillAmt each time the contract re ae 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 MMDDYYYY 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 MMDDYYYY format The end date must be greater than the start date If left blank the contract will be checked every day until manually cancelled or suspended by the system due to lack of payment NextBillDt Identifies the next time the contract will come due in MM DD YYYY Page 53 of 103 SureGate SureGate API Documentation 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 Billinglnterval to compute the next bill date for a contract Valid values are DAY WEEK MONTH YEAR Note The system will automatically account
79. o longer used poe es ExtData Reserved for future use Page 55 of 103 SureGate SureGate API Documentation ManageContractAddDaysToNextBillDt Service Location For SOAP connections https secure suregate net admin ws recurring asmx 0p ManageContractAddDaysToNextBillDt For standard HTTPS connections https secure suregate net admin ws recurring asmx ManageContractAddDaysToNextBillDt Description This web service allows the integrator to update the NextBillDate in the event that a payment was declined and a contract suspended Developer Notes Call this service in place of ManageContract if the NextBillDate is the only value being updated to minimize the possibility of overwriting data Input Parameters O Optional R Required opie 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 RO 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 op
80. o substantiation database For the indicator to be recognized the merchant must be set up for retail and the card type must be Visa or MasterCard Valid formats are e lt IIAS_Indicator gt T lt IIAS_Indicator gt where T true indicates that the transaction was authorized lt IIAS_Indicator gt F lt IIAS_Indicator gt where F true indicates that the transaction was not authorized lt IIAS_Indicator gt lt IIAS_Indicator gt where a blank value indicates that the transaction not was authorized Note False or blank indicators will disqualify the transaction for IIAS and any other IIAS fields will be ignored Partial Indicator optional Indicates whether a transaction is partially approved by the host Valid formats are e lt Partial_Indicator gt T lt Partiallndicator gt where T true indicates that the host may process the transaction as a partial authorization for available funds lt Partial_Indicator gt F lt Partial_Indicator gt where F indicates that the transaction does not qualify for partial approval lt Partial_Indicator gt lt Partial_Indicator gt where a blank value indicates that the transaction does not qualify for partial approval Note The Partial Indicator will return three fields in the response as received from the host First Data North e Requested Amount Decimal dollar amount as requested for authorization Approved Amount Decimal dollar amount as approved by the host Balanced Amount Decimal dolla
81. od 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 As such the endpoint URL s included in the WSDL file generated by the web reference to the service will be set to http by default 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 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 Page 3of 103 SureGate SureGate API Documentation Name Value Pairs Implementation top The Name Value Pairs implementation relies on the NET framework s built in HTTP to SOAP translation layer As a result there
82. of Page 79 of 103 SureGate API Documentation signed 32 bit all transactions integer CustomerID A string value up to Returns the 50 characters Customer ID of a customer to which the transaction belongs to CV_Resp_CH A string value up to Returns the card 1 character verification result code from the payment processor CV_Resp_Txt_VC A string value up to Returns the 25 characters formatted response message when card verification is performed Date_DT A string value Returns the date representing a date on which the and time transaction is first made Exp_CH A string value up to Returns the credit 10 characters card expiration date ForceCapture A string value Returns the dollar representing a amount of all signed 64 bit real ForceCapture number ForceAuth transactions ForceCapture_Cnt A string value Returns the representing a transaction count signed 32 bit of all ForceCapture integer ForceAuth transactions Host_Date_CH A string value up to Returns the 10 characters payment processor s ERROR A string value up to Returns an 200 characters error message when a problem occurs during the transaction processing date on which Page 80 of 103 SureGate API Documentation the transaction is Oo O ee Host_Ref_Num_CH A string value upto Returns a number 30 characters which uniquely identifies the transaction for the payment processor Host_Time_CH A string value up to Returns the 1
83. on Returns the dollar amount of all Authorization Page 78 of 103 SureGate SureGate API Documentation number PreAuth OOOO ee ees ee Authorization_Cnt A string value Returns the representing a transaction count signed 32 bit of all Authorization integer PreAuth transactions AVS_Resp_CH A string value up to Returns the address 1 character verification result code from the payment processor AVS_Resp_Txt_VC A string value up to Returns the 25 characters formatted response message when address verification is performed Batch_Number A string value upto Returns the batch Not all payment processors support 10 characters number for the returning this data element transaction that was returned by the payment processor Capture A string value Returns the dollar This value will always return 0 representing a amount of all signed 64 bit real Capture transactions number Capture_Cnt A string value Returns the This value will always return 0 representing a transaction count signed 32 bit of all Capture integer transactions Card_Info_Key A string value Returns the primary representing a key of the CC_Info_T signed 32 bit table in the database integer Cash_Back_Amt_MN Astring value Returns the cash representing a back amount for signed 64 bit real a debit or EBT number transaction CheckNum_CH A string value up to Returns the check Cnt A string value Returns the aa representing a transaction count
84. or example 36438999960016 05121015432112345678 Card owner s name as it appears on the card See Developer Notes for invalid character processing Note This parameter may be required depending on the merchant s processor setup Note Invalid characters will be removed from this entry See Developer Notes for invalid character processing Page 29 of 103 SureGate SureGate API Documentation Amount Total transaction amount in DDDD CC format ae bi 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 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 The encrypted PIN block returned by the PIN pad Note The transaction will fail if an unencrypted PIN is used A string that uniquely identifies the register terminal or computer on The amount in DDDD CC format charged by a merchant in exchange for The amount in DDDD CC format requested by the card holder in cash 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 The following information may be added via the ExtData
85. p GetOpenBatchSummary For standard HTTPS connections https secure suregate net admin ws trxdetail asmx GetOpenBatchSummary Description This web service retrieves a payment type transaction summary of the current open batch for a specified merchant Developer Notes Date Formats Dates entered through input parameters are automatically formatted to YYYY MM DDThh mm ss time is in 24 hour format using Pacific Standard Time PST zone Valid entry formats are e MM DD YYYY e YYYY MM DD e YYYY MM DDThh mmi ss Date Query String The query string used to obtain transactions in a date range is constructed as follows Date DT gt BeginDt AND Date DT lt EndDt Date DT is the transaction timestamp Input Parameters O Optional R Required opie UserName User name assigned in the payment server The user must have an appropriate level of access within the system in order to return records a Password associated with the user name provided 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 RO Identifies the beginning date range for a group of transactions Endt JR Identifies the ending date range for a group of transactions Page 76 of 103 SureGate API Documentation erat ExtData Currently there are no additiona
86. parameter would return results with either the PayReceipt or Settle payment types PAYRECEIPT SETTLE Input Parameters O Optional R Required R Required unless a value of PNRef is provided opt Rea UserName Rs User name assigned in the payment server The user must have Page 70 of 103 SureGate SureGate API Documentation an appropriate level of access within the system in order to return records Password dT RR Password associated with the user name provided 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 Note If a PNRef is provided all other query fields will be ignored Identifies the beginning date range for a group of transactions Identifies the ending date range for a group of transactions 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 Valid entries are ACH Automated Clearing House ECHECK Electronic check
87. r amount remaining on the balance on the account Optional Amounts All optional amounts should include the decimal They are all 13 character fields with explicit decimal The total of the sub amounts must match to the total authorization amount of the transaction Optional subtotal amount for qualified medical expenses over the counter medical items This applies to Visa transactions only Page 14 of 103 SureGate SureGate API Documentation lt QHP_Amount gt Value lt QHP_Amount gt lt RX_Amount gt Value lt RX_Amount gt where Value is the optional prescription RX subtotal in DDDD CC format lt Vision_Amount gt Value lt Vision_Amount gt where Value is the optional Vision Optical subtotal in DDDD CC format lt Dental_Amount gt Value lt Dental_Amount gt where Value is the optional dental subtotal in DDDD CC format lt Clinical_ Amount gt Value lt Clinical_ Amount gt where Value is the optional clinical subtotal in DDDD CC format If a partial reversal is required by an integrator certain fields must be passed The TransType passed with this request is the Reversal You must also pass the PNRef and IIAS_Indicator T The response will have the Partial_Reversal_Flag field set to T true anda Total_Amount field will show what amount is to be settled after requesting the partial reversal transaction Full reversals are also supported To request a full reversal the IIAS_Indicator must be set to T true
88. r must have an appropriate level of access within the system in order to utilize the web service Password R o 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 e Adjustment used to modify an existing tip amount for an original sale To call the service Page 8of 103 SureGate SureGate API Documentation Terminal based processors only e Capture settle a single transaction in the current batch Terminal based processors and host based processors supporting batch release feature only e CaptureAll settle all transactions in the current batch e Reversal perform a manual full reversal on a credit card or repeat sale within 24 hours of the original transaction See Developer Notes for additional details on support for reversals Cred
89. rs except for the last 4 digits if the System Security Level of the user is set to 1 Page 91 of 103 SureGate API Documentation TRX_Check_Key TRX_HD_Key TRX_Settle_Key TRX_Settle_Msg VC Type_CH User_Name_VC Void_Flag_CH Zip CH representing a signed 32 bit integer A string value representing a signed 32 bit integer A string value representing a signed 32 bit integer A string value representing a signed 32 bit integer A string value up to 25 characters A string value up to 10 characters A string value up to 25 characters A string value representing a Boolean value A string value up to 10 characters primary key of the TRX_Card_T table in the database Returns the primary key of the TRX_Check_T table in the database Returns the This field is the unique transaction identifier also called PNRef of the Payment Server Use its value when primary key of the TRX_Header_T table in the database submitting transactions based on a previous transaction i e Voids through the Transact asmx Web Service Returns the primary key of the TRX_Settle_T table in the database Returns the transaction s settlement message Returns the credit card type e g VISA MASTERCARD Returns the username under which the transactions were made Returns the transaction is voided or not Returns the billing zip code of the credit card Page 92 of 103 SureGate SureGate API Doc
90. s that training mode is active and transactions are processed for local loop back testing lt TrainingMode gt F lt TrainingMode gt where F false indicates Page 37 of 103 SureGate API Documentation Wercat that training mode is inactive and transactions should be treated normally Page 38 of 103 SureGate SureGate API Documentation ProcessCheck Recurring Billing Top Service Location For SOAP connections https secure suregate net admin ws recurring asmx op ProcessCheck For standard HTTPS connections https secure suregate net admin ws recurring asmx ProcessCheck Description This web service allows an integrator to process a Check Transaction against a checking account that has been ManageCheckinfo This web service is for processing Sale transactions only Developer Notes See Recurring Billing Web Services for more information on Check Data storage Input Parameters O Optional R Required R Required except when a payment reference number PNRef is provided Ont Re 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 RO 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
91. s with either the PayReceipt or Settle payment types PAYRECEIPT SETTLE Input Parameters O Optional R Required R Required unless a value of PNRef is provided Page 60 of 103 SureGate SureGate API Documentation UserName User name assigned in the payment server The user must have the apporpriate security permissions in order for the system to return transaction records eet i Ff 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 If this field is provided all other query fields will be ignored when using PNRef parameter to query the system Beginning date of the transaction record query End date of the transaction record query PaymentType If provided only those transactions matching the PaymentType will be included 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
92. saction number Tip_Amt_MN A string value Returns the tip representing a amount of a signed 64 bit real transaction number Trans_Type_ID A string value up to Returns the 20 characters transaction type e g Sale Credit Transport_Method A string Returns the Only for use with Dial up transactions Transportation Method Transport_EndPoint Astring Returns the Only for use with Dial up transactions Transportation s Ending Destination TransitNum_VC A string value up to Returns the transit This field will be masked out with asterisk 200 characters routing number characters except for the last 4 digits if the System Security Level of the user is set to 1 TRX_Card_Key A string value Returns the representing a primary key of the signed 32 bit TRX_Card_T table in Page 84of 103 SureGate API Documentation Oooo o neer TC TRX_Check_Key TRX_HD_Key TRX_Settle_Key TRX_Settle_Msg VC Type_CH User_Name_VC Void_Flag_CH Zip _CH Auth_Amt_MN Authorization A string value representing a signed 32 bit integer A string value representing a signed 32 bit integer A string value representing a signed 32 bit integer A string value up to 25 characters A string value up to 10 characters A string value up to 25 characters A string value representing a Boolean value A string value up to 10 characters A string value representing a signed 64 bit real number A string value representing a sig
93. sal transaction type lt PSN gt PSN Value lt PSN gt POS sequence number is the point of sale sequence number which follows a range between values of 001 to 999 and is Page 20 of 103 SureGate SureGate API Documentation specifically maintained by the Smart Payments Client application that allows for use with the Global Canadian Debit Allows for the submission of data specific to Interac Global Canada based transactions The Terminal ID is required with all the Interac based transactions This value is obtained from the Global PIN Pad device This value is also supported in the response field that will contain the MAC key POS Sequence Number Information and PIN Key lt Language gt Language Valid Values are Value lt Language gt English or French This value dictates what language is used in facilitating the Canadian debit transaction Page 21 of 103 SureGate API Documentation VSee Canadian Debit This value identifies the type of account being debited Valid format is lt AccountType gt Checking lt AccountType gt where Checkingindicates that a checking account is being used for the debit transaction lt AccountType gt Saving lt AccountType gt where Savingindicates that a savings account is being used for the debit transaction Page 22 of 103 SureGate SureGate API Documentation ProcessCheck Service Location For SOAP connections https secure suregate net ws
94. 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 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 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 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 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 Page 62 of 103 SureGate API Documentation Result ExcludeResult NameOnCard CardType ExcludeCardType ExcludeVoid SettleFlag SureGate If provided only those transactions matching the Result will be included Valid values are e NULL re
95. signed 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 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 Department Street1 Street2 Customer contact first name Customer contact last name Customer contact job or professional title For example Business Unit Manager or Dr Customer contact city O o o O o o CERE StatelD Customer contact s standard U S postal service two character state code U S customers only Note Valid entries are standard U S Postal service two character state codes For more information see http www usps com ncsc lookups usps_abbreviations html o O O o O O o CountryID Customer contact s three character country code For example USA Indicates whether the customer record is currently active or inactive Valid values are e ACTIVE Page 44 of 103 SureGate API Documentation e INACTIVE e PENDING e CLOSED ExtData lO Reserved for future use
96. sing 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 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 Page 46 of 103 SureGate SureGate API Documentation Numerical key value assigned to the payment method when it was Credit card number used to uniquely identify the card owner s CardinfoKey CcAccountNum CcExpDate O Credit card date of expiration in MMYY format Page 47 of 103 SureGate SureGate API Documentation ManageCheckinfo Service Location For SOAP connections https secure suregate net admin ws recurring asmx o0p ManageCheckinfo For standard HTTPS connections https secure suregate net admin ws recurring asmx ManageCheckinfo Description 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 Developer Notes The service returns a CheckInfoKey value which takes the place of the checking account data with which it is associated It is the responsibility of the integrator to keep trac
97. t Type optional Identifies the bank account for the check as a checking account or savings account Valid formats are e lt AccType gt Checking lt AccType gt to indicate a checking account e lt AccType gt Savings lt AccType gt to indicate a savings account City of Account Depending on merchant setup this may be required for TransType Sale or Return City name for the check owner s residential address See Developer Notes for invalid character processing Valid format is e lt CityOfAccount gt CityOfAccount lt CityOfAccount gt whereCityOfAccount is the check owner s city name Bill To Street Depending on merchant setup this may be required for TransType Sale or Return Street address for the check owner s bill to address See Developer Notes for invalid character processing Valid format is Page 26 of 103 SureGate SureGate API Documentation e lt BillToStreet gt BillToStreet lt BillToStreet gt where BillToStreet is the street name for the check owner s bill to address Bill To City optional City name for the check owners bill to address See Developer Notes for invalid character processing Valid format is e lt BillToCity gt BillToCity lt BillToCity gt where BillToCity is the city name for the check owner s bill to address Bill To State optional Two character state code for the check owner s bill to address See Developer Notes for invalid charact
98. t accepted Note Some processors including BuyPass will not recognize this tag and reject duplicate transactions Page 31 of 103 SureGate SureGate API Documentation ProcessGiftCard Service Location For SOAP connections https secure suregate net ws transact asmx op ProcessGiftCard For standard HTTPS connections https secure suregate net ws transact asmx ProcessGiftCard Description This web service is used to process gift card transactions for a merchant The processes supported by this web service include e Redeem make a purchase on a gift card e Reload increase the balance on a gift card e Refund refund money back to a gift card e Activate activate a gift card e Deactivate deactivate a gift card e inquire check the balance on a gift card e Void undo an unsettled transaction Paymentech Tampa only e Force place a transaction not processed through the payment server into the current batch ForceAuth Terminal based processors only e Capture settle a single transaction in the current batch Processors supporting the batch release feature only e CaptureAll settle all transactions in the current batch Developer Notes Invalid Characters Some parameters and XML tags contain data that will automatically remove invalid characters from the user entered data These parameters and tags include e MagData e InvNum e ExtData RegisterNum Input Parameters O Optio
99. t 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 Extended data in XML format Valid values are e lt IMAGE_TYPE gt NO_IMAGE lt IMAGE_TYPE gt Will only return transaction data that does not include image data to include signature data and check images lt IMAGE_TYPE gt ONLY_IMAGE lt IMAGE_TYPE gt Will only return transaction data that includes image data to include signature data and check images lt IMAGE_TYPE gt ALL lt IMAGE_TYPE gt will return transaction Page 74of 103 SureGate API Documentation with or without image data lt CustomerlD gt CustomerlD lt Customer D gt specifies the customer ID value to search by Matching is done using wild cards e g test will match test 1test and 1test234 lt Amount gt Amount lt Amount gt specifies the amount value of the transactions being searched for In DDDDDD CC format lt RegisterNum gt RegisterNum lt RegisterNum gt apecifies the register number originally passed with the transaction to search by Page 75of 103 SureGate SureGate API Documentation GetOpenBatchSummary Service Location For SOAP connections https secure suregate net admin ws trxdetail asmx 0
100. t gt SequenceCount lt SequenceCount gt where SequenceCount is any positive integer greater than or equal to the SequenceNum Server ID optional Unique server identification number See Developer Notes for invalid character processing Valid format is e lt ServerlD gt Serverl D lt Server ID gt where Server D 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 e lt TimeOut gt TimeOut lt TimeOut gt 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 e lt TrainingMode gt T lt TrainingMode gt where T true indicates that training mode is active and transactions are processed for local loop back testing lt TrainingMode gt F lt TrainingMode gt 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 e lt Transaction ID gt TransactionIdentifierValue lt TransactionID gt where TransactionldentifierValueis a numerical string Target optional Identifies th
101. 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 ManageChecklnfo see lt CheckInfoKey gt lt CheckInfoKey gt tags or can be found in the result set from the InfoCustomer web service 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 ExtData D Reserved for future use Page 39of 103 SureGate SureGate API Documentation ProcessCreditCard Recurring Billing Service Location For SOAP connections https secure suregate net admin ws recurring asmx op ProcessCreditCard For standard HTTPS connections https secure suregate net admin ws recurring asmx ProcessCreditCard Description 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 Developer Notes See Recurring Billing Web Services for more information on Credit Card Data storage Input Parameters O Optional R Required R Required except when a payment reference number PNRef is provided one UserName Password User name assigned in the payment server The user must have an appropriate level of access in order to utilize t
102. 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 Page 52 of 103 SureGate SureGate API Documentation StatelD Customer contact s standard U S postal service two character state code U S customers only Note Valid entries should follow USPS two character state code standards For more information see http www usps com ncsc lookups usps_abbreviations html Province oo Customer contact s province countries outside the U S only ip Customer contact s zip or postal code CountrylD Zi Fax Customer contact s three character country code For example USA United States or CAN Canada DayPhone NightPhone Customer contact s daytime phone number Customer contact s after hours phone number Customer contact s fax number Email Customer contact s email address Mobile Customer contact s mobile phone number 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 BillAmt Amount billed each time the co
103. tion 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 lt ContractKey gt lt ContractKey gt tags when a new contract is added to the system Page 56 of 103 SureGate API Documentation NumOfDays The number of days to be added to the NextBillDt field This value must be a positive integer ExtData FO Reserved for future use Page 57 of 103 SureGate SureGate API Documentation AddCustomField Service Location For SOAP connections https secure suregate net ws customfields asmx op AddCustomField For standard HTTPS connections https secure suregate net ws customfields asmx AddCustomField Description 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 Developer Notes 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 To pass data into a field an integrator must build an XML string which conforms to the following format The following example assumes that the integrator has
104. transact asmx op ProcessCheck For standard HTTPS connections https secure suregate net ws transact asmx ProcessCheck Description This web service is used whenever a transaction is completed via customer check The processes supported by this web service include e Sale make a purchase using a check manually keyed or scanned e Auth Verify authorizes or verifies the amount of a check e Return return the money of a settled check transaction to the check holder e Void undo a settled check transaction e Force ForceSale force a previous Sale transaction into the current batch Terminal based processors only e Capture settle a single transaction in the current batch e CaptureAll settle all transactions in the current batch Developer Notes Invalid Characters Some parameters and XML tags contain data that will automatically remove invalid characters from the user entered data These parameters and tags include e NameOnCheck e DL e SS e DOB e StateCode e ExtData lt Phone gt e Extdata lt Email gt e ExtData lt CityOfAccount gt e ExtData lt BillToStreet gt e ExtData lt BillToState gt e ExtData lt BillToPostalCode gt e ExtData lt BillToCountry gt e ExtData lt CustomerlD gt Date Formats Valid entry formats are e MM DD YYYY e YYYY MM DD Input Parameters Page 23 of 103 SureGate SureGate API Documentation O Optional R Required R Required except in
105. tring value representing a signed 64 bit real number A string value representing a signed 32 bit integer Returns the payment type e g ECHECK Returns the dollar amount of all PostAuth transactions Returns the transaction count of all PostAuth transactions Returns the name the payment processor e g Vital Returns the dollar amount of all transactions with a Receipt Returns the transaction count of all transactions with a Receipt Not currently used Returns the register number of a transaction Returns the dollar amount of all RepeatSale Recurring Billing Installment transactions Returns the transaction count of all RepeatSale Recurring Billing Installment transactions Page 82 of 103 This value will always return 0 This value will always return 0 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 SureGate API Documentation Reseller_Key Result_CH Result_Msg_ VC Result_Msg1_ VC Result_Msg2_VC Result_Txt_VC Return_Cnt A string value representing a signed 32 bit integer A string value up to 50 characters A string value up to 50 characters A string value up to 50 characters A string value up to 50 characters A string value up to 150 characters A string value representing a signed 64 bit real number A string value representing a signed 32 bit integ
106. turns both approved and declined transactions e 0 returns only approved transactions Note To return only declined transactions leave this parameter blank and use the ExcludeResult parameter Page 72 of 103 SureGate SureGate API Documentation 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 Note To return a only declined transactions set ExcludeResult 0 NameOnCheck 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 If a check number is provided for this parameter only those me _ P_ setonswtn singe ie o be red 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 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 Valid entries are e TRUE voided transactions are excluded e FALSE voided transactions are in
107. turns both approved and declined transactions e returns only approved transactions e 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 If provided any transactions matching the ExcludeResult will be excluded Note To return a only declined transactions set ExcludeResult 0 Cardholder s name as it is appears on the card If provided only those transactions with cardholder s name matching NameOnCard will be included Matching is done using wild cards e g test will match test 1test and 1test234 Acard number If provided only those transactions with the card number matching CardNum will be included Matching is done using wild cards This field has been deprecated Please use the PaymentType field to specify the type of card used in a transaction 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 The ExcludeVoid parameter allows you to exclude voided transactions from the result set Valid entries are e TRUE voided transactions are excluded e 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 The user who originated the transactions I
108. uery String The query string used to obtain transactions in a date range is constructed as follows Date DT gt BeginDt AND Date DT lt EndDt Date DT is the transaction timestamp Input Parameters O Optional R Required R Required unless a value of PNRef is provided Ont UserName User name assigned in the payment server The user must have an appropriate level of access within the system in order to return records Password RO Password associated with the user name provided 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 JRO Identifies the beginning date range for a group of transactions Endt ss TR 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 Page 66 of 103 SureGate SureGate API Documentation 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 The register is a unique string use
109. umentation Processing Services transact asmx top The following response fields may be part of the return value for web services using transact asmx operations These web services include Applicable Web Services e Getlnfo e ProcessCheck e ProcessCreditCard e ProcessDebitCard e ProcessEBTCard e ProcessGiftCard e ProcessSignature Response Field Definitions Response Field Data Type Value Remarks Description AuthCode A string value Returns the This value can be either an approval code for approved up to 50 transaction transactions or an error code for declined transactions characters result code from the payment processor ExtData A string value Returns The value of ExtData will be in a specific format The up to 500 extra data format typically consists of the name of the data field characters from the an equal sign and then the value for the data field processed Multiple data fields are separated with a comma transaction See the Web Service ExtData Response Field Data Elements for full description of data elements that can be returned The following is an example of the format ExtName1 ExtValue1 ExtName2 ExtValue2 GetAVSResult A string Returns When programmatically validating an AVS Result this value upto 1 the overall value should ALWAYS be used instead of any formatted character address response message describing the result verification result code from the payment processor GetAVS
110. veloper Notes Invalid Characters Some parameters and XML tags contain data that will automatically remove invalid characters from the user entered data These parameters and tags include e MagData e NameOnCard InvNum e RegisterNum 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 ProcessEBTCard operation must then send the appropriate register number to reflect the Page 28 of 103 SureGate SureGate API Documentation appropriate transaction type Input Parameters O Optional R Required R Required except in Capture and CaptureAll transactions R Required except for CaptureAll transactions R1

Download Pdf Manuals

Related Search

Related Contents

  06 - SIMRAD  User Manual  CLASSIC-LINE / ECO-LINE - Rüegg  TopControl Positioner Type 8630  1 - ps-2.kev009.com, an archive of old documentation and sites  USER MANUAL - Seaside Communications  IBM System x3550 M4 Typ 7914: Installations  TRIMBLE 3600 Hardware Handbuch deutsch  Toshiba Satellite P50-AST2GX1  

Copyright © All rights reserved. Failed to retrieve file