# .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 #### Download and reference SDK files 1. **Download & Run** * Download the [Updater app](https://cdn.cardknox.com/dl/updater.exe). * Right-click the file and Run as Administrator. 2. **Enter Software Name** * When prompted, type: paymentengine 3. **Select SDK Specifications** * Choose (Defaults are preselected): * Release Type (Stable/Beta/Alpha) * Program Version * OS Version * .NET Version * Download Location * Click Next. 4. **Download the SDK** * Click Start and wait for the files to download. * Click Next once the download is complete. * Click Finish. Your SDK files are now downloaded to the specified location. Reference the following DLLs in your project: **PaymentEngine**, **xCore**, **xCore.Forms**, **NLog**, and **Newtonsoft.Json**. (For SDK files with checksum [click here](https://solapayments.com/sdk)) ### Initiate Transaction This guide explains how to initiate credit card transactions using the Cardknox SDK. Transactions can be processed **in-scope** or **out-of-scope**, depending on whether the SDK needs to collect sensitive cardholder information. #### 0. Create a Transaction Request Object Instantiate a new `PaymentEngine.xTransaction.Request` object. This object will hold all transaction parameters and settings #### 1. Prepare the Transaction Request Before submitting a transaction, you must set the required and optional parameters. These include: * Basic SDK parameters: `xKey`, `xVersion`, `xSoftwareName`, `xSoftwareVersion`. * Transaction-specific parameters: `xCommand`, `xAmount`, `xInvoice`, etc. * Device settings (if using a physical device): `EnableDeviceInsertSwipeTap`, `Device_Set` etc. Parameter information is documented in the sections below. #### 2. Initiate the Transaction The Cardknox SDK provides two methods for processing transactions: **Out-of-Scope Transactions (**`ProcessOutOfScope`**)**\ Use this method when the SDK must collect sensitive card data directly from the cardholder. The SDK securely captures the information via a pop-up window or a card-present device (e.g., Verifone terminal for swipes, taps, or chip insertions) and submits the transaction to the Cardknox gateway. **In-Scope Transactions (**`Process`**)**\ Use this method when card data is already available in your system or for non-interactive transactions such as voids, refunds, or card-on-file payments. No user input or device interaction is required; the SDK submits the transaction directly to the Cardknox gateway. #### 3. Handle the Response After processing, the SDK returns the transaction response data to the calling method. This object contains all transaction details returned by the gateway, including status, approval code, and error messages. For definitions see [response parameters](https://docs.solapayments.com/#response-parameters) ### Troubleshooting steps * Ensure the Payment Engine DLLs are downloaded and referenced in the project. These include PaymentEngine, xCore, xCore.Forms, NLog, and Newtonsoft.Json. * Ensure that the Payment Engine DLLs architecture (x86, x64, AnyCPU) matches your project build settings. * Ensure that the Payment Engine DLLs .NET version matches your project framework version. ### Backup gateway host You can set the transactions to use a backup host in case there is an issue with the gateway. See Transaction Specific>ActivateBackupGatewayURL. You can sign up for status updates at ### Transaction Workflow Click [here](https://docs.solapayments.com/sdk/payment-engine-sdk/payment-engine-sdk) to view Transaction Workflows. [Download Our Sample Application](https://kb.cardknox.com/wp-content/uploads/PlastiDip.zip)\ 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 | Sola account key | SolaSupport\_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 | Sola 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, Sola 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 | | ActivateBackupGatewayURL | No | Set transactions to use the backup host for the next half hour. |

ActivateBackupGatewayURL(“x2“)

Options are x2 or b1

| | DeactivateBackupGatewayURL | No | Set transactions to use the regular host going forward | DeactivateBackupGatewayURL() | | Settings.EnableOfflineTransactions |

No\*

Required for offline transactions (cc:encrypt)

| Enable offline transactions. Offline transactions are initiated with the cc:encrypt command | 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. To enable fixed dollar amounts, include a "$" next to the number for the fixed dollar.

For example, if you want to show tip options of 5%, 10%, a fixed $1 tip option, and a custom amount, you can set the "Tip Prompt Option" as "5,10,$1, c". This will present these five options to the user when they are prompted to add a tip to the transaction.

| 5,10,$1, c | ### 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 A35` \ 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:
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: pax`10009` verifone`9001` ingenico`9999`) | 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 | | 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”,”Sola”,”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”,”Sola”,”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(); |