.NET SDK
Overview
The .NET Payment Engine SDK provides an easy way for developers to integrate card-present and card-not-present payment processing into their .NET projects. Our SDK is designed with user-friendly payment functions and compatibility with a broad range of payment hardware, removing the need for complicated device integration. With this SDK, you can easily incorporate its advanced payment processing capabilities into your .NET projects, streamlining your payment processing experience.
Getting Started
To get started with the SDK, you need to include the following DLLs in your project: PaymentEngine, xCore, xCore.Forms, NLog, and Newtonsoft.Json.
Click Here to Download SDK Files
Initiate Transaction
Initiating a transaction requires the selection of either the "in-scope" method (Process) or the "out-of-scope" method (ProcessOutOfScope). Before starting the transaction, ensure that all required and optional parameters have been properly set as outlined in the documentation.
Out-of-Scope (ProcessOutOfScope)
Use the out-of-scope transaction method when the user needs to provide their credit card information. In this case, the SDK will handle the process of collecting the sensitive credit card data from the user through a pop-up window or a credit card device, and then processing the transaction with the payment gateway.
In-Scope (Process)
Use the in-scope transaction method when there is no need for the SDK to interact with the user. This could be when you have already obtained the card number or when you want to run a void, for example. When using this method, you cannot set any parameters specific to a device.
Transaction Workflow
Click here to view the transaction workflows.
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 | 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 to add a tip to the transaction. This functionality is only available when the device is enabled. The response to the transaction will include two parameters: "xTip" (the tip amount) and "xAuthAmount" (the final authorized amount on the card, including the tip amount). | True |
TipPromptOption | No | To configure the tip percentage options shown to the user when the "EnableTipPrompt" feature is enabled, you can use the "TipPromptOption" setting. You can specify four options, separated by commas. You may include a “c” as one of the options, which allows the user to enter a custom tip amount when selecting that option and/or “0“ to have a “No Tip“ option as well. For example, if you want to show tip options of 5%, 10%, 20%, and a custom amount, you can set the "Tip Prompt Option" as "5,10,20,c". This will present these four options to the user when they are prompted to add a tip to the transaction. | 5,10,20,0 |
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 | Sets the number of milliseconds that the request should time out after. This should typically be set to at least 2 minutes (120,000) so it does not interrupt a transaction in progress. | 120000 |
Form_BackColor | No | Set form background color | Drawing.Color.Agua |
Form_Height | No | Set form height | 500 |
Form_Width | No | Set form width | 500 |
Device Settings
Device Name
Pax devices start with Pax_ and end with .3 (example: Pax_s300.3)
S300 S920 A60 A80 A920 PX5 PX7 D210 D220
Verifone devices start with Verifone_ and end with .4 (example: Verifone_MX915.4)
P400 P200 M400 E285 MX915 MX925 VX805 MX850 MX860 MX870 MX880
VeriFone driver download: https://cdn.cardknox.com/pe/files/verifone_unified_driver_installer-5.0.5.2-b5.zip
Ingenico ISC and IPP devices start with Ingenico_ and end with .6 (example: Ingenico_iSC480.6)
IPP320 IPP350 ISC250 ISC350
Ingenico ICT and Tetra devices start with Ingenico_ and end with .2 (example: Ingenico_iCT250.2)
ICT250 Desk5000 Move5000
ID TECH devices start with IDTech_ and end with .12 (example: IDTech_VP6300.12)
VP6300 VP6800
USB These settings should match what is set for the device in device manager:
COM Port (default: COM9)
Baud rate (default: 115200)
Parity (default: N)
Data Bits (default: 8)
IP These settings should match what the device is set to.
IP Port
Port (default: pax10009 verifone9001 ingenico9999)
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” |
EnableDeviceKeyedEntry | No | Allows the user to key in their card number on the credit card device. EnableDeviceInsertSwipeTap cannot be set to True in the same request. | True |
ShowMenu_DeviceKeyedEntry | No | Adds the DeviceKeyedEntry option on the form for the cashier to toggle. | True |
Cancel Command
| Name | Description | Sample Data |
|---|---|---|
Cancel() | Cancel ongoing function | Cancel("Transaction canceled") |
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 saves 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 on certain VeriFone devices.
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 that 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 on certain Verifone devices.
Name | Description | Sample Data |
Device_ShowMessage | Show form with message of 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 of 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(); |
Device_PromptForEmail | Prompt the user for their email address. | Device_PromptForEmail(); |
Device_PromptForPhone_JSON | Prompt the user for their phone number. | Device_PromptForPhone_JSON(); |
Device_PromptForZip | Prompt the user for their ZIP code. | Device_PromptForZip(); |
Response Parameters
Transactions that are submitted through the SDK will return a response with one or more fields. Most can be found at https://docs.cardknox.com/#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.
Last updated