Browser-Based POS systems (BBPOS)

The Cardknox solution for browser-based POS systems (BBPOS) is a tray application that runs in the background of your computer. It acts as a local server, allowing a POS application opperating out of a browser to accept chip-based EMV (Europay, MasterCard, Visa) payments while remaining out of PCI scope. Our BBPOS solution supports all major terminals including PAX, Verifone, and, Ingenico, and ID TECH. See www.cardknox.com/supported-emv-equipment for a full list of our supported devices.

Configuration

To configure the BBPOS application:

1. Download and install Cardknox BBPOS (PaymentEngineExt) from the provided link. BBPOS download

2. Follow the installation prompts.

3. When asked for the "Software name," enter "BBPOS."

4. Provide your Cardknox key when prompted.

5. BBPOS will now run in the background and can be found in the system tray

Transaction Flow

1. The POS sends an HTTP POST request containing transaction information, such as the transaction amount, to the local host https://localemv.com:8887. Note: Transaction details should be in URL encoded Key-Value Pairs (KVP).

2. Our BBPOS application receives the request and communicates with either the terminal or a pop-up window on the screen.

3. The customer inserts their credit card into the terminal or keys the card number into the pop-up window.

4. The transaction data is transmitted to the Cardknox gateway for authorization.

5. When the transaction is complete, our BBPOS application sends back the transaction authorization details to your browser in the HTTP response through a redirect URL or AJAX. Transaction results are returned in the HTTP response in KVP format unless otherwise using xResponseFormat. See the Transaction Settings Table for more information.

6. To cancel a currently processing transaction, send xCancel=1 to host https://localemv.com:8887.

7. You can find available and required commands and parameters at https://kb.cardknox.com/api/ . See the Custom Device Commands Table for BBPOS specific commands.

8. The transaction can be redirected to a URL specified in xRedirectURL. See the Transaction Settings Table for more information.

9. Go to https://www.cardknox.com/bbpos/request-redirect.htm for a sample implementation using a redirect.

10. Go to https://www.cardknox.com/bbpos/request-ajax.htm for a sample implementation using AJAX.

Transaction Settings

You can configure transaction setting in the application setting file (right-click on Payment Engine in the system tray and choose options), or in a transaction request. In the case of a conflict, settings that are applied in the transaction request will override settings applied in the setting file. Use 1 and 0 for Boolean variables.

Settings File Name	Transaction Request Name	Parameter Description
xKey	xKey	Cardknox API key
DeviceName	xDeviceName	Name of device (see list of device names here)
DeviceCOMPort	xDeviceComPort	USB COM port assigned to device
DeviceBaud	xDeviceComBaud	Device baud rate
DeviceParity	xDeviceComParity	Device parity
DeviceDataBits	xDeviceComDataBits	Device data bit
DeviceIP	xDeviceIPAddress	IP address assigned to device
DevicePort	xDeviceIPPort	IP port assigned to device
Device_Timeout	xDeviceTimeOut	set amount of time to wait from transaction
RequireAVS	xRequireAVS	Forces user to enter cardholder to enter AVS info for keyed transactions (Windows Only)
RequireCVV	xRequireCVV	Forces user to enter cardholder to enter card CVV for keyed transactions (Windows Only)
EnableDeviceInsertSwipeTap	xEnableDeviceSwipe	Enables device transactions
RequirePin	xRequirePin	Requires a PIN for debit enabled cards
RequireSignature	xRequireSignature	Requires a signature
EnableWelcomeScreen	xEnableWelcomeScreen	If set to false, will disable device welcome screen
PrinterName	N/A	Sets printer to which receipts will be sent
ExitFormIfApproved	xExitFormIfApproved	Exits payment form after transaction approval without user interaction (Windows only)
ExitFormIfNotApproved	xExitFormIfNotApproved	Exits payment form after transaction decline without user interaction (Windows Only)
ExitFormOnDeviceError	xExitFormOnDeviceError	Exits payment form after transaction error without user interaction (Windows Only)
EnableSilentMode	xEnableSilentMode	Payment form will not appear. Transaction will be handled solely on device.
EnableKeyedEntry	xEnableKeyedEntry	Disables keyed transaction on payment form, but does show form. Transaction will be handled solely on device.
EnableAmountConfirmationPrompt	xEnableAmountConfirmationPrompt	The device will prompt for a confirmation with the amount,
N/A	xResponseFormat	Specifies response format. Available formats are KVP, JSON, XML.
N/A	xRedirectURL	Species a URL to which user will be redirected to upon completion of the transaction.
CloseApplicationOnSessionEnd	N/A	Closes the application and prevents the application from running when screen is locked

Custom Device Commands

These commands can be used to transport custom data to or from the device. They should be sent in the xCommand variable. These are standalone commands and are not used during a transaction. Appropriate device variables (xDeviceName, xIP, etc.) must be sent in. For commands that expect a payload, send in the payload as an xDeviceData variable.

Command Name	Description
Device_ShowWelcomeScreen	Displays welcome screen on the device
Device_SendData	Sends data to device. Does not expect a response.
Device_GetData	Requests data from device
Device_GetFormEvent	Requests form data from the device
Device_GetSignature	Displays signature prompt on device. Returns Base64 encoded string. xDeviceData can be used to specify a location where signature will be stored as PNG file. xSignatureMessage can be used to display a signature message.
Device_ShowItems	Show the items during a transaction. Required fields xSerializationType=JSON, xAmount and xData with items in JSON format. Ex [{'xdescription':'Apples','xqty':1,'xunitprice':'.40'}, {'xdescription':'Oranges','xqty':2,'xunitprice':'.50'}]
Device_GetSignatureData
Device_GetScreenshot
Device_Download

BBPOS test sites

(Note: in order to use the test site, you will need to first download and run our application.)

https://www.cardknox.com/bbpos/request-redirect.htm https://www.cardknox.com/bbpos/request-ajax.htm

Offline Transactions

Use the following integration when you are offline or cannot reach Cardknox:

1. Send the following command to BBPOS (https://localemv.com:8887) to initiate an offline transaction on the device xCommand=cc:encrypt
2. Complete the transaction on the device or on the Payment Engine form

3. If successful, you should receive a response as follows: "xCardNum": "4444330000001111;enc_1_1_Yu2tZUHL2ucliZwKaq5NMKBY5QDArSh8BcroZg4qT6sc39O8fLgRlBxVMQH1jpv+42s9IFTu2cSEi73j6qgtaLkQ5O8gZ2sPBgWnWjDjg6hvYeDJBBTjKh/ms6h6hAhgrfMD+3+ibgrt7OT2Ks2KHQ==_TThACh9hOhTiKte+qU9jRke7f08aAnrsNqjuToWyuP2onSh/ksQN5JOn3yWF2ECMIIrM/uT1MeC3HZxojDV+XDa7+4qJiuKgRh2yyNyAooBtyAh63IzhYd7gaIosEb2U7laOO5d6Zt2HJ4+br7P9hHIEbvElYH2O7uIaQN004c1pki1cJcs0n1ugPLvPpFwUMaUOYUi7z0RuEwX+n/bc9bLHyvYQAt1vo+Z0xteVifT/B0PrNLmGbpElRnwRNpf4koSV05HH363NH/Y4Yu2rnZnCjtOzn1NCPWkt41fUqiVTF1f9ZWCvU7iWR2cLd61Q7OwuT2VLP/c0WnMRbPXDEg==?", "xResult": "S", "xStatus": "Success", "xCommand": "cc:encrypt", "xAuthAmount": "1.99", "xSignatureRequired": "True", "xTransactionMode": "Unknown Entry Mode", "CVM": "Signature" }

4. Store the xCardnum data locally until you have a connection, and then submit the data as xCardnum or xMagStripe