Choose a topic...
Overview
The purpose of the Payment Engine SDK is to allow the developer to easily implement payments into their system.
Getting started
To start, reference the DLLs in your project. PaymentEngine, xCore, NLog, and Newtonsoft.Json
Click Here to Download SDK Files
Initiate Transaction
This is called after all other required and optional transaction-relevant parameters have been set.
There are two types of main transactions that can be initiated: in-scope and out-of-scope. Only one can be called per transaction.
Out-of-scope
Use the out-of-scope function when the user needs to provide their credit card information. This type of transaction gives over control to the SDK to acquire the sensitive credit card data from the user via a pop-up message on the screen or on a credit card device, and then processes the transaction with the gateway.
In-scope
Use the in-scope function when there is no need for the SDK to interact with the user (for example, when you pass through the card number to the SDK or when running a void, etc.). When using this function, you cannot set any device-specific parameters.
Transaction Workflow
To submit a cc:sale transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters, transaction-specific parameters, and device settings.
MyRequest.xKey = "Your_Test_Key";
MyRequest.xVersion = "4.5.8";
MyRequest.xSoftwareName = "My Software";
MyRequest.xSoftwareVersion = "My Software Version 1.0";
MyRequest.xCommand = "cc:sale";
MyRequest.xAmount = 1.23m;
MyRequest.EnableDeviceInsertSwipeTap = True
MyRequest.Settings.Device_Set("Verifone_Mx915.4", "COM9", "115200", "N", "8");
Once this is done, initiate the transaction.
PaymentEngine.xTransaction.Response MyResponse = MyRequest.ProcessOutOfScope();
MyResponse will contain the transaction response information, xResult “A” will indicate that the transaction was approved, “E” or “D” will indicate that it was not approved, and xError will contain the reason.
To submit a cc:sale transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters, transaction-specific parameters, and device settings.
MyRequest.xKey = "Your_Test_Key"; MyRequest.xVersion = "4.5.8"; MyRequest.xSoftwareName = "My Software"; MyRequest.xSoftwareVersion = "My Software Version 1.0"; MyRequest.xCommand = "cc:sale"; MyRequest.xAmount = 1.23m; MyRequest.xCardNum = "4444333322221111"; MyRequest.xExp = "1022";
Once this is done, initiate the transaction.
PaymentEngine.xTransaction.Response MyResponse = MyRequest.Process();
MyResponse will contain the transaction response information, xResult “A” will indicate that the transaction was approved, “E” or “D” will indicate that it was not approved, and xError will contain the reason.
To submit a cc:void transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters and transaction-specific parameters.
MyRequest.xKey = "Your_Test_Key"; MyRequest.xVersion = "4.5.8"; MyRequest.xSoftwareName = "My Software"; MyRequest.xSoftwareVersion = "My Software Version 1.0"; MyRequest.xCommand = "cc:void"; MyRequest.xRefNum = "123456789";
Once this is done, initiate the transaction.
PaymentEngine.xTransaction.Response MyResponse = MyRequest.Process();
MyResponse will contain the transaction response information, xResult “A” will indicate that the transaction was approved, “E” or “D” will indicate that it was not approved, and xError will contain the reason.
To submit a cc:refund transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters and transaction-specific parameters.
MyRequest.xKey = "Your_Test_Key"; MyRequest.xVersion = "4.5.8"; MyRequest.xSoftwareName = "My Software"; MyRequest.xSoftwareVersion = "My Software Version 1.0"; MyRequest.xCommand = "cc:refund"; MyRequest.xRefNum = "123456789";
Once this is done, initiate the transaction.
PaymentEngine.xTransaction.Response MyResponse = MyRequest.Process();
MyResponse will contain the transaction response information, xResult “A” will indicate that the transaction was approved, “E” or “D” will indicate that it was not approved, and xError will contain the reason.
To submit a cc:credit transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters, transaction specific-parameters, and device settings.
MyRequest.xKey = "Your_Test_Key";
MyRequest.xVersion = "4.5.8";
MyRequest.xSoftwareName = "My Software";
MyRequest.xSoftwareVersion = "My Software Version 1.0";
MyRequest.xCommand = "cc:credit";
MyRequest.xAmount = 1.23m;
MyRequest.EnableDeviceInsertSwipeTap = True
MyRequest.Settings.Device_Set("Verifone_Mx915.4", "COM9", "115200", "N", "8");
Once this is done, initiate the transaction.
PaymentEngine.xTransaction.Response MyResponse = MyRequest.ProcessOutOfScope();
MyResponse will contain the transaction response information, xResult “A” will indicate that the transaction was approved, “E” or “D” will indicate that it was not approved, and xError will contain the reason.
To submit a cc:authonly transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters, transaction-specific parameters, and
device settings.
MyRequest.xKey = "Your_Test_Key";
MyRequest.xVersion = "4.5.8";
MyRequest.xSoftwareName = "My Software";
MyRequest.xSoftwareVersion = "My Software Version 1.0";
MyRequest.xCommand = "cc:authonly";
MyRequest.xAmount = 1.23m;
MyRequest.EnableDeviceInsertSwipeTap = True
MyRequest.Settings.Device_Set("Verifone_Mx915.4", "COM9", "115200", "N", "8");
Once this is done, initiate the transaction.
PaymentEngine.xTransaction.Response MyResponse = MyRequest.ProcessOutOfScope();
MyResponse will contain the transaction response information, xResult “A” will indicate that the transaction was approved, “E” or “D” will indicate that it was not approved, and xError will contain the reason.
To submit a cc:capture transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters and transaction-specific parameters.
MyRequest.xKey = "Your_Test_Key"; MyRequest.xVersion = "4.5.8"; MyRequest.xSoftwareName = "My Software"; MyRequest.xSoftwareVersion = "My Software Version 1.0"; MyRequest.xCommand = "cc:capture"; MyRequest.xRefNum = "123456789";
Once this is done, initiate the transaction.
PaymentEngine.xTransaction.Response MyResponse = MyRequest.Process();
MyResponse will contain the transaction response information, xResult “A” will indicate that the transaction was approved, “E” or “D” will indicate that it was not approved, and xError will contain the reason.
To submit a GetSignature transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters and device settings.
MyRequest.xKey = "Your_Test_Key";
MyRequest.xVersion = "4.5.8";
MyRequest.xSoftwareName = "My Software";
MyRequest.xSoftwareVersion = "My Software Version 1.0";
MyRequest.Settings.Device_Set("Verifone_Mx915.4", "COM9", "115200", "N", "8");
Once this is done, initiate the transaction.
string MySignature = MyRequest.GetSignature();
MySignature will contain the transaction signature.
To submit a Device_ShowWelcomeScreen transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters and device settings.
MyRequest.xKey = "Your_Test_Key";
MyRequest.xVersion = "4.5.8";
MyRequest.xSoftwareName = "My Software";
MyRequest.xSoftwareVersion = "My Software Version 1.0";
MyRequest.Settings.Device_Set("Verifone_Mx915.4", "COM9", "115200", "N", "8");
Once this is done, initiate the transaction.
TransRequest.Device_ShowWelcomeScreen();
MySignature will contain the transaction signature.
To submit a ebtfs:sale transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters, transaction-specific parameters, and device settings.
MyRequest.xKey = "Your_Test_Key";
MyRequest.xVersion = "4.5.8";
MyRequest.xSoftwareName = "My Software";
MyRequest.xSoftwareVersion = "My Software Version 1.0";
MyRequest.xCommand = "ebtfs:sale";
MyRequest.xAmount = 1.23m;
MyRequest.EnableDeviceInsertSwipeTap = True
MyRequest.Settings.Device_Set("Verifone_Mx915.4", "COM9", "115200", "N", "8");
Once this is done, initiate the transaction.
PaymentEngine.xTransaction.Response MyResponse = MyRequest.ProcessOutOfScope();
MyResponse will contain the transaction response information, xResult “A” will indicate that the transaction was approved, “E” or “D” will indicate that it was not approved, and xError will contain the reason.
To submit a ebtfs:credit transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters, transaction-specific parameters, and device settings.
MyRequest.xKey = "Your_Test_Key";
MyRequest.xVersion = "4.5.8";
MyRequest.xSoftwareName = "My Software";
MyRequest.xSoftwareVersion = "My Software Version 1.0";
MyRequest.xCommand = "ebtfs:credit";
MyRequest.xAmount = 1.23m;
MyRequest.EnableDeviceInsertSwipeTap = True
MyRequest.Settings.Device_Set("Verifone_Mx915.4", "COM9", "115200", "N", "8");
Once this is done, initiate the transaction.
PaymentEngine.xTransaction.Response MyResponse = MyRequest.ProcessOutOfScope();
MyResponse will contain the transaction response information, xResult “A” will indicate that the transaction was approved, “E” or “D” will indicate that it was not approved, and xError will contain the reason.
To submit a ebtfs:balance transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters, transaction-specific parameters, and device settings.
MyRequest.xKey = "Your_Test_Key";
MyRequest.xVersion = "4.5.8";
MyRequest.xSoftwareName = "My Software";
MyRequest.xSoftwareVersion = "My Software Version 1.0";
MyRequest.xCommand = "cc:balance";
MyRequest.xAmount = 1.23m;
MyRequest.EnableDeviceInsertSwipeTap = True
MyRequest.Settings.Device_Set("Verifone_Mx915.4", "COM9", "115200", "N", "8");
Once this is done, initiate the transaction.
PaymentEngine.xTransaction.Response MyResponse = MyRequest.ProcessOutOfScope();
MyResponse will contain the transaction response information, xResult “A” will indicate that the transaction was approved, “E” or “D” will indicate that it was not approved, and xError will contain the reason.
To submit a Device_ShowItems transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters, transaction-specific parameters, and device settings.
MyRequest.xKey = "Your_Test_Key";
MyRequest.xVersion = "4.5.8";
MyRequest.xSoftwareName = "My Software";
MyRequest.xSoftwareVersion = "My Software Version 1.0";
TransRequest.xTax = 1.26m;
TransRequest.xAmount = 19.23m;
MyRequest.EnableDeviceInsertSwipeTap = True
MyRequest.Settings.Device_Set("Verifone_Mx915.4", "COM9", "115200", "N", "8");
Once this is done, initiate the transaction.
TransRequest.UpdateItems("json", "[{'xdescription':'ItemABC','xupc':558,'xqty':3,'xunit':'EA','xunitprice':'5.99'}]");
TransRequest.Device_ShowItems();
The items will be shown to the user on the pin pad.
To submit a cc:encrypt transaction type, first initiate the request.
PaymentEngine.xTransaction.Request MyRequest = new PaymentEngine.xTransaction.Request();
Next, specify the basic parameters, transaction-specific parameters, and device settings.
MyRequest.xKey = "Your_Test_Key";
MyRequest.xVersion = "4.5.8";
MyRequest.xSoftwareName = "My Software";
MyRequest.xSoftwareVersion = "My Software Version 1.0";
MyRequest.xCommand = "cc:encrypt";
MyRequest.EnableDeviceInsertSwipeTap = True
MyRequest.Settings.Device_Set("Verifone_Mx915.4", "COM9", "115200", "N", "8");
Once this is done, initiate the transaction.
PaymentEngine.xTransaction.Response MyResponse = MyRequest.ProcessOutOfScope();
MyResponse will contain the transaction response information, xResult ”S” will indicate that the request was processed successfully, and xEncryptedPayload will contain the encrypted card number. Once the system is back online submit a cc:sale (in scope) transaction or via API using the encrypted card number as xMagstripe there is no need to submit an expiration date since it is included with the encrypted card number.
Download Our Sample Application
Our sample application supports some of the basic transaction workflows, more will be added in the future. The application is intended to show you how our SDK works.
Transaction Functions
| Function | Description | Sample Data |
|---|---|---|
| ProcessOutOfScope | Process an out-of-scope transaction | ProcessOutOfScope(); |
| Process | Process an in-scope transaction | Process(); |
Basic Parameters
| Name | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Cardknox account key | CardknoxSupport_Test |
| xVersion | Yes | Gateway version | 4.5.8 |
| xSoftwareName | Yes | Name of your software | My app |
| xSoftwareVersion | Yes | Version number of your software | 1.0.0 |
Transaction Specific
| Name | Required | Description | Sample Data |
|---|---|---|---|
| xCommand | Yes*
Use this to submit any CC or ACH command. See Transaction Types. |
Cardknox transaction type | cc:Sale |
| xAmount | Yes | Total amount of the transaction, including tax and tip, if applicable. | 3.0 |
| xTax | No | Tax amount of the transaction. The xTax amount is included in the xAmount. | |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard.
True/False allowed. |
True |
| RequireAVS | No | Requires the user to enter their street address and ZIP Code (only affects keyed transactions).
True/False allowed. |
True |
| RequireCVV | No | Requires the user to enter CVV (only affects keyed transactions).
True/False allowed. |
True |
| EnableTipPrompt | No | Prompts the user on the device if they want to add a tip to the transaction. The transaction response will include “xTip” and “xAuthAmount” (This is the final amount that was authorized on the card including the tip amount). This only works when a device is enabled. | True |
Form Settings
| Name | Required | Description | Sample Data |
|---|---|---|---|
| ExitFormIfApproved | No | Returns control to the calling application if the transaction is approved.
True/False allowed. |
True |
| ExitFormIfNotApproved | No | Returns control to the calling application if the transaction is not approved.
True/False allowed. |
True |
| ExitFormOnDeviceError | No | Returns control to the calling application after any device error.
True/False allowed. |
True |
| Form_Timeout | No | Set the number of milliseconds that the request should time out after. This should typically be set to at least 2 minutes (120000) so it does not interrupt a transaction in progress. | 120000 |
Device Settings
| Name | Required | Description | Sample Data |
|---|---|---|---|
| EnableDeviceInsertSwipeTap | No | Enables the use of a credit card device for card-present transactions.
True/False allowed. |
True |
| Device_Set | No*
Required if EnableDeviceInsertSwipeTap is set to True |
Sets specific device parameters. | Device_Set(“Verifone_Mx915.4”, “COM11”, “115200”, “N”, “8”); IP: “Verifone_Mx915.4”, “10.166.110.101”, “9001” |
PIN Signature
| Name | Description | Sample Data |
|---|---|---|
| EnableDeviceSignature | Prompt for signature after the transaction is approved.
True/False allowed. |
True |
| EnableDeviceSignature_MinAmount | Prompt for signature only if xAmount is greater than the amount set here.
EnableDeviceSignature must be set. |
5 |
| EnableDevicePin | Set the device to prompt for a PIN on swiped transactions. EMV transactions are subject to other rules.
True/False allowed. |
True |
| GetSignature | Manually prompts for signature post transaction. | string MySignature = TransRequest.GetSignature(); |
| GetSignatureAndSaveToFile | Manually prompts for signature post transaction and save it to a file. You can pass through a string to display a message when prompting. | string MySignature = TransRequest.GetSignatureAndSaveToFile(“Signature.png”); |
Receipt
| Name | Required | Description | Sample Data |
|---|---|---|---|
| Settings.Printer_Name | No | Sends the transaction receipt to the printer. | Adobe PDF |
| Settings.Receipt_Merchant_Disabled | No | To disable the merchant receipt, set this to True.
True/False allowed. |
True |
| Settings.Receipt_Customer_Disabled | No | To disable the customer receipt, set this to True.
True/False allowed. |
True |
Stored Account
| Name | Required | Description | Sample Data |
|---|---|---|---|
| EnableStoredAccount | No | Enables the stored account option.
Card number and expiration date are required, and a token can also be used. True/False allowed. |
True |
| StoredAccount_Message | No*
Required if EnableStoredAccount is set to True |
Displays the message to show on the form for the user to select the stored account. | StoredAccount_Message = “Alt + &W – Use Stored Card {1}”; |
| StoredAccount_CustomerPin | No | Asks the user for their account PIN.
The PIN will be whatever value is set here. |
StoredAccount_CustomerPin = “2222” |
Show Items
This is currently only supported for the Mx915 and Mx925. You can add xAmount and xTax to the request before “Device_ShowItems“ so the user can see the total amount and tax of their order. This runs on a separate thread within the application.
| Name | Description | Sample Data |
|---|---|---|
| UpdateItems | Specify the items to show during the transaction (JSON or XML) | TransRequest.UpdateItems(“json”, “[{‘xdescription’:’ItemABC’,’xupc’:558,’xqty’:3,’xunit’:’EA’,’xunitprice’:’5.99′}]”); |
| Device_ShowItems | Show the items that were specified in “UpdateItems”. | TransRequest.Device_ShowItems(); |
Update Device
This is currently only supported for the Mx915 and Mx925
| Name | Required | Description | Sample Data |
|---|---|---|---|
| Device_OsUpdateAvailable | No | Checks if there is an available device OS update | bool OsUpdateAvailable = TransRequest.Device_OsUpdateAvailable(); |
| Device_UpdateOS | No | Update the device OS | Device_UpdateOS(); |
| Device_FirmwareUpdateAvailable | No | Checks if there is an available device Firmware update | bool FirmwareUpdateAvailable = TransRequest.Device_FirmwareUpdateAvailable(); |
| Device_UpdateFirmware | No | Update the device Firmware | Device_UpdateFirmware(); |
Additional Features
| Name | Required | Description | Sample Data |
|---|---|---|---|
| EnableMultipleKeys | No | Enable multiple keys on a computer so Initialization will not be required when switching keys.
True/False allowed. |
True |
| EnableCashback | No | Prompts the user if they want cash back.
True/False allowed. |
True |
| ShowKeyPad | No | If the merchant’s system is touch enabled, set to True to display an on-screen keypad.
True/False allowed. |
True |
| EnableKeyedEntry | No | To disable keyed entry, set to False.
True/False allowed. |
True |
| ExitFormOnDeviceError | No | To return control to the calling application after any device error, set to True.
True/False allowed. |
True |
| EnableSilentMode | No | To enable silent mode and prevent the payment screen from showing, set to True.
True/False allowed. |
True |
| EnableAmountConfirmationPrompt | No | Prompts the user to confirm the transaction amount.
True/False allowed. |
True |
Show Forms
This is currently only supported for the Mx915 and Mx925
| Name | Description | Sample Data |
|---|---|---|
| Device_ShowMessage | Show form with message up to 4 lines. An exception will be thrown if the device does not support it. | Device_ShowMessage(“Hello” ,”Welcome”,”Cardknox”,”Thank you!”); |
| Device_TryShowMessage | Show form with message up to 4 lines. This returns a boolean indicating if it was successful or not. | Device_TryShowMessage(“Hello” ,”Welcome”,”Cardknox”,”Thank you!”); |
| Device_ShowWelcomeScreen | Show the welcome screen on the device. An exception will be thrown if the device does not support it. | Device_ShowWelcomeScreen(); |
| Device_TryShowWelcomeScreen | Show the welcome screen on the device. This returns a boolean indicating if it was successful or not. | Device_TryShowWelcomeScreen(); |
Response Parameters
Transactions that are submitted through the SDK will return a response with one or more fields. Most can be found at https://kb.cardknox.com/api/#_Response_Parameters. Below are the parameters that are specific to the SDK.
| Field Name | Description | Values |
|---|---|---|
| xIsDebit | Indicates if the transaction was processed as debit | True/False |
Sandbox Account Test Cases
Most test cases can be found at https://kb.cardknox.com/api/#_Sandbox_Account_Test_Cases. Below are the test cases specific to the SDK.
Triggers
Debit transaction
Use the cc:sale workflow and set EnableDevicePin = True Insert a debit card into the device and it will prompt you for the PIN (If prompted for AIDs on the device select the Debit AID), you can enter any PIN. The transaction response will include xIsDebit = True.
Offline transaction
The SDK allows you to process transactions when your system is offline. The idea is that you, the user will insert/enter their card and you will receive an encrypted token to be used when the system is back online. see the cc:encrypt workflow.
