Payment Engine SDK

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

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

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.