Home

Document Version 2.7.6

1. ET gt lt RE A p A A A A A A A A p PURCH_CA lt CVV2_COD T gt CI gt Y lt ACI gt PROC_RES CMRCL_TY P_CODE gt 00 lt RD_TYPE gt 0 lt E gt lt CVV2_COD Da D Z e U D H za v RANS_ID gt 13 lt TRANS_ID gt MSI gt lt MSI gt EM gt lt PEM gt IM gt 160226 lt TIM gt PROC_RESP_COD PE gt 0 lt CMRCL_TYPE gt PURCH_CAR lia gt RDHOLD 00347 0812 lt TRACK_DATA gt E w v E v D_TYP Fl Vv lt INTRN_SEQ_NUM gt 13 lt INTRN_SEQ_NUM gt lt T T RANS_IT EM_NUM gt 008 lt TRANS_ITI EM_NUM gt 23 lt TICODE gt lt TICODE gt lt CARD_ID_CODE gt lt CARD_ID_CODE gt lt ACCT_DATA_SRC gt D lt ACCT_DATA_SRC gt lt XML_REQUEST gt lt XML_FILI gt EJ Note If you wish to force a duplicate transaction using the same credit card and amount just place an F at the beginning of the Account Number string This action will force the transaction to be sent for authorization 24 Appendices A Test Card Information Integrators can use these following test cards for manually keyed in transaction testing If a full track II is required for the test please contact our Pivotal support team at setup Opivotalpayments com Expiration Card Type Card Number Date VISA 4387755555555550 1209 Mastercard 5454545454545454 1210 AMEX 3
2. The amount of the transaction Format DDDDDD CC Max Length 9 characters including the decimal The value may not be negative Do not use commas Note The amount MUST include the decimal point and the cents even if the amount is a whole dollar amount Example 3 00 not 3 or 3 If sending less than one dollar the zero place holder must be sent as well Example 0 50 The track II data captured from the magnetic strip of the card The track data is required Max Length 40 characters Note The characters that are appended to the beginning and ending of track II usually and should not be passed in Example 5439750001500347 08121011000001234567 The ticket or invoice number for internal referencing by merchant This value is passed to the processor for referencing purposes Max Length 9 characters The value can be alphanumeric Note Concord EFS CCRD supports only a 6 length numeric ticket or invoice number The cardholder s name Max Length 20 characters If a Key Serial Number is obtained from the PIN pad this property should be populated with that number If processing transactions with a PIN pad using DUKPT encryption this value is sixteen or twenty characters long depending on the processor s encryption The SmartPayments Client Service will automatically obtain this information if not provided with the transaction 13 Data Tag Type Description Debit I nput File
3. 20000 MICRO 122 Drivers License Verify 230 Double A WoidCheck 510 Sale MICR SA Void MICR 53 Force MICR EBT sae Description lso Account AU Inquiry O ee a a a aeaea 62 Food Stamp Purchase ss i i lt lt a i 63 Food Stamp Credit Batch Action TE Description 31 Batch Settlement Settlement 85 Batch Inquiry Store and Forward Action Description 98 St re and Forward and Forward O 27 C Result and Response Codes Address Verification Response Codes Response Code Address Match A Address matches ZIP code does not B Address matches postal code does not C No match on address or postal code D Street address and postal code matches E AVS error G Service not supported by non US issuer Address not verified for international transaction Street address and postal code matches No match on address or ZIP code Postal code matches address does not Retry system is unavailable or timed out Service not supported by issuer card type does not support AVS Address information is unavailable 9 digit ZIP code matches address does not Exact match Address and 5 digit ZIP code match 5 digit ZIP code matches address does not O N lt x lt s c u u z z No response sent CVV2 CVC2 CID Response Codes Response Code Address Match M CVV2 CVC2 CID match N CVV2 CVC2 CID mismatch Not processed Either the expiration date was not provided or the card do
4. companies Returns the Retrieval reference number This value is not RET String returned by all processing companies Returns the POS entry mode that is associated with the PEM String transaction This value is not returned by all processing companies TIM String Returns the Time of the transaction This value is not returned by all processing companies Returns the Authorization Characteristics Indicator is that ACI String is provided by the card associations This value is stored for settlement Returns the response code that is provided by the PROC_RESP_CODE String processor This value is not returned by all processing companies Returns a code that is used to verify the identity of the CARD_ID_CODE String cardholder ACCT_DATA_SRC String Returns the entry method of the transaction EBT File Layouts This section contains the tags required to process EBT transactions 19 For processing EBT Cards a pin pad is required to allow for the customer to enter their PIN The EBT information is usually collected via a card swipe device instead of keyboard entry so it is a requirement as well to have this card swipe reader Note some EBT processors would allow for manually keyed in transactions EBT Input File INX Tag Data Description EBT Input File I NX Type The action code that identifies what type of transaction ACTION String will be performed Consult the Constants for a list of valid values The credit card numb
5. Length 25 characters Tag TAX_AMOUNT Z P_CODE STREET TICKET_NUM CARDHOLDER CVV2 CMRCL_FLAG AUTH_CODE Data Type String String String String String String String String Description Credit I nput File inx The tax amount This is the portion of the amount that is tax Providing the tax amount is required to obtain the best rate on commercial card transactions Format DDDDDD CC The transaction s action code must indicate that it is a commercial transaction Max Length 9 characters including the decimal The cardholder s zip code The Zip property is used for address verification Max Length 9 digits Address verification can only be performed on non swiped transactions Note For manually keyed transactions the Zip is required to qualify for the lowest transaction rates Note f submitting the 9 digit zip do not include the dash The cardholder s billing street address The Street property is used for address verification Address verification can only be performed on non swiped transactions Note For manually keyed transactions Street is required to qualify for the lowest transaction rates Max Length 20 characters The ticket or invoice number for internal referencing by merchant This value is passed to the processor for referencing purposes Max Length 9 characters The value can be alphanumeric Note Concord EFS CCRD supports only a 6 length numeric ticket
6. Returns the response code that is provided by the processor This value is not returned by all processing companies This section describes the XML tags required to process Gift Loyalty transactions Gift Card Input File INX Tag ACTION ACCT_NUM USER_ID EXP_DATE Data Type String String String String Description Gift Input File I NX The action code that identifies what type of transaction will be performed Consult the Constants for a list of valid values The gift card number that will be used when processing the transaction Max Length 20 characters Example 5439750001500347 This is a new feature that will allow integrators to specify which account they would like their transaction to be associated with if they have multiple merchant accounts set up on their client The limitation of this feature is that the merchant needs to be set up with a Payment Server merchant account The valid values of this USER_ID are the index value of the profile representing that merchant account For example if there are two profiles on the account one for VITAL and a second profile for Global Payments Vital Profile Index 0 Global Payments Index 1 The integrator can then choose to pass 0 to represent the profile index of VITAL or 1 for Global to send transactions to the respective account The expiration date associated with the credit card number that will be processed Must be exactly
7. a Payment Server it would be a good practice to enable the local SmartPayments Admin Client database so that the internal sequence numbers reference numbers will be returned in the output file The internal sequence or reference numbers are used for follow on transactions such as Voids and Post Authorizations The screen shot below shows how this is enabled in the SmartPayments client user interface Check Flat File Credit Flat Fie InPutFie System j DutPut Device Data to Flat File Training Mode MV Debug Log File a a V Reset on Startup Time Out 40 Seconds Payment Types Supported V Credit Iv Gift Cards V Debit Y Check Verification V EBT V Electronic Checks pes Additional Debit Options Cash Back SurCharge Cash Back Only SurCharge 0 00 OK Cancel Apply Help Processing Cycle of XML File Drop Integration 1 An input file lt file name gt inx is dropped in the specified location i e C temp 2 The SmartPayments Manager polls for any files with this extension and once it is found it performs validation on the file and then changes it into a lt file name gt pro meaning that this file is in the process of getting routed to the appropriate payment processor 3 When a response is determined the SmartPayments manager will then replace this lt file name gt pro file with the finished lt file name gt oux file which will be ready for retrieval and parsing by the POS application 4 After this
8. companies Returns the ticket number or invoice of the transaction Returns the Internal Sequence Number which is an assigned unique number for each transaction Returns the Transaction Item number or the number that is associated with the transaction in the settlement file This value is not returned by all processing companies Returns the active batch number for the transaction This value is not returned by all processing companies Returns the Transaction Identifier that is returned from the processor This value is not returned by all processing companies Returns the Transaction Indicator Code that is returned from the processor The Transaction Indicator Code is a Validation code for VISA MasterCard This value is not returned by all processing companies Returns the Market Specific Indicator This value indicates the transaction s market segment This value is assigned by the card associations and is not returned with all transactions Returns the Retrieval reference number This value is not returned by all processing companies Returns the POS entry mode that is associated with the transaction This value is not returned by all processing companies Returns the Time of the transaction This value is not returned by all processing companies Returns a one character identification code that identifies the network on which transactions approved 22 Tag EBT_FOOD_BALANCE EBT_CASH_BALANCE Data Type
9. file has been retrieved or read by the POS application and the information has been processed it is strongly suggested that this lt file name gt oux file be destroyed for security purposes These are the basic steps that need to be taken for developing a POS application for processing XML files 1 Write the transaction information to a file in the XML message format ASCII text using the file layouts described in this section 2 Name the file lt file name gt inx ex regl inx 3 Place the lt file name gt inx file into the designated directory The transaction will now be processed by SmartPayments 4 Wait for lt file name gt oux to appear in the SmartPayments directory 5 Wait for lt file name gt pro to be deleted from the SmartPayments directory 6 Read the values from lt file name gt oux The most important information is returned in the RESULT and AUTH_CODE tags 7 Delete lt file name gt oux Example Credit Sale transaction lt XML_FILE gt lt XML_REQUEST gt lt COMMAND gt 1 lt COMMAND gt lt ACCT_NU gt 543975 lt EXP_DAT lt TRANS_AI lt XML_REQUEST gt lt XML_FILE gt Credit File Layouts MOUNT gt 2 XP_DATE gt 0001500347 lt ACCT E gt 1208 lt E lt MANUAL_FLAG gt 0 lt MANUAL_FLAG gt 00 lt TRANS_AMOUNT _NUM gt This section describes the tags required to process credit card transactions Credit In
10. four characters long Format MMYY Note Most gift cards have no expiration date Example 1249 17 Tag MANUAL_FLAG TRANS_ AMOUNT REFERENCE TRACK_DATA AUTH_CODE FORCE_FLAG Data Type String String String String String String Description Gift Input File I NX Flag that indicates whether the transaction was manually entered or swiped If the transaction was swiped the TRACK_DATA property must also be set Valid values 0 manual transaction 1 swiped transaction The amount of the transaction Format DDDDDD CC Max Length 9 characters including the decimal The value may not be negative Do not use commas Note The amount MUST include the decimal point and the cents even if the amount is a whole dollar amount Example 3 00 not 3 or 3 If sending less than one dollar the zero place holder must be sent as well Example 0 50 The reference number from the original transaction returned by the processor The REFERENCE property does not need to be set if the Post Authorization completes a standard Pre Authorization using the internal sequence value of the Pre Authorization The track I data captured from the magnetic strip of the credit card The track II data is required to ensure the lowest per transaction rate from the processing company when performing swiped transactions Retail and Restaurant Sending the track II data is not allowed if the me
11. response file from the same location Before using this integration method there are configuration settings that need to be set in the SmartPayments Client User Interface Please follow these steps in setting up the SmartPayments Client software to be able to accept this XML Format 1 Launch the Pivotal Payments Gateway Client user interface by double clicking on smartadmin exe 2 Locate the Set up menu and then select Payments 3 Change the Input Format from the default TCP XML Pay Format to XML Industry Standard File as shown in the example below Configure Payment System 3 x Interface TPI Software Store and Forward Input Format Location C Temp Browse OutPut Format TFPI Software OK Cancel Apply Help 4 The Location field will then be enabled and is used to specify the location that the POS developers will send the input files for processing and retrieve the output response files The SmartPayments manager will be polling this file location for any files with the extension INX that need to be processed The folder specified in the Location field needs to have the correct permissions set so that the Pivotal Payments Gateway Manager will have full access to it 5 Stop and re Start the Service to make sure that the configuration changes are committed 6 If itis the case that the SmartPayments Client Admin will be doing a direct communication to a payment processor instead of
12. was swiped the TRACK_DATA property must also be set Valid values 0 manual transaction 1 swiped transaction The amount of the transaction Format DDDDDD CC Max Length 9 characters including the decimal The value may not be negative Do not use commas Note The amount MUST include the decimal point and the cents even if the amount is a whole dollar amount Example 4 00 not 4 or 4 If sending less than one dollar the zero place holder must be sent as well Example 0 65 This has to be passed in the INX file The cardholder s zip code The Zip property is used for address verification Max Length 9 digits Address verification can only be performed on non swiped transactions Note For manually keyed transactions the Zip is required to qualify for the lowest transaction rates Note If submitting the 9 digit zip do not include the dash 15 Tag TICKET_NUM MICR STATE LICENSE ABA_NUMP PHONE_NUM DOB CHECK_NUM Data Type String String String String String String String String Description Check Input File inx The ticket or invoice number for internal referencing by merchant This value is passed to the processor for referencing purposes Max Length 9 characters The value can be alphanumeric Note Concord EFS CCRD support only a 6 length numeric ticket or invoice number Transactions will decline if the TICKET_NUM is
13. 4p PIVOTAL PAYMENTS XML File Method Integration Developer Kit User s Manual Document Version 2 7 6 Copyright O 2007 2008 Pivotal Payments Inc All Rights Reserved Visit us at www pivotalpayments com Support Pivotal Payments is committed to providing the highest quality tools and customer support If you have any questions comments or suggestions please contact Pivotal Payments at USA Canada Pivotal Payments Inc Pivotal Payments Inc 200 Broadhollow Road Suite 207 685 Cathcart Street Suite 1000 Melville NY 11747 Montreal QC H3B 1M7 Support 1 866 298 9895 Support setup pivotalpayments com VAR Integrator Support integration pivotalpayments com Sales gateway_sales pivotalpayments com Thank you for choosing Pivotal Payments Integration Methods File Method Integration A widely used integration method that uses an XML industry standard file format The required fields will be formatted in XML tags as an input file that will be dropped or sent to a specified location This specified location is then polled by the SmartPayments Client if there are any input files processed and then replaced with an output response file that contains data from the payment processor TCP Socket Integration This integration method utilizes the same XML tags as the XML file drop but the difference is that this is not dropped as a file but requested by the POS application as a data stream using the winsock OCX compo
14. 71449635398431 1210 Discover 6011000995500000 1210 Procurement Card 5405010100000016 1210 Mastercard Procurement card 1210 VISA 4275330012345675 Notes on Testing Please secure a testing account with the payment processor of your choice or Pivotal support will assist you in testing against our test hosted gateway Contact us for this information so you may begin testing against a simulated live merchant account setting for those integrators that will be routing to a Payment Server gateway Debit Transactions for PIN based debit will require an encryption scheme injected pin pad by a specific processor and either a test plastic card or a live card for testing This is required because all true debit transactions need to be swiped only accompanied by a personal identification number PIN For those that want the debug log files turned on you may enable this by launching the SmartPayments Admin Client executable and proceed to SetuplConfigurelOptions and select the Debug log file This debug log file when enabled will log transactions processed through the SmartPayments Admin Client and is located in the Pivotal directory as SmartPayments log 25 B Action Command Codes Credit Card Command pint Code Description 1 sae SSS A Gratuity o UU Debit Gift ome Description A RA eae Description 18 Balaae 26 Refund Credit A Agivate o 30000 d 26 Check Action Description
15. E REFERENCE TRANS_ DATE TICKET INTRN_SEQ_NUM TRANS_ITEM_NUM TBATCH TRANS_ID TICODE MSI RET PEM TIM NET_ID Data Type String String String String String String String String String String String String String String String String String Description EBT Output File OUX Returns the result which indicates the transaction s status upon completion Refer to the Transaction Result Constants section for a list of valid values and descriptions For approved transactions returns the authorization code from the issuing bank For declined transactions returns the reason why the transaction was declined if the issuing bank provides one or why the transaction was rejected This returns the last 4 digits of the card number used by the cardholder to perform this payment transaction Note Now Applicable to Global Canada This field displays the card type used in the payment transaction Please see CARD_TYPE list for valid values Note Now Applicable to Global Canada Returns the reference number associated with the transaction The reference number is assigned by the card associations The reference number is used to help identify the transaction and is useful for the cardholder and merchant when doing research This value is not returned with all transactions Returns the date that the transaction was processed This value is not returned by all processing
16. String String Description EBT Output File OUX Returns the remaining Balance on a Food Stamp card This value is not returned by all processing companies Returns the remaining balance on a Cash Benefits card This value is not returned by all processing companies These properties are required to process transactions Notes These XML tags follow the industry standard formats and please be advised that these formats This format has its own ERROR CODE Definition XML File Sample Input File Structure For a swiped transaction lt XML_FILE gt lt XML_R EQUEST gt lt XML_R lt XML_FILE gt lt XML_FILE gt lt XML lt COMMAND gt 1 lt COMMAND gt lt ACCT_NUM gt 5439750001500347 lt ACCT_NUM gt lt EXP_DATE gt 1208 lt lt MANUAL_FLAG gt 1 lt MANUAL_FLAG gt EXP_DATE gt lt TRANS_AMOUNT gt 1 00 lt TRANS_AMOUNT gt lt TRAC lt Z lt STREET gt 8320 lt STREE lt CARDHOLDER gt John Doe lt CA K_DATA gt 54397500015 IP_CODE gt 85284 lt ZIP_CODE gt EQUEST gt UEST gt lt AVS_CODE gt R lt AVS_CO RANS_DATE gt 1125 lt T lt T lt E lt T p H R T gt ESULT gt CAPTURED lt R E gt QAV1MC lt AUTH_COD UTH_COD ESULT gt EFERENC E v E gt 13 lt REFER ENCE gt ICKET gt lt TICKET gt
17. al carriage return new line to this tag Please note that if the integrator is expected to properly parse this data through their own point of sale if they are to use this properly If this is not the case then do not enable this option in the Smart Client user interface Returns a flag indicating whether the processor indicated whether the card was a Purchasing Card or not This value is not returned by all processing companies Valid values 1 Purchasing Card 0 Otherwise Returns the gratuity amount if one is associated with the transaction This value is not returned by all processing companies Returns a numerical representation of the result of the transaction Currently this field is only used for a batch transaction Returns the Commercial Card Flag This indicates what type of Commercial card was used for the transaction This value is not returned by all processing companies Returns a one character identification code that identifies the network on which the transaction was approved This value is not returned by all processing companies 11 Data Tag Type Description Charge Output File oux Returns the Authorization Source Code The authorization source code indicates to the processor who authorized the transaction This value is not returned by all processing AUTH_SRC_CODE String companies Values Returned no card reader D Track 2 T Keyed track 2 capable Returns a code that is used to verify the ide
18. clined transactions returns AUTH_CODE String the reason why the transaction was declined if the issuing bank provides one or why the transaction was rejected This returns the last 4 digits of the card number used by the CARD String cardholder to perform this payment transaction This field displays the card type used in the payment CARD_TYPE String transaction Please see CARD_TYPE list for valid values Returns the reference number associated with the transaction The reference number is assigned by the card associations The reference number is used to help identify the transaction and is useful for the cardholder and merchant when doing research This value is not returned with all transactions REFERENCE String Returns the date that the transaction was processed This ANS PATS String value is not returned by all processing companies TICKET String Returns the ticket number or invoice of the transaction Returns the Internal Sequence Number which is an SES NUM string assigned unique number for each transaction Returns the Transaction Item number or the number that is associated with the transaction in the settlement file TRANS_ITEM_NUM String This value is not returned by all processing companies This will contain the PNREF information which is a SmartPayments Client Unique Identifier Returns the Transaction Identifier that is returned from TRANS_ID String the processor This value is not returned by all processing
19. d can be enabled Valid values True or False This is a new feature that will allow integrators to specify which account they would like their transaction to be associated with if they have multiple merchant accounts set up on their client The limitation of this feature is that the merchant needs to be set up with a Payment Server merchant account The valid values of this USER_ID are the index value of the profile representing that merchant account For example if there are two profiles on the account one for VITAL and a second profile for Global Payments Vital Profile Index 0 Global Payments Index 1 The integrator can then choose to pass 0 to represent the profile index of VITAL or 1 for Global to send transactions to the respective account These properties are the minimum required to process a Sale or Pre Authorization transaction This field is required when MANUAL_FLAG value is set to 1 Credit Output File oux Tag RESULT AUTH_CODE CARD CARD_TYPE REFERENCE AVS_CODE TRANS_ DATE TICKET INTRN_SEQ_NUM TRANS_ITEM_NUM TBATCH TRANS_ID TICODE IND MSI RET Data Type String String String String String String String String String String String String String String String String Description Charge Output File oux Returns the result which indicates the transaction s status upon completion Refer to the Transaction Resu
20. d in the payment CARD_TYPE String transaction Please see CARD_TYPE list for valid values Note Now Applicable to Global Canada Returns the reference number associated with the transaction The reference number is used to help REFERENCE String identify the transaction and is useful for the cardholder and merchant when doing research This value is not returned with all transactions Returns the date that the transaction was processed This ANA PAT String value is not returned by all processing companies Returns the ticket number or invoice of the transaction TICKET String This value is echoed back from the original transaction INTRN_SEQ_NUM String Returns the Internal Sequence Number which is an assigned unique number for each transaction Returns the Transaction Item number or the number that TRANS_ITEM_NUM String is associated with the transaction in the settlement file This value is not returned by all processing companies Returns the active batch number for the transaction This value is not returned by all processing companies The TICODE field contains the last byte of the Working key that is provided by the processor TBATCH String TI CODE String 14 Tag TIM NET_ID Check File Layouts Data Type String String Description Debit Output File oux Returns the Time of the transaction This value is not returned by all processing companies Returns a one character identification code tha
21. ending the track II data is not allowed if the TRACK_DATA String merchant s industry type is MOTO or eCommerce Max Length 40 characters Example 5424180279791765 08121011000001234567 Note The characters that are appended to the beginning and ending of track II usually and should not be passed in If a Key Serial Number is obtained from the PIN pad this property should be populated with that number If processing transactions with a PIN pad using DUKPT encryption this value is sixteen or twenty characters long depending on the processor s encryption The SmartPayments Client Service will automatically obtain this information if not provided with the transaction KEY_SERIAL_NUM String 20 Tag PIN_ BLOCK ZIP_CODE TICKET_NUM CARDHOLDER CASHBACK_AMNT EBT_TYPE AUTH_CODE Data Type String String String String String String String Description EBT Input File I NX The encrypted PIN block that is retrieved from the PIN pad The PIN is provided to the processor for verification Max Length 16 characters The cardholder s zip code The Zip property is used for address verification Max Length 9 digits Address verification can only be performed on non swiped transactions Note For manually keyed transactions the Zip is required to qualify for the lowest transaction rates Note If submitting the 9 digit zip do not include the dash The ticket or invoice number for interna
22. er that will be used when processing 5 the transaction ACCT_NUM String Max Length 20 characters Example 5439750001500347 The expiration date associated with the credit card a number that will be processed Must be exactly four EXPTE String characters long Format MMYY Example 1208 Flag that indicates whether the transaction was manually MANUAL FLAG String entered or swiped If the transaction was swiped the TRACK_DATA property must also be set Valid values 0 manual transaction 1 swiped transaction The reference number from the original transaction returned by the processor The REFERENCE property REFERENCE String does not need to be set if the Post Authorization completes a standard Pre Authorization using the internal sequence number value of the Pre Authorization The amount of the transaction Format DDDDDD CC Max Length 9 characters including the decimal The value may not be negative Do not use commas TRANS_ AMOUNT String Note The amount MUST include the decimal point and the cents even if the amount is a whole dollar amount Example 4 00 not 4 or 4 If sending less than one dollar the zero place holder must be sent as well Example 0 80 The track I data captured from the magnetic strip of the credit card The track II data is required to ensure the lowest per transaction rate from the processing company when performing swiped transactions Retail and Restaurant S
23. es not have a CVV2 CVC2 CID value If the expiration date P was left blank resubmit as a zero dollar amount for the transaction so the customer s credit line won t be affected by the second CVV2 CVC2 CID request Issuer indicates that the CVV2 CVC2 CID data should be present on S the card but the merchant has indicated that the CVV2 CVC2 CID data is not present on the card Issuer has not certified for CVV2 CVC2 CID or issuer has not provided Visa MasterCard with the CVV2 CVC2 CID encryption keys 28 D Constants and Definitions Transaction Result Constants Result CAPTURED NOT CAPTURED APPROVED NOT APPROVED CANCELLED Transaction Type Description Successful online transaction now ready for Monetary settlement Varies Unsuccessful online transaction Successful offline transaction for Terminal based Non Monetary processors or successful Pre Authorization for Host based processors Unsuccessful offline transaction or unsuccessful wanes Pre Authorization for Host based processors Transaction canceled by operator or modem never Any connected Credit Card Transactions Definitions There are several types of credit card transactions The different types of transactions are referred to as actions The following is a list of the various actions with general descriptions Term Sale Void Sale Credit Void Credit Pre Authorization Commercial Card Sale Definition Diminishes the cardholder s o
24. inx The amount of cash back that the customer will receive This amount is in addition to value entered in TRANS AMOUNT property For example if the total amount of the sale is 10 and the customer has requested 5 cash back TRANS AMOUNT should be set to 15 and CASHBACK_AMNT String CASHBACK_AMNT should be set to 5 The CASHBACK_AMNT property should be formatted the same the TRANS AMOUNT property Max Length 9 characters Note Some debit processors do not support the cash back feature The encrypted PIN block that is retrieved from the PIN PIN_ BLOCK String pad The PIN is provided to the processor for verification Max Length 16 characters These properties are required to process a Debit Sale transaction Debit Output File oux Data Tag Type Description Debit Output File oux Returns the result which indicates the transaction s status upon completion Refer to the Transaction Result Constants section for a list of valid values and descriptions RESULT String For approved transactions returns the authorization code from the issuing bank For declined transactions returns AUTH_CODE String the reason why the transaction was declined if the issuing bank provides one or why the transaction was rejected This returns the last 4 digits of the card number used by the CARD String cardholder to perform this payment transaction Note Now Applicable to Global Canada This field displays the card type use
25. iped transaction The amount of the transaction Format DDDDDD CC Max Length 9 characters including the decimal The value may not be negative Do not use commas Note The amount MUST include the decimal point and the cents even if the amount is a whole dollar amount Example 3 00 not 3 or 3 If sending less than one dollar the zero place holder must be sent as well Example 0 50 The reference number from the original transaction returned by the processor The REFERENCE property does not need to be set if the Post Authorization completes a standard Pre Authorization using the internal sequence value of the Pre Authorization The track I data captured from the magnetic strip of the credit card The track II data is required to ensure the lowest per transaction rate from the processing company when performing swiped transactions Retail and Restaurant Sending the track II data is not allowed if the merchant s industry type is MOTO or eCommerce Max Length 40 characters Note The characters that are appended to the beginning and ending of track II usually and should not be passed in Example 5424180279791765 08121011000001234567 Customer code for purchasing commercial cards This property must be set for commercial card transactions in order to get the best discount rate Additionally the transaction s action code must indicate that the transaction is a commercial card transaction Max
26. k These strong encryption keys are specific to the payment processor Please consult the properties specific to debit card transactions supported by the different integration methods TRACK Key Serial Number PIN Block data elements are required in addition to the basic sale information transmitted for normal credit card transactions Debit CHECK cards can be used as credit cards as well without the PIN and these are often referred to as offline debit cards These are debit cards that are branded as check cards with a credit card association logo 32 Gift Card Definitions Gift Card programs have become popular over the last few years Gift Cards are plastic cards similar to a credit or debit card that can be both hand keyed or swiped through a card reader These are basically designed as an alternative to the paper loyalty cards or gift certificates When a gift card is purchased either through cash or credit cards the gift card will then have to be activated with either a fixed or variable amount tied to the gift card Some gift card programs allow for reloading more funds to that gift card that can be used to purchase items from a store When a purchase is done using a gift card the request is sent to a gift card processor and the amount will be debited from the card value A balance on the gift card is usually returned along with the response from the gift card sale Since gift card processors are host based settlement close is usua
27. k Verification This transaction permits the merchant to confirm that the check writer has a checking account and does not have any outstanding checks Check Guarantee This transaction allows the merchant to verify that the check writer has an existing account and that the amount for that transaction can guaranteed Note The guaranteed amount may vary so please consult with your check processor Check Conversion This action allows the merchant to transmit the MICR information from the check to the issuing bank and receive electronically deposited funds thus eliminating the need for paper checks Check Transaction types as supported by SmartPayments Client Verify Enables the merchant to confirm that the customer has an existing checking account and assures the transaction amount is available This action also enables the merchant to perform the first of two steps in the check sale transaction Sale Diminishes the checking account balance of the customer A sale executes two functions verification of the check and finalization the transaction for settlement Void Eliminates a Sale or Force transaction for the settlement information The transaction will be deleted and no funds will be received from this transaction The Void Sale action is used to edit and correct mistakes on the same day before the settlement process is finalized This can only be performed before the settlement is closed Force Finalizes a verified check t
28. l referencing by merchant This value is passed to the processor for referencing purposes Max Length 9 characters The value can be alphanumeric Note Concord EFS CCRD supports only a 6 length numeric ticket or invoice number Transactions will decline if the TICKET_NUM is not submitted with each transaction Note For manually keyed transactions TICKET NUM is required to qualify for the lowest transaction rates The cardholder s name Max Length 20 characters The amount of cash back that the customer will receive This amount is in addition to value entered in TRANS AMOUNT property For example if the total amount of the sale is 10 and the customer has requested 5 cash back TRANS AMOUNT should be set to 15 and CASHBACK_AMNT should be set to 5 The CASHBACK_AMNT property should be formatted the same the TRANS AMOUNT property Max Length 9 characters Note Some debit processors do not support the cash back feature EBT_TYPE Indicates what type of EBT transaction will be performed Valid values F Food Stamp Transaction C Cash Benefits transaction For an EBT Forced Authorization the original authorization code would need to be passed in this tag from the Pre_Auth transaction These properties are the minimum required to process a Sale or Pre Authorization transaction This field is required when MANUAL_FLAG value is set to 1 21 EBT Output File OUX Tag RESULT AUTH_CODE CARD CARD_TYP
29. llow on transaction called a Post Authorization must occur This action is commonly used in MOTO Mail Order Telephone Order and eCommerce environments Diminishes the cardholder s open to buy amount and places the transaction in the open batch This action is similar to a standard credit card sale but is typically used if the card tendered is a procurement purchasing business government or commercial card Two additional values the Tax amount and customer code must be passed with this type of card in order for the merchant to qualify for the lowest transaction rate 29 Term Commercial Card Credit Commercial Card Post Authorization Sale with Gratuity Definition Typically used after the batch that contains the Procurement Card Sale or Procurement Card Post Authorization transaction has been settled or closed This action is similar to a standard credit card credit but is typically used if the card tendered is a procurement purchasing business government or commercial card This action will increase the cardholder s limit to buy once the batch containing the credit has been settled Two additional values the Tax amount and customer code must be passed with this type of card in order for the merchant to qualify for the lowest transaction rate Places an approved Pre Authorization transaction into the open batch This action is similar to a standard credit card Post Authorization but is typically used if the ca
30. lly not applicable EBT Definitions EBT stands for electronic benefits transfer wherein the government of the United States can issue benefits electronically These benefits cover food stamps cash benefits issued as a social security payment and disability payments The processing of an EBT transaction is very similar to a debit card transaction It is required for this type of transaction to be swiped and face to face in a retail environment such as a grocery store A pin pad is usually required as well for terminals that will be processing EBT transactions EBT transactions are usually host based but it is advised to consult with the merchant service provider or payment processor representative on the topic of settlement close There are 4 basic tender types associated with EBT transactions Food Stamp Sale Processes a food stamp sale that deducts from the previous balance of the EBT card Food Stamp Return This action allows a merchant to run a credit back funds to the EBT card Cash Benefit This action allows transaction requests in relation to government program cash benefits Balance Inquiry Allows the merchant to view the balance on the EBT account 33
31. lt Constants section for a list of valid values and descriptions For approved transactions returns the authorization code from the issuing bank For declined transactions returns the reason why the transaction was declined if the issuing bank provides one or why the transaction was rejected This returns the last 4 digits of the card number used by the cardholder to perform this payment transaction This field displays the card type used in the payment transaction Please see CARD_TYPE list for valid values Returns the reference number associated with the transaction The reference number is assigned by the card associations The reference number is used to help identify the transaction and is useful for the cardholder and merchant when doing research This value is not returned with all transactions Returns the AVS response code from the issuing bank If performing Address Verification on card not present transactions this code indicates how well the AVS information passed in matches what the issuing bank has on file for the cardholder Consult the section Constants for a description of values that may be returned Returns the date that the transaction was processed This value is not returned by all processing companies Returns the ticket number or invoice of the transaction Returns the Internal Sequence Number which is an assigned unique number for each transaction Returns the Transaction Item number or the number
32. nent An IP address and Port specified in the setting configuration of the SmartPayments Admin Client is required to allow the POS application to open a port send the data stream with the required XML tags and wait on that same socket for a response to be returned with the appropriate payment processor information SmartPayments OCX This integration method utilizes a visual Active X component installed by the SmartPayments Admin Client installer in the Pivotal directory This OCX gives the advantage of allowing integrators built in hardware support to use with their third party POS integrations This will save time and resources integrating to a supported hardware device IP COM Allows the integrators to develop their POS applications to call specific SmartPayments Admin Client forms to process transaction requests The advantage of this integration method is that it saves time and resources developing homegrown forms because the POS application can just call the existing forms to handle transaction requests and response XML File Method Pivotal Payments Gateway Client XML File Method Integration Introduction This XML File format is a widely used format for many applications It is known to be an industry standard file format Support for this format was recently added to allow first time developers to the SmartPayments Client Manager to process transactions by sending a named file to a specified location and then retrieve the processed
33. ng String String String String Boolean String Description Credit I nput File inx The amount for tip adjustment This tag is only applicable to restaurant based merchant accounts Please see list of Action codes Tax Exempt Flag This flag is used to indicate if the purchase is tax exempt Used only for Commercial Card Transactions Valid Values 1 Purchase is tax exempt O Purchase is not tax exempt Please use this tag for follow on transactions specifically for a VOID transaction The information that needs to be passed in this needs to come from a Reference number from the output file of an Original Sale or Pre Authorization This allows for a value to be passed to Global Payments to specify if a card was present or not during the transaction Applicable Values 0 Not Present 1 Present This property is only applicable to Global Payments This property describes the status of the CVV value upon submitting a transaction request Applicable Values CVPresence NOTSUBMITTED CVPresence ILLEGIBLE CVPresence NOT PRESENT This property is only applicable to Global Payments This property is only applicable to credit card transactions types The tag lt FORCESNF gt Value lt FORCESNF gt when set to True will cause a transaction to be in store and forward mode and will get a response with a store and forward approval code This is applicable to payment server gateway users where store and forwar
34. not submitted with each transaction Note For manually keyed transactions TICKET_ NUM is required to qualify for the lowest transaction rates The raw MICR data from the bottom of the check Used for conversion transaction The state code of the state that issued the check writer s driver s license The state code is required for DL Driver s License Format 2 characters The driver s license number of the individual writing the check Max Length 20 characters The driver s license is required for DL Driver s License transactions and when performing Double ID transactions The Transit Routing Number ABA number that will be used when processing the transaction This value indicates which bank issued the check Max Length 9 characters This value is required for MICR transactions and when performing Double ID transactions The phone number of the individual writing the check Format digits only The phone number is required for COD Checks On Delivery Max Length 7 digits The date of birth of the check writer Format MMDDYY The birth date is required for DL Driver s License check transactions Max Length Exactly six characters The check number of the check that will be used when the transaction Max Length 10 characters Note To perform Double ID both the MICR and LICENSE fields must be populated These properties are required regardless of service type The user name is used to keep the transac
35. ntity of the cardholder Value s Returned CARD_ID_CODE String M card present unable to read Magnetic data N Card not present Z card signature terminal has a pin pad card signature no pin pad ACCT_DATA_SRC String Returns the entry method of the transaction ECOMM_GOODS_IND String Returns a value indicating whether the goods sold were digital or physical in an e commerce environment Debit File Layouts This section describes the tags required to process debit transactions When processing debit cards a PIN pad is required to allow the customer to enter their PIN Personal Identification Number In addition debit card information is always collected via a card swipe device never via keyboard entry Because of this a card reader is also required When processing U S debit card transactions merchants have the option of allowing the customer to receive cash back on a transaction For instance the customer purchases 50 of products and wants 25 cash back set the Amount to 50 00 and Cash Back to 25 00 This will withdraw a total of 75 from the debit card account 50 for the products and 25 for cash to give to the customer Debit Input File inx Data Tag Type Description Debit I nput File inx The action code that identifies what type of transaction ACTION String will be performed Consult the section Constants for a list of valid values The Debit card number that will be used when processing z the tran
36. or invoice number Transactions will decline if the TICKET_NUM is not submitted with each transaction Note For manually keyed transactions TICKET NUM is required to qualify for the lowest transaction rates The cardholder s name Max Length 20 characters The CVV2 value for the transaction The card verification value CVV2 for Visa CVC2 for MasterCard and CID for AMEX and Discover is a 3 or 4 digit number that is embossed in the signature panel for Visa MasterCard and Discover and on the front of the card for AMEX Max Length 4 characters CVV2 should only be passed on non swiped transactions The type of commercial card being submitted See the section Commercial Card Transactions for more information Max Length 1 character Valid values B Business P L G Purchase C Corporate F Fleet The Authorization code This value is returned by the issuing bank and should only be set in a transaction request if processing a Post Authorization and the Post Authorization is being used to add a Voice Authorization to the batch or to store a Voice Authorization The AuthCode property does not need to be set if the Post Authorization completes a standard Pre Authorization using the reference number value of the Pre Authorization See the section Follow On Transactions for more information Tag GRATUITY_AMNT TAX_EXEMPT TRANS_ID CARDPRESENT CVPresence FORCESNF USER_ID Data Type Stri
37. pen to buy amount and places the transaction in the open batch This action is commonly used in retail environments Eliminates a sale transaction from the open batch The funds will not be deposited into the merchant s bank account at settlement close Void Sale is typically used for returns usually same day or to correct cashier mistakes A Void Sale can only be done before settling closing of the batch this usually means the action has to be performed on the same day as the sale Used to refund money to the cardholder This action is typically used after the batch that contains the Sale or Post Authorization transaction has been settled or closed This action will increase the cardholder s open to buy amount once the batch containing the credit has been settled Removes a credit transaction from the batch This can only be done before the batch is settled closed this usually means the action has to be performed on the same day as the credit This transaction is not available with all processing companies If the Void Credit action is not available use the Void Sale action Diminishes the cardholder s open to buy amount It does not place a transaction in the open batch A Pre Authorization can be considered one of two steps of a sale A Pre Authorization reduces the limit to buy for only a set amount of time usually 7 10 days which is determined by the credit card s issuing bank To place the transaction in the open batch a fo
38. put File inx Data Tag Type CARDPRESENT String Description Credit I nput File inx This allows for a value to be passed to Global Payments East to specify if a card was present or not during the transaction Applicable Values 0 Not Present 1 Present This property is only applicable to Global Payments EAST Tag CVPresence COMMAND ACCT_NUM EXP_DATE MANUAL_FLAG TRANS_ AMOUNT REFERENCE TRACK_DATA CUSTOMER_CODE Data Type String String String String String String String String String Description Credit I nput File inx This property describes the status of the CVV value upon submitting a transaction request Applicable Values CVPresence NOTSUBMITTED CVPresence ILLEGIBLE CVPresence NOT PRESENT This property is only applicable to Global Payments EAST The action code that identifies what type of transaction will be performed Consult the Constants for a list of valid values The credit card number that will be used when processing the transaction Max Length 20 characters Example 5439750001500347 The expiration date associated with the credit card number that will be processed Must be exactly four characters long Format MMYY Example 1208 Flag that indicates whether the transaction was manually entered or swiped If the transaction was swiped the TRACK_DATA property must also be set Valid values 0 manual transaction 1 sw
39. ransaction in the settlement batch A Verify transaction is followed by a Force which is equal to a Check Sale Debit Transaction Definitions The items listed in the table are the supported debit card commands with their definitions Sale Diminishes the checking account balance of the customer Void Removes a Sale transaction from the open Batch or can also reverse a Return transaction The debit void is not supported by all payment processors Return This action allows a merchant to credit funds back into the card holder s debit account 31 Debit Cards are also known as check cards and their use has proliferated greatly in the last few years Debit Cards are more akin to checks due to the fact that when used for a purchase this action immediately deducts the balance of the purchase from the checking account of the card holder ATM debit cards can also be used to withdraw cash from the banks Notes to Integrators 1 If you are planning to integrate debit transactions please be aware that true debit transactions are in person requiring a card swipe and entry of the card holder s PIN This is true unless the merchant is enrolled with a PIN less Debit Account Please consult your Merchant Service Providers for details about this program Please be aware that a pin pad is required for Debit card transactions and make sure that these have been injected with encryption keys by your merchant s payment processor networ
40. rchant s industry type is MOTO or eCommerce Max Length 40 characters Note The characters that are appended to the beginning and ending of track II usually and should not be passed in Example 5424180279791765 08121011000001234567 The Authorization code This value is returned by the issuing bank and should only be set in a transaction request if processing a Post Authorization and the Post Authorization is being used to add a Voice Authorization to the batch or to store a Voice Authorization The AuthCode property does not need to be set if the Post Authorization completes a standard Pre Authorization using the internal sequence value of the Pre Authorization See the section Follow On Transactions for more information Flag Indicating whether the transaction should be forced for Paymentech Valid Values 1 force O don t force These properties are the minimum required to process a Sale or Pre Authorization transaction This field is required when MANUAL_FLAG value is set to 1 Gift Card Output File OUX Tag RESULT Data Type String Description Gift Output File OUX Returns the result which indicates the transaction s status upon completion Refer to the Transaction Result Constants section for a list of valid values and descriptions 18 Data Tag Type Description Gift Output File OUX For approved transactions returns the authorization code from the issuing bank For de
41. rd tendered is a procurement purchasing business government or commercial card This action can be considered the second half of a sale This follow on transaction must occur before a Pre Authorization can be settled closed This Post Authorization may also be used to place an approved Voice Authorization in the batch Two additional values the Tax amount and customer code must be passed with this type of card in order for the merchant to qualify for the lowest transaction rate Used only in a restaurant environment this action allows a server to authorize the amount of the meal plus the gratuity and place the entire amount in the batch When settled the amount plus the gratuity is deducted from the cardholder s account Note Pre Authorization cannot be voided 30 Check Transaction Definitions Check Guarantee and Check Verification are transactions that do not involve an electronic transfer of funds To determine that the check writer has an existing account and does not have current outstanding checks check verification can be performed by the merchant The Check Guarantee service extends the guarantee that the merchant will get a percentage of his money even if the check bounces There is a higher fee associated with this check guarantee service depending on the check processor the merchant is associated with Check Verification and Check Guarantee are single step processes and there are three types of check transactions Chec
42. ry mode that is associated with the transaction This value is not returned by all processing companies Returns the Time of the transaction This value is not returned by all processing companies Returns the Authorization Characteristics Indicator is that is provided by the card associations This value is stored for settlement Returns the response code that is provided by the processor This value is not returned by all processing companies Returns the record number of the transaction in the reversal file Will return 1 if the processor doesn t support reversals This value is not returned by all processing companies Returns the type of commercial card that was used for the transaction This value is not returned by all processing companies Returns the CVV2 CVC2 CID response code from the issuing bank If performing CVV2 CVC2 CID validation on card not present transactions this code indicates if the CVV2 CVC2 CID code passed in matches what the issuing bank has on file for the cardholder Consult the section Constants for a description of values that may be returned Returns the error code applicable to the transaction It will only return a value if the error has occurred Returns the description of the error code and will only return a value if an error has occurred Return this tag if and only if the receipt was successfully generated and if this option is enabled in the Smart Client user interface Returns sever
43. saction ACCT_NUM String Max Length 20 characters Example 5439750001500347 12 Tag USER_ID EXP_DATE MANUAL_FLAG TRANS_ AMOUNT TRACK_DATA TICKET_NUM CARDHOLDER KEY_SERIAL_NUM Data Type String String String String String String String String Description Debit I nput File inx This is a new feature that will allow integrators to specify which account they would like their transaction to be associated with if they have multiple merchant accounts set up on their client The limitation of this feature is that the merchant needs to be set up with a Payment Server merchant account The valid values of this USER_ID are the index value of the profile representing that merchant account For example if there are two profiles on the account one for VITAL and a second profile for Global Payments Vital Profile Index 0 Global Payments Index 1 The integrator can then choose to pass 0 to represent the profile index of VITAL or 1 for Global to send transactions to the respective account The expiration date associated with the Debit card number that will be processed Must be exactly four characters long Format MMYY Example 1208 Set this property if there is an expiration date associated with the Debit card Flag that indicates whether the transaction was swiped or manually entered This property must be set to 1 swiped and the TRACK_DATA property must also be set
44. t identifies the network on which the transaction was approved This section provides information on the tags that are required to process check transactions Check Input File INX Tag ACTION ACCT_NUM USER_ID MANUAL_FLAG TRANS_ AMOUNT ZIP_CODE Data Type String String String String String String Description Check Input File inx The action code that identifies what type of transaction will be performed Consult the Constants for a list of valid values For Check MICR or Double ID The account number that will be used when processing the transaction Max Length 20 characters This is a new feature that will allow integrators to specify which account they would like their transaction to be associated with if they have multiple merchant accounts set up on their client The limitation of this feature is that the merchant needs to be set up with a Payment Server merchant account The valid values of this USER_ID are the index value of the profile representing that merchant account For example if there are two profiles on the account one for VITAL and a second profile for Global Payments Vital Profile Index 0 Global Payments Index 1 The integrator can then choose to pass 0 to represent the profile index of VITAL or 1 for Global to send transactions to the respective account Flag that indicates whether the transaction was manually entered or swiped If the transaction
45. that is associated with the transaction in the settlement file This value is not returned by all processing companies Returns the active batch number for the transaction This value is not returned by all processing companies Returns the Transaction Identifier that is returned from the processor This value is not returned by all processing companies Returns the Transaction Indicator Code that is returned from the processor The Transaction Indicator Code is a Validation code for VISA MasterCard This value is not returned by all processing companies Returns the IND code The IND code is a transaction description code and an Interchange compliance field This value is not returned by all processing companies Returns the Market Specific Indicator This value indicates the transaction s market segment This value is assigned by the card associations and is not returned with all transactions Returns the Retrieval reference number This value is not returned by all processing companies 10 Tag PEM TIM ACI PROC_RESP_CODE REC CMRCL_TYPE CVV2_CODE ERRORCODE ERRORDESC MERCHRECEI PT CUSTRECEI PT PURCH_CARD_ TYPE GRATUITY_AMNT RESULT_CODE CMRCL_FLAG NET_ID Data Type String String String String String String String String String String String String String String String String Description Charge Output File oux Returns the POS ent
46. tion associated with the correct terminal COD required for Checks On Delivery DL required for Driver s License MICR required for MICR Check Output File OUX Tag RESULT Data Type String Description Check Output File oux Returns the result which indicates the transaction s status upon completion Refer to the Transaction Result Constants section for a list of valid values and descriptions 16 Tag AUTH_CODE REFERENCE TRANS_ DATE TICKET INTRN_SEQ_NUM PROC_RESP_CODE Gift File layouts Data Type String String String String String String Description Check Output File oux For approved transactions returns the authorization code from the issuing bank For declined transactions returns the reason why the transaction was declined if the issuing bank provides one or why the transaction was rejected Returns the reference number associated with the transaction The reference number is assigned by the card associations The reference number is used to help identify the transaction and is useful for the cardholder and merchant when doing research This value is not returned with all transactions Returns the date that the transaction was processed This value is not returned by all processing companies Returns the ticket number or invoice of the transaction Returns the Internal Sequence Number which is an assigned unique number for each transaction

Document Version 2.7.6

Contents

Download Pdf Manuals

Related Search

Related Contents