.NET SDK

Overview
Payment Engine is our .NET SDK that allows developers to easily integrate card-present and card-not-present payment processing within Windows-based systems. Featuring simple functions for initiating payments and support for a range of hardware, it enables developers to bypass lengthy integrations and device integrations.
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
​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 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
Device Name
Pax device 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 MX915 MX925 VX805 MX850 MX860 MX870 MX880

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
IDTech 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 (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
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 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 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 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();
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://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.
Account Boarding Merchant Agreement
Next - SDK
Javascript SDK
Last modified 10d ago