EFT with BS Payone (B+S Card Service)
Prism 1.14.7 and BS Payone PDF
Disclaimer: BS Payone is available for use with Retail Pro outside the U.S. only.
This topic has information about configuring Prism for use with BS Payone (formerly B+S Card Service). The plugin is for use with BS Payone and the VeriFone VX-820 Duet device. This plugin handles:
- Credit card sales
- Returns (Refunds)
- Voids (‘Payment Reversals')
- End-of-Day (‘Reconciliation with Closure')
The plugin for BS Payone automatically prints the text-based Merchant and Customer receipt designs that are sent in the transaction response coming from BS Payone.
BS Payone includes numerical return codes with each response. These can be translated by the end-user. At the end of this topic is a section with translation information for German, French and Dutch.
Basic Steps
Each of the basic steps listed below are explained in greater detail in the sections that follow.
- Enable and Configure the B+S EFT Customization at the Subsidiary level.
- Create the B+S Customization.
- Enable and Configure the B+S Customization at the workstation level.
- (Optional) Add Localization (translation) strings (See Appendix A.)
Important Note about Stopping/Restarting Proxy and BandSCardService.exe
If you stop the Prism Proxy for whatever reason (e.g. configuration changes), you must manually stop the BandSCardService.exe using Windows Task Manager. If you stop the Proxy and forget to stop the BandSCardService.exe, then when you restart the Proxy, the Proxy will not be bound to the plugin and therefore the EFT service will not work. If you are in this situation, the solution is to stop the Proxy again, stop BandSCardService.exe using Task Manager, and then restart the Proxy. If you stopped the plugin when you stopped the proxy, then when you restart the Proxy, BandSCardService.exe will restart automatically.
Step 1. Create B+S Customization
1. Navigate to ‘Admin Console' > Customizations. You will see 1 existing customization (‘Shopperdisplay'). Leave that. It isn't running so it will not use any resources. You will create a new one for BS Payone.
2. Click Add New Customization. Add the following values in the listed fields:
Name = BS Payone
Version = 1.0.0
Developer ID = 002
Customization ID = 002
Control Address = 127.0.0.1
Control Port = 5001
Manifest File Location =
C:\Program Files (x86)\RetailPro\PrismProxy\BandSCardService.exe
(assuming default install path)
Location drop down box = Local
Timeout = 60000
Retry = 0
3. Check the check boxes for ‘Auto Start' and ‘Auto Stop'
4. Click ‘Save' to save your changes. The customization is added to the list.
Sample Customization Configuration screen:
Timeout Value
The Timeout value is the time the Proxy will wait for a response from the BS Payone terminal. The value is in milliseconds. You can pick any reasonable value, as long as the value is longer than the value specified for the Proxy timeout (prism waits for the Proxy). The maximum timeout setting is 150,000 ms (2.5 minutes).
Step 2. Enable, Configure B+S at Subsidiary Level
Select Node Preferences > Transactions > Tenders > EFT Server Configuration. Select B+S Card Service from the drop-down.
Stop BandSCardService.exe if starting/stopping Proxy
If you stop the Prism Proxy for whatever reason (e.g. to apply configuration changes), you must manually stop the BandSCardService.exe using Windows Task Manager. If you stop the Proxy and forget to stop BandSCardService.exe, when you restart the Proxy the Proxy will not be bound to the plugin and the EFT service will not work. If you are in this situation, the solution is to stop the Proxy again, stop BandSCardService.exe using Task Manager, and then restart the Proxy. If you stopped the plugin when you stopped the proxy, then when you restart the Proxy, BandSCardService.exe will restart automatically.
Step 3. Enable, Configure BS Payone at Workstation Level
NOTE: After making and saving the changes in the next section, you must close the browser and restart the Proxy, then log in again. In the Admin Console, navigate to your workstation level by double-clicking on the SBS, Store and Workstation level.
1. In the Admin Console, drill down to the desired Sub and Store.
2. Click the Edit button (pencil icon) for the desired Workstation
3. Click the ‘Hal Settings' tab. Select the HAL identified by your Workstation's name and proxy number from the dropdown.
4. Click the ‘Customizations' tab. Click the ‘Add Customization' button.
5. In the drop down box, you will see the Customization you just created. Select it. In the ‘Local Path' field, enter: C:\Program Files (x86)\RetailPro\PrismProxy\BandSCardservice.exe
6.In the ‘Configuration data' field, you will have to enter data that consists of both System parameters and the localization (language) you wish to use. See Appendix A. Translating Authorization Response Codes for an example of localization data.
Add the below strings ‘as is' with values. Do not change the ‘DevicePort', as this address is set by B+S in the Terminal.
DeviceAddress=
DevicePort=20002
RequestTimeout=60000**
CurrencyType=EUR***
**= The RequestTimeout is the time Prism will wait for a response from the Proxy. The value is in milliseconds. You can pick any reasonable value, as long as the value is shorter than the value specified for the B+S timeout in the Customization you created in Step 4 (the Proxy waits for the B+S Terminal).
***=The CurrencyType s is the default currency that Prism sends. However, you can change this to the official currency used in your area, e.g. GBP, etc. Enter the standard three-letter ISO currency abbreviation.
If Blank Screen is Displayed Upon Login
After completing all configuration, if you find that upon launching Prism the browser screen is blank, you will need to clear the cache. In Chrome, press Shift+Ctrl+Delete to display the Clear browsing data screen. Select to clear data from the beginning of time and make sure the first four checkboxes are selected. Click Clear Browsing Data.
Document Designs
Since its first release, the BS Payone document design has changed.
In the first release of the BS Payone plugin, the BS Payone response would be parsed field by field, and each field was individually added to the receipt design, based on industry requirements. Retail Pro included basic receipt designs with all required fields in the design. This has the disadvantage that when industry requirements change, the receipt designs would have to be modified.
With subsequent releases, however, Retail Pro has instead opted to start using the BS Payone text-based Merchant and Customer receipt blocks that are included in each transaction response (approved, declined, etc.). This, of course, takes any receipt requirements out of the hands of the merchant, as the receipt blocks are used verbatim, so any changes by BS Payone would automatically be included.
These BS Payone receipt text blocks are saved in the DB (EFTDataBSCust for the customer copy, EFTDataBSMer for the merchant copy) . These 2 fields are on the default receipt design.
Each text block field holds all the required EFT fields (EFTData0-EFTData9) that are returned to the Verifone terminal during authorization. As long as the text block fields are included in the design, retailers can be sure that all the required EFT fields will be included in the printed document.
Besides the complete receipt text blocks , the receipt fields for the of individual EFT fields are still available. Merchants can still opt to include the individual fields in their receipts. However, content accuracy of the information in the individually parsed fields may differ with information in the predefined receipt text
Keep in mind that there are there are two types of receipts for B+S:
- Receipts: These are regular sale and return receipts
- Declined Tender Receipts: These are special receipts that can be printed when an EFT tender is declined
You will find separate areas for each of these types in Prism Document Designer.The following table lists the receipt designs for use with the Plugin. All of these receipt designs include the text block fields described above.
| Design | Description |
|---|---|
| B+S Receipt 40-col | Basic 40-column receipt design for BS Payone users. |
| B+S Receipt 40-col - OPOS | This version of the 40-column receipt is specially designed for OPOS printers. |
| B+S Declined Receipt 40col | This receipt design is used when printing "declined tender" receipts. Declined tender receipts are receipts that can be printed when an EFT authorization is declined. |
| B+S Declined Receipt 40-col - OPOS | This version of the declined tender receipt is specially designed for OPOS printers. |
About the EFTDataBSMer, EFTDataBSCust, Extra Str Field 29 and Extra Str Field 30 fields
The EFTDataBSMer, EFTDataBSCust, Extra Str Field 29 and Extra Str Field 30 fields are text-block fields that store the entire data stream returned to the Verifone VX-820 terminal. This ensures that any required EFT data is included. In the legacy receipt designs, the data is stored in multiple fields and this sometimes resulted in confusion about which fields are needed in designs. Including all of the BS Payone EFT data fields in a single block saves retailers from having to worry about which fields to include/exclude.
The following table lists the text block fields and their intended use. These designs can be used, modified, or used as a basis if you would like to create new designs.
The EFTDataBSMER and EFTDataBSCust fields are saved in the database for each transaction in the invc_tender table. The Extra String fields 29 & 30 are not saved to the database; these fields are only available at the time of the Decline.
| Text Block Data Field | Description |
|---|---|
| EFTDataBSMER | Text block that contains all the individual EFT fields used by BS Payone for merchant receipts. |
| EFTDataBSCust | Text block that contains all the individual EFT fields used by BS Payone for customer receipts. |
| Extra Str Field 29 | (Declined Receipts) Text block that contains all the individual EFT fields used by BS Payone for Declined Tender receipts (Merchant copy) |
| Extra Str Field 30 | (Declined Receipts) Text block that contains all the individual EFT fields used by BS Payone for Declined Tender receipts (Customer copy) |
Replication of EFTDataBSCust and EFTDataBSMer fields
The EFTDataBSCust and EFTDataBSMer fields are CLOB fields. CLOB fields are not currently replicated between Prism and Retail Pro 9. If you print a receipt in RP Prism that uses the EFTDataBSCust and EFTDataBSMer fields, when the receipt is replicated to RP 9 and a user prints the receipt, the receipt will not print correctly. However, if the user in RP 9 prints the receipt using an OLD design (with individual EFTData fields instead of the EFTDataBSCust and EFTDataBSMer text-block fields), then the receipt will print correctly.
Individual EFT Fields
The following are the individual EFT fields currently used in RP Prism and contained in the text block fields. The same information for regular Receipts in the following tables is also available for the B+S EFT Declined Receipts; however, this design is located in the ‘Information Receipts' group in the ‘Extra Str Field 10' through ‘Extra Str Field 19' fields.
INVC_TENDER table
| Doc Designer Field | Information Displayed |
|---|---|
| Doc No. | Displays the last four digits of the card number. |
| EFTDATA0 | B+S Timestamp |
| EFTDATA1 | Card Circuit (Visa, Master, etc.) |
| EFTDATA2 | Result Code. |
| EFTDATA3 | Transaction Request ID. |
| EFTDATA4 | Total Amount Currency |
| EFTDATA5 | TA-No |
| EFTDATA6 | Card Expiration Date |
| EFTDATA7 | Terminal ID |
| EFTDATA8 | The specific receipt number returned by B+S Card Service. |
| EFTDATA9 | Merchant ID |
| EFTDATA10 | Additional data that is needed for printing on the invoice. |
| EFTDATA11 | Additional data that is needed for printing on the invoice. |
| EFTDATA12 | Additional data that is needed for printing on the invoice. |
| EFTDATA13 | Additional data that is needed for printing on the invoice. |
| EFTDATA14 | Additional data that is needed for printing on the invoice. |
| EFTDATA15 | Additional data that is needed for printing on the invoice. |
| EFTDATA16 | Additional data that is needed for printing on the invoice. |
| EFTDATA17 | Additional data that is needed for printing on the invoice. |
| EFTDATA18 | Additional data that is needed for printing on the invoice. |
| EFTDATA19 | Additional data that is needed for printing on the invoice. |
| EFTDATABSMER | CLOB field that has all the individual fields. |
| EFTDATABSCUST | CLOB field that has all the individual fields. |
INVC_ITEM table
| Doc Designer Field | Information Displayed |
|---|---|
| Doc_No | Displays the last four digits of the card number. |
| GIFT_EFTDATA0 | B+S Timestamp |
| GIFT_EFTDATA1 | Card Circuit (Visa, Master, etc.) |
| GIFT_EFTDATA2 | Result code. (See Translating Result Codes section at end of document) |
| GIFT_EFTDATA3 | Transaction Request ID |
| GIFT_EFTDATA4 | Total Amount Currency |
| GIFT_EFTDATA5 | TA-No |
| GIFT_EFTDATA6 | Card Expiration Date |
| GIFT_EFTDATA7 | Terminal ID |
| GIFT_EFTDATA8 | The specific receipt number returned by B+S Card Service. |
| GIFT_EFTDATA9 | Merchant ID |
| GIFT_EFTDATA10 | Additional data that is needed for printing on the invoice. |
| GIFT_EFTDATA11 | Additional data that is needed for printing on the invoice. |
| GIFT_EFTDATA12 | Additional data that is needed for printing on the invoice. |
| GIFT_EFTDATA13 | Additional data that is needed for printing on the invoice. |
| GIFT_EFTDATA14 | Additional data that is needed for printing on the invoice. |
| GIFT_EFTDATA16 | Additional data that is needed for printing on the invoice. |
| GIFT_EFTDATA17 | Additional data that is needed for printing on the invoice. |
| GIFT_EFTDATA18 | Additional data that is needed for printing on the invoice. |
| GIFT_EFTDATA19 | Additional data that is needed for printing on the invoice. |
| GIFT_EFTDATABSMER | CLOB field that has all the individual fields. |
| GIFT_EFTDATABSCUST | CLOB field that has all the individual fields. |
EFTData10 through EFTData19 Fields
It is important to note that the text block fields include not only all the EFT fields currently being used (EFTData0-EFTData9), but additional fields not yet used (EFTData10-EFTData19). The extra fields are included in the event BS Payone requires additional fields in the future. Note: The extra fields do not print or affect the design in any way until such time as they are implemented by Cayan and actually used in the RIL database. If BS Payone decides to require additional fields, the data stream sent back by BS Payone will automatically reflect this and be included in the text block. However, for these new fields to be correctly populated with new data, a new release would be required.
Additional Fields such as Auth, Card Type, Cardholder Name
In addition to the fields listed above, you will also probably want to include fields such as Auth, Card Type, and Cardholder Name in any custom designs that you create.
Assign Receipt Design to Workstation
When printing a receipt, users must select a receipt design (or accept the default assigned design). RIL includes a set of predefined receipt designs specially configured for the BS Payone Plugin. You can assign a default design in the workstation record, or select the desired design at run-time when printing the receipt.
Required Driver Configuration
The B+S 40 Col receipt and the B+S Declined receipt designs each include multiple pages (3 and 2 pages, respectively). To print these designs as separate receipts and not one long receipt, you must adjust the following printer driver settings.
- Set the printer to cut after each page instead of after each document
- Set the max paper length to a setting that you are sure will be longer than the longest receipt you normally print.
NOTE: Some printers may be re-branded (cloned) printers from another make of printers. If the driver you are using does not show the settings for the printer cutter or max paper length, look for an updated driver, or find a driver from the original make.
Cut Paper Setting
The B+S 40 Col receipt will print the "item" receipt first, followed by the merchant credit card receipt and then the customer credit card receipt. To cut after each page of the design instead of at the end of the complete physical receipt (which includes 3 receipts as explained above), the driver needs to be set to cut at the end of each ‘page' and not at the end of the ‘doc'. This setting may appear in several places in the driver.
Roll (Max Paper Length)
The Roll setting controls the default max paper length. In the driver, the default setting is 8 inches. This is not long enough to properly cut the receipt after the barcode , so you should set the max paper length to some larger value (e.g. 150 inches). Setting the default max paper length to a longer value will make sure my receipt would be shorter than the max length. This setting may appear in several places in the driver.
The Roll setting can impact when a receipt is cut. If the Roll setting is less than the length of some receipts you will be printing, then the paper cuts will be made at undesired locations. If you set the Roll value to a length that is greater than any single receipt you will print, the paper cuts will be made at the appropriate places. In the screenshot below, the Roll dropdown is set to 157 inches, which would be a receipt that consists of hundreds of itesm. Because such a large value is selected, the paper cuts will be made at the appropriate place. Keep in mind that you might have to adjust this value in multiple places in the driver settings.
Modify Receipt Designs
This section explains how to modify the predefined B+S receipt designs, if needed. You must install Prism Document Designer using the Autorun.exe file.
- Launch Document Designer and log in.
- In the Area dropdown, select the Receipt area (or Information Receipts tab). Select the desired receipt design in the Document dropdown.
- Click the Edit button.
- Navigate to the desired fields.
- Drag and drop elements onto the desired area of the design. Resize and reposition as needed.
- Save the changes.
Localization
The Plugin allows you to localize the Authorization Return codes in the response from BS Payone, so that instead of a return code of ‘0', the cashier will see ‘Approved'. This will also be the value stored in the database. Be aware that if you do not enter any localization strings at all, the bare authorization return code will be shown for any transaction and stored in the database.
Plugin-specific Log Settings
Users can set logging levels for individual plugins via the Prism Proxy "right-click" configuration settings.
The Configuration Settings screen has separate tabs for the Prism plugins that are installed with Proxy. To access the settings, start the Proxy, then right-click on the proxy icon and select Configure
Select the tab for the BandSCardService plugin and update the Log Level and any other log settings as needed. Settings configured for an individual plugin will override the default logging settings defined in PrismLogging.ini, as follows:
If no setting is made for a plugin, the plugin's log settings default to the settings made for Proxy.
The Proxy log settings themselves, as displayed in this UI, default to the "Global" settings in PrismLogging.ini until they are manually changed to different settings.
Tax Rules: Char and Message
DevTrack ID#22233
The fields Char (or Indicator) and Message are added to the Tax Rules Grid in Admin Console > Node Preferences > Taxes > Tax Areas. These were a feature of Retail Pro 9 tax rules. Some countries have a tax requirement to show items that are taxable or non-taxable on the Receipt when both types are sold in the same transaction. The Tax Char (or Indicator) field is used to satisfy this requirement. In the RPS.tax_code_rule table, the fields are labeled Reference (Char) and Legend (Message).
BandS.ini
The BndS.ini file has configuration settings for the Plugin. This file is stored in the \ProgramData\RetailPro\HardwareServices\Conf folder. Refer to the following table for information about the settings in the BandS.ini file:
| Option | Value | Description |
|---|---|---|
| LogLevel | 0-3 | 0=None; 1=Minimal; 2=Regular; 3=Verbose |
| LiveLogging | True/False | Use CodeSite Live Logger |
| CodeSiteActive | True/False | Log to CodeSite log (CSL) file |
| DebugStackTraceActive | True/False | Enable Stack Trace in CodeSite log |
| RetainXLogs | Integer | Number of previous logs to preserve. Default = 9 |
| BufferSize | Integer | Size of log buffer in lines; 0 if no buffering used Customization. Default = 0 |
| IP Address | ex. 10.50.101.140 | IP Address of B+S device |
| IPPortList | ex. 5001,5002 | Comma-separated list of ports, one per proxy. |
Translating Authorization Return Codes
The result code (or translated string) is populated in the EFTDATA2 field. If the code returned is in the list, the corresponding text string will be displayed. If the returned code is unknown or is in the list but does not have a text string associated with it, the return code will be displayed instead.
Note: You can add the EFTDATA2 field to document designs (using DocumentDesigner.exe).
Adding a Translation
You can display result codes in other languages by adding the language and result code translations to the EFT_BS.ini file. That new language will then be available in the language dropdown box in the Plugin configuration screen.
- Open the EFT_BS.ini file and navigate to the [LANGUAGES] section. Add the new language to the list. In this example, the language "Nederlands" has been added to the default languages of German, English and French.
- Create a new section for the language and add translated strings for each result code. Save the changes.
- Go back to the BS EFT Configuration screen in Workstation Preferences. The language you added is now available in the dropdown. Select the language and save the changes.
At the top of the localization file are the following settings:
Device Address: [e.g. 10.50.101.140]
DevicePort=20002
RequestTimeout=60000 **
CurrencyType=EUR***
**= this is the time Prism will wait for a response from the Proxy. The value is in milliseconds. You can pick any reasonable value, as long as the value is shorter than the value specified for the B+S timeout (the Proxy waits for the B+S Terminal), specified in B.
***=This is the default currency that Prism sends. However, you can change this to the official currency used in your area, e.g. GBP, etc.
| Return Code | English | French | Dutch | German |
|---|---|---|---|---|
| default | Approved | Autorisée | Aangenomen | Autorisierung erfolgt |
| 0 | Approved | Autorisée | Aangenomen | Autorisierung erfolgt |
| A0 | Approved | Autorisée | Aangenomen | Autorisierung erfolgt |
| A1 | Approved | Autorisée | Aangenomen | Autorisierung erfolgt |
| A2 | Approved | Autorisée | Aangenomen | Autorisierung erfolgt |
| A3 | Approved | Autorisée | Aangenomen | Autorisierung erfolgt |
| A4 | Approved | Autorisée | Aangenomen | Autorisierung erfolgt |
| A5 | Approved | Autorisée | Aangenomen | Autorisierung erfolgt |
| A6 | Approved | Autorisée | Aangenomen | Autorisierung erfolgt |
| 2 | Not accepted | Pas acceptée | Niet geaccepteerd | Vorgang nicht möglich |
| 3 | System malfunction | système défaillant | Systeem storing | Systemfehler |
| 4 | Card not admitted | Carte pas admise | Kaart Niet toegestaan | Karte nicht zugelassen |
| 5 | Declined | Déclinée | Afgekeurd | Vorgang abgelehnt |
| 6 | System malfunction | système défaillant | Systeem storing | Systemfehler |
| 12 | Invalid transaction | Transaction invalide | Ongeldige transactie | Transaktion ungültig |
| 13 | Not accepted | Pas acceptée | Niet geaccepteerd | Vorgang nicht möglich |
| 14 | Invalid card number | numéro de carte invalide | Ongeldig kaartnummer | Kartennummer ungültig |
| 21 | Not accepted | Pas acceptée | Niet geaccepteerd | Vorgang nicht möglich |
| 30 | System malfunction | système défaillant | Systeem storing | Systemfehler |
| 33 | Expired card | Carte expirée | Kaart verlopen | Karte verfallen |
| 34 | Transaction not permitted | Transaction pas permise | Transactie niet toegestaan | Transaktion nicht möglich |
| 40 | Invalid function | Fonction invalide | Ongeldige Functie | Funktion ungültig |
| 43 | Transaction not permitted | Transaction pas permise | Transactie niet toegestaan | Transaktion nicht möglich |
| 51 | Not accepted | Pas acceptée | Niet geaccepteerd | Vorgang nicht möglich |
| 54 | Expired card | Carte expirée | Kaart verlopen | Karte verfallen |
| 55 | Incorrect PIN | NIP erroné | Foute PIN | Geheimzahl falsch |
| 56 | Invalid card | Carte invalide | Iongeldige Kaart | Karte ungültig |
| 57 | Wrong card | Fausse Carte | Kaart niet in orde | Falsche Karte verwendet |
| 58 | Declined | Déclinée | Afgekeurd | Vorgang abgelehnt |
| 59 | Not accepted | Pas acceptée | Niet geaccepteerd | Vorgang nicht möglich |
| 62 | Card not admitted | Carte pas admise | Kaart Niet toegestaan | Karte nicht zugelassen |
| 64 | Original amount incorrect | Montant initial erroné | Origineel bedrag incorrect | Betr. abweich. v. Originaltr |
| 75 | PIN Try Limit exceeded | Limite dépassée de NIP | Aantal PIN Pogingen overschreden | Geheimzahl zu oft falsch |
| 84 | Pin not activated | NIP non activé | PIN niet geactiveerd | PIN nicht aktiv |
| 85 | Cashback not possible | Cashback pas permis | Cashback not mogelijk | Cashback nicht möglich |