Choose a topic...
The purpose of the Payment Engine SDK is to allow the developer to easily implement payments into their system.
Click Here to Download SDK Files
Getting started
To start, reference the DLLs in your project. PaymentEngine, xCore, NLog, and Newtonsoft.Json
Initate 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: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 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.
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 |
| 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 |
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 |
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 | Required | Description | Sample Data |
|---|---|---|---|
| EnableDeviceSignature | No | Prompt for signature after the transaction is approved.
True/False allowed. |
True |
| EnableDeviceSignature_MinAmount | No | Prompt for signature only if xAmount is greater than the amount set here.
EnableDeviceSignature must be set. |
5 |
| EnableDevicePin | No | Set the device to prompt for a PIN on swiped transactions. EMV transactions are subject to other rules.
True/False allowed. |
True |
| GetSignature | No | Manually prompts for signature post transaction. | string MySignature = TransRequest.GetSignature(); |
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” |
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 |
Transaction Types
See kb.cardknox.com/api for more information about each command and required/optional fields.
| Name | Notes |
|---|---|
| cc:Sale | Use out-of-scope. |
| cc:AuthOnly | Use out-of-scope. |
| cc:Capture | Use in-scope. |
| cc:Adjust | Use in-scope. |
| cc:Save | Use out-of-scope. |
| cc:PostAuth | Use out-of-scope. |
| cc:Credit | Use out-of-scope. |
| cc:Refund | Use in-scope. |
| cc:VoidRefund | Use in-scope. |
| cc:VoidRelease | Use in-scope. |
| cc:Void | Use in-scope. |
| check:Sale | Use out-of-scope. |
| check:Credit | Use out-of-scope. |
| check:Save | Use out-of-scope. |
| check:Void | Use in-scope. |
| check:Refund | Use in-scope. |
