# Table of Contents
- [3D Secure 2.0 | Cardknox](#3d-secure-2-0-cardknox)
- [Account Boarding Swagger UI | Cardknox](#account-boarding-swagger-ui-cardknox)
- [Client-Side Integration | Cardknox](#client-side-integration-cardknox)
- [Transaction API | Cardknox](#transaction-api-cardknox)
- [Fraud | Cardknox](#fraud-cardknox)
- [Account Boarding Merchant Agreement | Cardknox](#account-boarding-merchant-agreement-cardknox)
- [iOS SDK - Technical Guide | Cardknox](#ios-sdk-technical-guide-cardknox)
- [Account Updater | Cardknox](#account-updater-cardknox)
- [.NET SDK | Cardknox](#-net-sdk-cardknox)
- [Introduction | Cardknox](#introduction-cardknox)
- [Account Boarding API | Cardknox](#account-boarding-api-cardknox)
---
# 3D Secure 2.0 | Cardknox
Last updated 10 months ago
###
[](#overview)
**Overview**
3-D (Three-Domain) Secure is an e-commerce security protocol that adds a layer of protection to the checkout process by authenticating the cardholder's identity in real-time — resulting in a reduced rate of fraud and fraud-related chargebacks. Authenticated transactions are very unlikely to be fraudulent, and they cannot be disputed by the cardholder as fraudulent.
While the original 3DS technology effectively reduced rates of fraud, it also introduced friction to the checkout experience because customers were often redirected to their issuing bank’s website to verify their identity. Additionally, the original 3DS is not compatible with mobile payments since it was developed before mobile payment usage became mainstream.
To address the drawbacks of 3DS, EMVco developed 3-D Secure 2.0 in 2016. The updated technology improves upon the original 3DS in several key ways:
* **Utilizes a Greater Number of Data Points to Authenticate Transactions** 3DS2 relies upon a much greater number of transaction-specific data points than the original 3DS, which improves the reliability of authentication and limits customer involvement.
* **Embedded, Frictionless Authentication** In the event that the customer does have to verify their identity, they will no longer be redirected to a third-party page — instead, they can verify their identity with a passcode or biometric scan right from the checkout page.
* **Compatible With Mobile Commerce** The new 3-D Secure offers support for iOS and Android SDKs so that merchants can provide a seamless and secure mobile checkout experience.
###
[](#contents)
Contents
* [Overview](#overview)
* [Contents](#contents)
[Client Side Integration](/cardknox-products/3d-secure/client-side-integration/public-client-side-integration)
[Server Side Integration](/cardknox-products/3d-secure/public-server-side-integration)
---
# Account Boarding Swagger UI | Cardknox
Last updated 1 year ago
For general information about using Swagger UI, refer to .
####
[](#swagger-url)
Swagger URL
####
[](#using-swagger-ui)
Using Swagger UI
* Only sandbox keys may be used when submitting accounts
* The Signature.Token field is not required
[this documentation](https://swagger.io/docs/specification/2-0/what-is-swagger/)
[Swagger UI](https://psapi.cardknox.com/boarding/v1/swagger)
---
# Client-Side Integration | Cardknox
[](#recommended-ifields)
Recommended - iFields
---------------------------------------------------
For the iFields client-side 3DS 2.0 integration, refer to [iFields | Cardknox](https://docs.cardknox.com/cardknox-products/ifields#ifields-with-3d-secure-authentication)
[](#non-ifields-implementation)
Non-iFields Implementation
---------------------------------------------------------------
For the Non-iFields client-side 3DS 2.0 integration, refer to the child page [here](/cardknox-products/3d-secure/client-side-integration/public-client-side-integration)
.
Last updated 3 months ago
🧰
* [Recommended - iFields](#recommended-ifields)
* [Non-iFields Implementation](#non-ifields-implementation)
---
# Transaction API | Cardknox
Last updated 6 days ago
[](#overview)
Overview
---------------------------
The Cardknox API enables developers to process payments using the Cardknox gateway. Systems integrating with the Cardknox API can submit API calls using various commands. The API supports many payment methods, including credit cards, ACH, EBT, and gift cards.
To begin building your API integration, for a Cardknox sandbox — our secure testing environment that mimics the production environment. After signing up, you’ll be able to create user credentials for the Cardknox Merchant Portal. Once you log in to the Portal, you’ll be able to generate an API key from the Settings menu. or follow the instructions below to obtain a key.
###
[](#how-to-generate-cardknox-keys)
How to Generate Cardknox Keys
1. Sign in to the Cardknox Merchant Portal.
2. Select "Account Settings" from the navigation bar.
3. Select "Keys" from the sub-menu.
4. Click "Create a Key" in the top-right corner.
5. Choose the desired key type (API or iFields), description (software, etc.), and permissions.
6. Click "Create and View" and copy your key.
It is critical to copy your key and save it in a secure location, as you won’t be able to obtain the key again.
###
[](#ifields-and-transaction-api)
iFields and Transaction API
We recommend using iFields in conjunction with the Transaction API for added security. Cardknox iFields is an iFrames solution that keeps sensitive card data away from merchant servers while granting you complete control over form layout and design. to learn more about iFields.
The Cardknox iFields solution utilizes iFrames in which the user enters their credit card and/or ACH information and then uses JavaScript to generate SUTs (single-use tokens) for processing. These features allow the website to remain secure and out-of-scope for PCI compliance while allowing the developer to customize the page layout and design fully.
###
[](#cross-origin-resource-sharing-cors-restrictions)
Cross-Origin Resource Sharing (CORS) Restrictions
This API has Cross-Origin Resource Sharing (CORS) restrictions in place to enhance security. Requests made directly from a web browser client (e.g., JavaScript running in the browser) will be blocked.
**Allowed Origins** This API only accepts requests from server-side origins. Ensure that your requests originate from a server to successfully interact with the API.
###
[](#endpoints)
Endpoints
The endpoint section defines the details for accessing and interacting with the Cardknox transaction API.
####
[](#health-check)
Health Check
**Method:** Always use `GET` for health checks. **Protocol**: Secure communication is enforced using `https://` **Environment**: Specifies the targeted environment for the check, such as `x1`, `x2`, or `b1` **Domain**: The base URL is always `cardknox.com` **Paths:** The endpoint path for health checks is `/status`
####
[](#transactions)
Transactions
**Method:** Always use `POST` for transaction requests. **Protocol**: Secure communication is enforced using `https://` **Environment**: The primary environment is `x1`, with `x2` and `b1` available as backups. **Domain**: The base URL is always `cardknox.com` **Paths/Formats**: Various paths are supported based on data format requirements:
* `/gatewayform` for form data
* `/gatewayjson` for JSON data
* `/gatewayxml` for XML data
[](#request-method)
Transaction Types
------------------------------------------
The endpoints can be found in the following child pages by navigating to the appropriate page:
**Transactions**
[](#credit-card)
Questions
-------------------------------
Transaction Type
Transaction (Link)
xCommand
Can't find what you're looking for? Please contact .
**Method**
**Protocol**
**Environment**
**Domain**
**Path**
**Example URL**
GET
https
x1 x2 b1
cardknox.com
status
https://x1.cardknox.com/status
**Method**
**Protocol**
**Environment**
**Domain**
**Path**
**Example URL**
POST
https
x1 x2 b1
cardknox.com
gatewayform gatewayjson gatewayxml
https://x1.cardknox.com/gatewayjson
[Credit Card](/api/transaction/credit-card)
[Sale](/api/transaction/credit-card#sale)
cc:sale
[AuthOnly](/api/transaction/credit-card#authonly)
cc:authonly
[Capture](/api/transaction/credit-card#capture)
cc:capture
[Adjust](/api/transaction/credit-card#adjust)
cc:adjust
[Save](/api/transaction/credit-card#save)
cc:save
[AVS Only](/api/transaction/credit-card#avsonly)
cc:avsonly
[PostAuth](/api/transaction/credit-card#postauth)
cc:postauth
[Credit](/api/transaction/credit-card#credit)
cc:credit
[Refund](/api/transaction/credit-card#refund)
cc:refund
[VoidRefund](/api/transaction/credit-card#voidrefund)
cc:voidrefund
[VoidRelease](/api/transaction/credit-card#voidrelease)
cc:voidrelease
[Void](/api/transaction/credit-card#void)
cc:void
[Check (ACH)](/api/transaction/check-ach)
[Sale](/api/transaction/check-ach#sale)
check:sale
[Credit](/api/transaction/check-ach#credit)
check:credit
[Save](/api/transaction/check-ach#save)
check:save
[Void](/api/transaction/check-ach#void)
check:void
[Refund](/api/transaction/check-ach#refund)
check:refund
[Check (ACH-Q)](/api/transaction/check-ach#achq)
[VoidRefund](/api/transaction/check-ach#voidrefund)
check:voidrefund
[EBT Food Stamp](/api/transaction/ebt#ebt-food-stamp)
[Sale](/api/transaction/ebt#sale)
ebtfs:sale
[Credit](/api/transaction/ebt#credit)
ebtfs:credit
[Balance](/api/transaction/ebt#balance)
ebtfs:balance
[Voucher](/api/transaction/ebt#voucher)
ebtfs:voucher
[EBT Cash Benefits](/api/transaction/ebt#ebt-cash-benefits)
[Sale](/api/transaction/ebt#sale-1)
ebtcb:sale
[Cash](/api/transaction/ebt#cash)
ebtcb:cash
[Balance](/api/transaction/ebt#balance-1)
ebtcb:balance
[EBT Wic (eWic)](/api/transaction/ebt#ebt-wic-ewic)
[Sale](/api/transaction/ebt#sale-2)
ebtw:sale
[Balance](/api/transaction/ebt#balance-2)
ebtw:balance
[Void](/api/transaction/ebt#void)
ebtw:void
[Gift Card](/api/transaction/gift-card#issue)
[Issue](/api/transaction/gift-card#issue)
gift:issue
[Redeem](/api/transaction/gift-card#redeem)
gift:redeem
[Balance](/api/transaction/gift-card#balance)
gift:balance
[Activate](/api/transaction/gift-card#activate)
gift:activate
[Deactivate](/api/transaction/gift-card#deactivate)
gift:deactivate
[Fraud](/api/transaction/fraud)
[Fraud Submit](/api/transaction/fraud#fraud-submit)
fraud:submit
[create an account](https://www.cardknox.com/sandbox/)
[Watch our Key Management video](https://www.youtube.com/watch?v=2t0p7LYgtkA&list=PLJOVea6Z4X_AQIcDmeAXOcQGZalOWkLxi&index=12)
[Click here](https://docs.cardknox.com/cardknox-products/ifields)
[support@cardknox.com](mailto:support@cardknox.com)
* [Overview](#overview)
* [How to Generate Cardknox Keys](#how-to-generate-cardknox-keys)
* [iFields and Transaction API](#ifields-and-transaction-api)
* [Cross-Origin Resource Sharing (CORS) Restrictions](#cross-origin-resource-sharing-cors-restrictions)
* [Endpoints](#endpoints)
* [Transaction Types](#request-method)
* [Questions](#credit-card)
[Credit Card](/api/transaction/credit-card)
[Check (ACH)](/api/transaction/check-ach)
[EBT](/api/transaction/ebt)
[Gift Card](/api/transaction/gift-card)
[Fraud](/api/transaction/fraud)
---
# Fraud | Cardknox
Last updated 6 days ago
[](#overview)
Overview
---------------------------
This page contains all API documentation for Gift Card transactions. For more information regarding account access, navigate to the parent page.
[](#transactions)
Transactions
-----------------------------------
###
[](#fraud-submit)
Fraud Submit
`POST` `fraud:submit`
`xCommand` = `fraud:submit`
The Submit command is used in conjunction with a valid FraudWatch account to submit e-commerce transactions for a fraud verification check.
####
[](#request-body)
Request Body
Name
Type
Description
* [Overview](#overview)
* [Transactions](#transactions)
* [Fraud Submit](#fraud-submit)
xCardNum\*
String
Masked Card number with BIN and last 4 digits exposed
xKey\*
String
Your Cardknox API key.
xVersion\*
String
Gateway API version. The current version is 5.0.0.
xSoftwareName\*
String
Name of your software
xSoftwareVersion\*
String
Version number of your software
xCommand\*
String
Cardknox transaction type
xAmount\*
String
The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction
xCustom01
String
20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20
xInvoice\*
String
The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling
xIP\*
String
The customer’s IP address. Typically used for fraud detection
xEmail\*
String
The customer’s email address
xBillFirstName\*
String
The customer’s first name for their billing profile
xBillLastName\*
String
The customer’s last name for their billing profile
xBillStreet\*
String
The customer’s street address for their billing profile
xBillCity\*
String
The customer’s city for their billing profile
xBillState\*
String
The customer’s state for their billing profile
xBillZip\*
String
The customer’s zip code for their billing profile
xBillPhone\*
String
The customer’s phone number for their billing profile
xShipFirstName\*
String
The customer’s first name for their shipping profile
xShipLastName\*
String
The customer’s last/family name for their shipping profile
xShipStreet\*
String
The customer’s street address for their shipping profile
xShipCity\*
String
The customer’s city for their shipping profile
xShipState\*
String
The customer’s state for their shipping profile
xShipZip\*
String
The customer’s zip code for their shipping profile
xShipPhone\*
String
The customer’s phone number for their shipping profile
xOrderID
String
Unique order number for FraudWatch verification
xExistingCustomer
String
Yes/No value indicating if customer is a repeat customer
xAllowDuplicate
String
By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed.
xGatewayRefNum\*
String
Transaction RefNum received from gateway for FraudWatch verification
xGatewayResult\*
String
Transaction status received from gateway for FraudWatch verification (Approved/Declined/Error)
xGatewayCVV\*
String
CVV for FraudWatch verification
xGatewayAVS\*
String
Street address for FraudWatch verification
xOrderType\*
String
Specifies if the order origin is internet OR phone for FraudWatch verification
xExistingCustomer\*
String
Yes/No value indicating if the customer is a repeat customer
xShipEmail\*
String
The ShipTo email address
xName
String
The cardholder’s name
xTax
String
The tax portion that is included in the total transaction amount (xAmount)
xTip
String
The tip portion that is included in the total transaction amount (xAmount)
xPONum
String
The merchant’s purchase order number for the transaction
xDescription
String
Additional data that is optionally passed along for reporting
xShipMiddleName
String
The customer’s middle name for their shipping profile
xBillMiddleName
String
The customer’s middle name for their billing profile
xBillStreet2
String
The customer’s second line street address for their billing profile
xShipStreet2
String
The customer’s second line street address for their shipping profile
xShipCountry
String
The customer's country code for their shipping profile
xBillCountry
String
The custom's country code for their billing profile
xBillMobile
String
The customer’s mobile phone number for their billing profile
xGatewayError
String
Transaction RefNum received from gateway for FraudWatch verification
xComments
String
Additional data that is optionally passed along to the receipt
xFax
String
The customer’s fax number.
xOrderItems
String
Summary of products ordered
xCustomerComments
String
Comments submitted by customer along with order
xShipMethod
String
The shipping carrier/service used
xShipAmount
String
The total cost of shipping charges
xSupports64BitRefnum
String
True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.
[Transaction API](/api/transaction)
Fraud Submit - Request Payload Example
Copy
{
"xCardNum": "4444333322221111",
"xKey": "[xkeycredentials]",
"xVersion": "4.5.9",
"xSoftwareName": "YourSoftwareName",
"xSoftwareVersion": "1.0.0",
"xCommand": "fraud:submit",
"xToken": "61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84",
"xCustom01": "Register01",
"xExp": "12/25",
"xCVV": "945",
"xStreet": "123 Any Street Apt 4b Anytown, NY",
"xZip": "12345",
"xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
"xName": "John Doe",
"xAuthCode": "T4321A",
"xDUKPT": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;444433",
"xTax": "2.00",
"xTip": "2.00",
"xRefNum": "81234568",
"xInvoice": "123456A",
"xPONum": "123456B",
"xComments": "This is a comment",
"xDescription": "This is a description",
"xIP": "1.2.3.4",
"xEmail": "text@example.com",
"xFax": "1234567890",
"xBillFirstName": "John",
"xBillMiddleName": "Max",
"xBillLastName": "Doe",
"xBillCompany": "Acme",
"xBillStreet": "123 Any Street",
"xBillStreet2": "Apt 4b",
"xBillCity": "Anytown",
"xBillState": "NY",
"xBillZip": "12345",
"xBillCountry": "USA",
"xBillPhone": "8005551212",
"xBillMobile": "8005551111",
"xShipFirstName": "John",
"xShipMiddleName": "Max",
"xShipLastName": "Doe",
"xShipCompany": "Acme",
"xShipStreet": "123 Any Street",
"xShipStreet2": "Apt 4b",
"xShipCity": "Anytown",
"xShipState": "NY",
"xShipZip": "12345",
"xShipCountry": "USA",
"xShipPhone": "8005551212",
"xShipMobile": "8005551111",
"xMICR": "t021000021t 123456789o _2542",
"xRouting": "021202337",
"xGatewayRefNum": "852585258",
"xGatewayResult": "Approved",
"xGatewayError": "845455484",
"xGatewayCVV": "M",
"xGatewayAVS": "YYY",
"xOrderType": "Internet",
"xOrderID": "12356",
"xExistingCustomer": "TRUE",
"xOrderItems": "Sony Digital Camera",
"xCustomerComments": "Please ship as soon as possible",
"xShipMethod": "UPS Ground",
"xShipAmount": "29.99",
"xShipEmail": "text@example.com",
"xAllowDuplicate": "TRUE"
}
---
# Account Boarding Merchant Agreement | Cardknox
Last updated 10 months ago
[](#overview)
Overview
---------------------------
* * *
In order to be boarded every Merchant needs to agree to Go Plus Terms and Conditions. To help Developers integrate Agreement API into their website we are supporting Agreement API through Cardknox iFields.
###
[](#integrate-agreement-api-using-ifields)
**Integrate Agreement API using ifields**
Obtain your _**iFields xKey**_ from your account settings.
####
[](#adding-reference-to-ifields)
Adding Reference to iFields
* * *
**Step 1:** Check the latest stable iFields version here:
**Step 2:** Add the ifields.js file after the tag on your website:
``
####
[](#adding-iframe-and-javascript-objects-for-merchant-agreement)
Adding iFrame and JavaScript Objects for Merchant Agreement
* * *
**Step 1:** Add the following iFrame JS snippet inside the __ where Merchant Agreement is desired.
* Make sure you have an attribute `data-ifields-id="agreement"` as part of _`
**Step 2:** Create JavaScript function to handle Agreement API callback
**Step 3:** Enable Customer Agreement to get the token
There are two ways to get the token:
* Asynchronously (a callback will be performed once the customer agrees to Terms and Conditions) Just add `enableAgreement` call when the document is loaded (`autoAgree` the parameter is set to `true`):
* Synchronously (Explicitly calling `getToken` function for example on Submit) Add `enableAgreement` call when the document is loaded (`autoAgree` the parameter is set to `false`):
In your `Submit` function add the following code:
###
[](#objects-reference)
Objects Reference
* * *
####
[](#istatus)
iStatus
####
[](#agreement-response)
Agreement Response
**The object holding the response with token from Agreement API.**
For `response` object reference refer here:
**Name**
**Type**
**Description**
`status`
[iStatus](/api/account-boarding-api/account-boarding-merchant-agreement#objects-reference)
There are 2 possible cases:
* Agreement was accepted and Token was obtained `status=iStatus.success`
* Agreement wasn’t accepted or an error occurred obtaining the token: `status=iStatus.error`
`statusText`
String
When `status=iStatus.error` this field will be populated with the reason
`token`
String
When `status=iStatus.success` this field will be populated with `token`
[Cardknox Partner Portal](https://partner.cardknox.com/)
[https://cdn.cardknox.com/ifields/versions.htm](https://cdn.cardknox.com/ifields/versions.htm)
Copy
function handleAgreementResponse(response) {
let msg = null;
if (!response) {
msg = "Failed to load token. No Response";
} else if (response.status !== iStatus.success) {
msg = "Failed to load token. "+response.statusText || "No Error description available";
} else if (!response.token) {
msg = "Failed to load token. No Token available";
} else {
msg = response.token;
}
setTimeout(() => {alert(msg)}, 10);
}
* [Overview](#overview)
* [Integrate Agreement API using ifields](#integrate-agreement-api-using-ifields)
* [Objects Reference](#objects-reference)
[Agreement Response](/api/account-boarding-api/account-boarding-merchant-agreement#agreement-response)
Copy
document.addEventListener("DOMContentLoaded", function(event) {
................
ckCustomerAgreement.enableAgreement({
iframeField: 'agreement',
xKey: '',
autoAgree: true,
callbackName: 'handleAgreementResponse'
});
................
}
Copy
document.addEventListener("DOMContentLoaded", function(event) {
................
ckCustomerAgreement.enableAgreement({
iframeField: 'agreement',
xKey: '',
autoAgree: false
});
................
}
Copy
ckCustomerAgreement.getToken()
.then(resp => {
handleAgreementResponse(resp);
})
.catch(err => {
console.error("Agreement Token Error", exMsg(err));
handleAgreementResponse(err);
});
Copy
const iStatus = {
success: 100,
unsupported: -100,
error: -200
}
---
# iOS SDK - Technical Guide | Cardknox
Last updated 1 year ago
[](#overview)
Overview
---------------------------
This document helps developers to set up and integrate Cardknox Payments SDK into Objective C and Swift projects. The document contains steps for framework integration, required settings setup and import of SDK headers.
[](#technical-overview)
Technical Overview
-----------------------------------------------
* The SDK is distributed as a `.framework`
* `.framework` contains the `CardknoxPaymentsSDK` binary and `ObjectiveC` `.h` headers describing the SDK API
* The `CardknoxPaymentsSDK` does not contain `bitcode` and cannot be integrated with applications that require `bitcode`
* `.framework` only supports `arm64` 64-bit architecture for device builds. Simulator targets are not supported.
* SDK minimum deployment target is 14.0
[](#framework-file-integration)
Framework File Integration
---------------------------------------------------------------
1. Download the zip file with CardknoxPaymentsSDK.framework. Links for downloading framework files can find in section.
2. Extract CardknoxPaymentsSDK.framework from downloaded .zip file.
3. Copy the downloaded .framework file to the root of your project (for example, alongside the xcodeproj file):
4. Open the `General` under the application `Target`. Find the `Frameworks, Libraries, and Embedded Content` section. Click on the `+` icon for adding a framework to the project.
5. `+` icon opens the dialog screen for adding framework. On dialog click on `Add Other` dropbox, which opens a menu. On the menu click on `Add files...`
6. `Add files...` opens Choose frameworks and libraries to add dialog. On dialog find the root folder of the project and select `CardknoxPaymentsSDK.framework` file.
7. After adding the framework, the `CardknoxPaymentsSDK.framework` must be in the `Frameworks, Libraries, and Embedded Content` section. Pay attention to the value in the `Embed` column. The value must be `Embed & Sign`.
8. Also after adding the framework, the `CardknoxPaymentsSDK.framework` must be in `Link Binary With Libraries and Embed Frameworks` sections. `Link Binary With Libraries` and `Embed Frameworks` sections are in the `Build Phases` tab, under the application `Target`.
###
[](#undefined)
[](#required-settings-setup)
Required Settings Setup
---------------------------------------------------------
###
[](#disabling-bitcode)
Disabling Bitcode
The Cardknox SDK doesn’t support bitcode. To disable Bitcode follow these steps:
1. Click on your application target. Choose `Build Settings` > `All`
###
[](#info.plist-merge)
Info.plist merge
1. The `CardknoxPaymentsSDK` framework contains an `Info.plist` file which contains various key/value pairs that are required by the framework, for example, it defines a `NSBluetoothAlwaysUsageDescription` key with a value similar to “Bluetooth is required to find, connect to and transfer data between a card reader and the app"
2. The application that is using the `CardknoxPaymentsSDK` framework also defines an `Info.plist` file with its own key/value pairs
3. The goal is to merge the framework `Info.plist` file with the application `Info.plist` in order to avoid runtime errors in the `CardknoxPaymentsSDK` framework code due to missing key/values. `XCode` doesn't perform any merges automatically.
4. Note that if there are identical keys present in the application `Info.plist` and in the framework `Info.plist` files, such as the `NSBluetoothAlwaysUsageDescription` key; the value defined in the application Info.plist for that key will have priority during the merge; making it easy to override values in the framework `Info.plist`
5. To merge the two files, define a `Run Script` step in the `XCode` application Target's `Build Phases` section and run the `PlistBuddy` tool, as following:
* Delete the `Type a script...` contents of the input box and add the following command
[](#id-5.-cardknoxpaymentssdk-headers-import)
CardknoxPaymentsSDK headers import
-------------------------------------------------------------------------------------
This section shows how to use the `CardknoxPaymentsSDK` in Objective C and Swift code. For Objective C it’s sufficient to reference the main SDK header. For Swift, an umbrella header is required to wrap the main SDK header into a Swift compatible format.
###
[](#objective-c-import)
Objective C import
For Objective C applications - reference the `CardknoxPaymentsSDK` main header file in your code with `#import "CardknoxPaymentsSDK/CardknoxPaymentsSDK.h"`
###
[](#swift-import)
Swift import
For Swift applications - an umbrella header needs to be created and referenced by your application `Target` in order to properly embed the framework into your app. To create the umbrella header, follow the steps:
2. Clear all text in the header file
4. Navigate to your target’s `Build Settings` > `All`
Set the `Enable Bitcode` option to `No` in the `Build Options` section
Add a new `Run Script` step to `Build Phases`
Make sure that the `Run Script` step is the last step, below other steps (`Compile Sources`, `Embed Frameworks`, etc.). You can reposition steps by dragging up and down:
Expand the `Run Script` step
`/usr/libexec/PlistBuddy -c "merge CardknoxPaymentsSDK.framework/Info.plist" "${TARGET_BUILD_DIR}/${INFOPLIST_PATH}"`
Create a new header file in the Target folder via File menu > New... > File.... Choose Header File option. For example, the name might be: `iOS.Swift.SampleApp-Bridging-Header.h`
Add `#import "CardknoxPaymentsSDK/CardknoxPaymentsSDK.h"` into the header file
Find the `Objective-C Bridging Header` option in the `Swift Compiler - General` section and set its value to be the relative path to the header file. For example, an application target named `iOS.Swift.SampleApp` will have the `iOS.Swift.SampleApp/iOS.Swift.SampleApp-Bridging-Header.h` path specified. The assumption is that the header file is in the `Target` folder, side by side the `info.plist` file.
* [Overview](#overview)
* [Technical Overview](#technical-overview)
* [Framework File Integration](#framework-file-integration)
* [](#undefined)
* [Required Settings Setup](#required-settings-setup)
* [Disabling Bitcode](#disabling-bitcode)
* [Info.plist merge](#info.plist-merge)
* [CardknoxPaymentsSDK headers import](#id-5.-cardknoxpaymentssdk-headers-import)
* [Objective C import](#objective-c-import)
* [Swift import](#swift-import)
[iOS SDK - Get Started](https://docs.cardknox.com/sdk/ios-sdk#getting-started)
---
# Account Updater | Cardknox
[](#accountupdater-howitworks)
Overview
--------------------------------------------
Cardknox Account Updater identifies customer cards that have expired or are inactive, and then obtains the new card information from the bank. This information is returned to Cardknox within 10 days of the initial request, at which point it is stored and applied towards any subsequent transactions that are attempted using the previous card (using either the actual data or a Cardknox token).
When a subsequent transaction is processed using updated card information, Cardknox will indicate this by including `xIsUpdatedCard = True` in the transaction responses. The data returned in `xMaskedCardNumber` and `xExp` will also reflect the updated information, when applicable.
[](#recurring-billing)
Recurring Billing
---------------------------------------------
Because Account Updater does not provide updated card information instantaneously, we recommend that Merchants wait 5-10 days before retrying a declined transaction in order to ensure that the updated card information is available. In the case of a recurring payment, note that declined recurring payments are retried once a day for 5 consecutive days, and it's very likely that updated card information will be received and successfully retried within this timeframe.
[](#accountupdater-reporting)
Reporting
--------------------------------------------
When a transaction utilizes Account updater, this is indicated in the reporting in the `xCardSource` field (as `xIsUpdatedCard = True`).
`xCardSource = incoming` represents transactions processed with original card data.
`xCardSource = account` represents transactions that were processed using updated card info from Account Updater.
Last updated 2 years ago
* [Overview](#accountupdater-howitworks)
* [Recurring Billing](#recurring-billing)
* [Reporting](#accountupdater-reporting)
---
# .NET SDK | Cardknox
Last updated 1 day ago
[](#overview)
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)
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.
###
[](#initiate-transaction)
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)
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)
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.
###
[](#backup-gateway-host)
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)
Transaction Workflow
---------------------------------------------------
###
[](#transaction-functions)
Transaction Functions
###
[](#basic-parameters)
Basic Parameters
###
[](#transaction-specific)
Transaction-Specific
###
[](#form-settings)
Form Settings
###
[](#device-settings)
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`
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`)
###
[](#pin-signature)
Cancel Command
###
[](#pin-signature-1)
PIN Signature
###
[](#receipt)
Receipt
###
[](#stored-account)
Stored Account
###
[](#show-items)
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.
###
[](#update-device)
Update Device
This is currently only supported on certain VeriFone devices.
###
[](#additional-features)
Additional Features
###
[](#show-forms)
Show Forms
This is currently only supported on certain Verifone devices.
###
[](#response-parameters)
Response Parameters
###
[](#sandbox-account-test-cases)
Sandbox Account Test Cases
**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)
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.
###
[](#troubleshooting-steps)
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.
.
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.
VeriFone driver download:
Name
Description
Sample Data
Transactions that are submitted through the SDK will return a response with one or more fields. Most can be found at . Below are the parameters that are specific to the SDK.
Most test cases can be found at . Below are the test cases specific to the SDK.
Function
Description
Sample Data
ProcessOutOfScope
Process an out-of-scope transaction
ProcessOutOfScope();
Process
Process an in-scope transaction
Process();
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
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
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()
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
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
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()
Cancel ongoing function
Cancel("Transaction canceled")
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”);
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
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”
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();
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();
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
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();
Field Name
Description
Values
xIsDebit
Indicates if the transaction was processed as debit.
True/False
[Click here to view the transaction workflows](https://kb.cardknox.com/payment-engine-sdk-flow)
[Download Our Sample Application](https://www.cardknox.com/wp-content/uploads/Plasti-Dip.zip)
[https://cdn.cardknox.com/pe/files/verifone\_unified\_driver\_installer-5.0.5.2-b5.zip](https://cdn.cardknox.com/pe/files/verifone_unified_driver_installer-5.0.5.2-b5.zip)
[https://docs.cardknox.com/#response-parameters](https://docs.cardknox.com/#response-parameters)
[https://kb.cardknox.com/api/#\_Sandbox\_Account\_Test\_Cases](https://kb.cardknox.com/api/#_Sandbox_Account_Test_Cases)
* [Overview](#overview)
* [Getting Started](#getting-started)
* [Initiate Transaction](#initiate-transaction)
* [Out-of-Scope (ProcessOutOfScope)](#out-of-scope)
* [In-Scope (Process)](#in-scope)
* [Backup gateway host](#backup-gateway-host)
* [Transaction Workflow](#transaction-workflow)
* [Transaction Functions](#transaction-functions)
* [Basic Parameters](#basic-parameters)
* [Transaction-Specific](#transaction-specific)
* [Form Settings](#form-settings)
* [Device Settings](#device-settings)
* [Cancel Command](#pin-signature)
* [PIN Signature](#pin-signature-1)
* [Receipt](#receipt)
* [Stored Account](#stored-account)
* [Show Items](#show-items)
* [Update Device](#update-device)
* [Additional Features](#additional-features)
* [Show Forms](#show-forms)
* [Response Parameters](#response-parameters)
* [Sandbox Account Test Cases](#sandbox-account-test-cases)
* [Offline transaction](#offline-transaction)
* [Troubleshooting steps](#troubleshooting-steps)
[Click Here to Download SDK Files](https://kb.cardknox.com/sdk)
[Cardknox Status](http://status.cardknox.com/)
---
# Introduction | Cardknox
Last updated 4 months ago
[](#knowledgebase-credentials)
Credentials
-----------------------------------------------
Across all Cardknox products we use a key (`xKey`) to identify on what account to process a specific transaction. Each Cardknox product doc will guide you where to set the `xKey` (for example: in the body of the request along with all other parameters, in the request header as “Authorization”, in the app settings etc.). You will have a unique `xKey` for and production accounts.
[](#best-practices)
Best practices
---------------------------------------
* **Transaction response** Transaction responses contain valuable information that you can utilize. The most important one is `xResult`; this will inform your system if the transaction was approved or declined. `xAuthAmount` will indicate how much was actually authorized by the bank, so it is a good idea to make sure that it matches the requested amount. By default, transactions will only approve for the full amount. If the full amount is not available, the transaction will be declined. Every transaction will receive a unique `xRefnum` that is used to identify this unique transaction. It is helpful during troubleshooting and is also used in case of a follow-up transaction (void refund, etc.). It is a good idea to display this `xRefNum` to the user and add it to receipts. You can find a full list of available response parameters .
* **Logs**
When submitting transaction requests to the Cardknox gateway, it is highly recommended to log the full request and response, including both the content body and headers. By logging this information, you ensure that critical details are readily available. In the event of any questions or troubleshooting needs, providing this information to the Cardknox support team will significantly reduce the time required to assist you or resolve the issue.
* **Declines** When a payment fails, you will get a `xResult` of `D` or `E`. Typically, you would simply want to display the failure notification to the user and show them the `xError` in the response that may, at times, contain helpful information to identify the reason for the decline. You can choose to allow the user to try another card. There is no need to handle different error messages or error codes specifically.
* **Duplicates** It is a good idea to pass in a unique xInvoice with each transaction that is sent for processing so Cardknox can try to catch unintentional duplicate payments. You can also give the user an option to intentionally process a duplicate payment by incrementing the invoice number or adding `xAllowDuplicate=true` to the transaction request. You can see more about duplicate payment handling .
[](#vendor-settings-optional)
Vendor Settings _(optional)_
---------------------------------------------------------------
A Vendor ID is a unique identifier associated with your vendor account. This feature is useful when you will be processing payments across multiple Cardknox accounts. It allows for specific settings to be configured on your vendor account, and these settings will be applied on transactions that include your Vendor ID in the transaction request. When using this feature, It is optimal to include your vendor ID across all transactions that you process on the Cardknox gateway.
####
[](#setup)
**Setup**
Our support team can enable your vendor account and provide you with the ID.
####
[](#usage)
**Usage**
To use Vendor settings, include the `xVendorID` = {yourvendorid} in the transactions request.
####
[](#features)
**Features/Benefits**
**iFields key:** Use a single iFields key across all your accounts.
**Tokenization:** Tokens can be used across accounts.
**Licenses:** Unlimited device licenses
[](#knowledgebase-tokenization)
Tokenization
-------------------------------------------------
Tokenization is the process of replacing sensitive payment data with a non-sensitive algorithm-generated `string` called a **token (**`**xToken**`**).** Each time you send a card or bank account number with a transaction, the response will include a token represented by `xToken`.
> With this approach, **sensitive data will not be at risk** if a data breach occurs on your local system.
Cardknox references the payment information on our servers associated with the token sent and processes the transaction. A new token will be returned on every new transaction processed.
You can reuse the original token multiple times. However, you should use the new returned token in the following scenarios:
* If the card has a new expiration date.
* If a response flag indicates, the card was updated/modified.
A token only stores the data sent with a transaction that is necessary to process future transactions. Tokens store the expiration date, street address, and zip code for credit card transactions. **Tokens do not store customer information, such as billing or contact information, other than street address and ZIP codes, sometimes required for validation by Address Verification System (AVS)**.
Cardknox servers will **never** store the 3 or 4 digit CVV number as per PCI regulations and, in extension, is not associated with tokens.
Only when a cardholder is processing an initial transaction, with a physical card in hand, is CVV data used.
Tokens can be used only on the account it was generated on unless linked to another account via **cross tokenization**
The best practice is to generate tokens on one account and link all other accounts to your first account instead of generating tokens for each.
To generate a token for a payment method without processing a transaction, use the save command.
* For credit card transactions: `cc:save`.
* For check transactions: `check:save`.
[](#knowledgebase-duplicatehandling)
Duplicate Handling
------------------------------------------------------------
The Cardknox Gateway automatically blocks a transaction considered a “duplicate” of another transaction based on certain identifying features and if the transactions are within 10 minutes (_default timeframe_) of each other. The transaction will error with a message of: `Duplicate Transaction`
Identifying Features:
* Key
* Credit Card Number
* Transaction Amount
* Invoice Number
* Check Account Number
* Check Routing Number
You can allow the transaction to go through by changing any of the above. Alternatively, you can pass through "`xAllowDuplicate` = True" in the transaction request.
You can set `xDuplicateWindow` with the number of minutes on a transaction request to override the default 10-minute timeframe of the duplicate checker.
[](#knowledgebase-batches)
Batches
---------------------------------------
Each day, batch files capture all of your transactions.
[](#response-parameters)
Response Parameters
-------------------------------------------------
Transactions that are submitted to the Cardknox API will return a response with one or more of the fields below. Below are the standard parameters and their values. The field names in parentheses are the fileds for the reporting API.
[](#sandbox-account-testing-info-and-triggers)
Sandbox Account Testing Info and Triggers
---------------------------------------------------------------------------------------------
A sandbox account is used to simulate transactions as if it is in production. It is designed to act exactly like a production account. However, there can sometimes be unique account setups where the production account won't match the sandbox account exactly to a T. Therefore, we recommend that you do all your testing in the sandbox account and then doing one final test when going live and swapping out your sandbox key with your production key.
####
[](#credit-card-and-account-numbers-hardbreak)
Credit Card and Account Numbers
You can use any valid card number to submit transactions while using a sandbox account. The card will not actually be charged as long as you are using your sandbox key. To avoid your system unintentionally going live while still configured with your sandbox credentials, transactions in the sandbox account are limited to $10. You can bypass that limit by using the below numbers.
Credit CardCheck (ACH)
###
[](#triggers)
Triggers
Declined TransactionPartial AuthDelay/TimeoutCVV Responses
(AllowPartialAuth must be set to True)
AVS ResponsesAlternative AVS Responses
As a merchant’s significantly increases when storing sensitive data, the best practice is to store the token in your database rather than sensitive data. You use the token for follow-up transactions.
You can request **account linking for tokenization** via .
By default, you can set it up to 1440 (24 Hours) max. Your account can be set to allow up to 43200 (30 Days) via .
Cardknox automatically “batches out” once the **batch cutoff time** is reached (_determined by the processing bank_) and sends the related transactions to the bank for settlement. A batch report is available in the .
Card Type
Card Number
Account Number
Routing Number
xAmount
Behavior
Response
The Cardknox gateway does not require developers to go through a certification process. We do provide a process to self-certify if developers choose to do so. You can download the .
Visa
4444333322221111
Visa
4111111111111111
Mastercard
5454545454545454
Discover
6011208703331119
American Express
370276000431054
EBT
6004861944321111844
Pledger
6599973548556861
DonorsFund
6599993776775348
OJC
6900664467242419
999999999
021000021 (any valid routing number)
**xName**
**Response**
Decline
Declined
**xAmount**
**AuthAmount**
**7.5**
1.5
**7.23**
1.23
**7.31**
Response delayed 30 seconds
Try Again
**7.32**
Response delayed 30 seconds
Try Again
**7.29**
Response delayed 30 seconds
Approved
**xDescription**
**Behavior**
**Response**
**Delay**
Response delayed 30 seconds
Approved
**Timeout**
Response delayed 30 seconds
Try Again
**Timeout\_Extended**
Response delayed 120 seconds
Try Again
**xCVV**
**CVV Result**
**CVV Result Code**
**123**
M
Match
**1234**
M
Match
**111**
M
Match
**1111**
M
Match
**222**
N
No Match
**2222**
N
No Match
**555**
P
Not Processed
**444**
S
Should be on card, but not so indicated
**8888**
U
Issuer Not Certified
**7777**
X
No Response from Association
**xStreet**
**xZip**
**AvsResultCode**
**xAvsResult**
**111**
11111
YYY
Address: Match & 5 Digit Zip: Match
**999**
99999
NNN
Address: No Match & 5 Digit Zip: No Match
**111**
111111111
YYX
Address: Match & 9 Digit Zip: Match
**111**
99999
YNA
Address: Match & 5 Digit Zip: No Match
**999**
111111111
NYW
Address: No Match & 9 Digit Zip: Match
**999**
11111
NYZ
Address: No Match & 5 Digit Zip: Match
**888**
88888
XXR
Retry / System Unavailable
**777**
77777
XXU
Address Information not verified for domestic transaction
**666**
66666
XXS
Service Not Supported
**AvsResultCode**
**xAvsResult**
**Y**
Address: Match & 5 Digit Zip: Match
**Z**
No Match & 5 Digit Zip: Match
**A**
Address: Match & 5 Digit Zip: No Match
**N**
Address: No Match & 5 Digit Zip: No Match
**X**
Address: Match & 9 Digit Zip: Match
**W**
Address: No Match & 9 Digit Zip: Match
**R**
Retry / System Unavailable
**S**
Service Not Supported
[sandbox](https://www.cardknox.com/sandbox/)
[here](https://docs.cardknox.com/#response-parameters)
[here](https://docs.cardknox.com/#knowledgebase-duplicatehandling)
[PCI-compliance scope](https://www.cardknox.com/white-papers/pci-compliance-the-biggest-myths-explained/)
[Support](https://www.cardknox.com/contact-3/integration-question/)
[Support](https://www.cardknox.com/contact-3/integration-question/)
[Cardknox Merchant Portal](https://portal.cardknox.com/)
[Cardknox Self-certification Guide](https://kb.cardknox.com/wp-content/uploads/CardknoxCertScript.xlsx)
* [Credentials](#knowledgebase-credentials)
* [Best practices](#best-practices)
* [Vendor Settings (optional)](#vendor-settings-optional)
* [Tokenization](#knowledgebase-tokenization)
* [Duplicate Handling](#knowledgebase-duplicatehandling)
* [Batches](#knowledgebase-batches)
* [Response Parameters](#response-parameters)
* [Sandbox Account Testing Info and Triggers](#sandbox-account-testing-info-and-triggers)
* [Triggers](#triggers)
**Field Name**
**Description**
**Sample values**
**xResult** (xGatewayResult)
Single character code indicating if the transaction was Approved or not. A = Approved E = Error D = Declined
A E D
**xStatus** (xResponseResult)
Verbiage indicating if the transaction was approved or not.
Approved Error Declined
**xError** (xResponseError)
Error message, if applicable
See error code
**xErrorCode**
Error code
Most common error codes: 00000 = Approved 01332 = Duplicate Transaction 1334 = Declined Transaction 01479 = Invalid Card
**xRefNum**
Cardknox transaction reference number Note: xRefnum is always returned regardless of the outcome of the transaction Note: `xRefnum` can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String
**xInvoice**
Invoice number
**xExp**
The card expiration number
**xAuthCode** (xResponseAuthCode)
Authorization code, for approved transactions only
**xBatch** (xResponseBatch)
Batch into which the transaction will settle
**xAvsResultCode** (xResponseAVSCode)
The Address Verification Service (AVS) response code
YYY = Address: Match & 5 Digit Zip: Match NYZ = Address: **No Match** & 5 Digit Zip: Match YNA = Address: Match & 5 Digit Zip: **No Match** NNN = Address: **No Match** & 5 Digit Zip: **No Match** XXU = Address Information not verified for domestic transaction YYX = Address: Match & 9 Digit Zip: Match NYW = Address: No Match & 9 Digit Zip: Match XXR = Retry / System Unavailable XXS = Service Not Supported XXW = Card Number Not On File XXE = Address Verification Not Allowed For Card Type XXG = Global Non-AVS participant YYG = International Address: Match & Zip: Not Compatible GGG = International Address: Match & Zip: Match YGG = International Address: Not Compatible & Zip: Match
Alternative Responses
AvsResultCodexAvsResultYAddress: Match & 5 Digit Zip: MatchZNo Match & 5 Digit Zip: MatchAAddress: Match & 5 Digit Zip: No MatchNAddress: No Match & 5 Digit Zip: No MatchXAddress: Match & 9 Digit Zip: MatchWAddress: No Match & 9 Digit Zip: MatchRRetry / System UnavailableSService Not Supported
**xAvsResult**
AVS verbiage
See AVS result code
**xCvvResultCode** (xResponseCVVCode)
Card code verification (CCV) response code
M = Match N = No Match P = Not Processed S = Should be on card, but not so indicated U = Issuer Not Certified X = No Response from Association
**xCvvResult**
CVV verbiage
See CVV result code
**xAuthAmount** (xAmount)
The total amount authorized, inclusive of tax and tip (if applicable)
**xMaskedCardNumber**
A masked version of the credit card used for the transaction
**xCardType**
Type of credit card used for the transaction
Unknown EBT GiftCard Amex Visa MasterCard Discover Diners JCB DonorsFund OJC Pledger
**xName**
Name of cardholder
John
**xToken**
Token returned for use with future transaction
gh3hpn46mp0g785915gn7h79q502976n
**xCurrency**
Currency that the transaction was processed in
USD
**xEntryMethod**
Transaction method
Keyed EMV Swipe
**xDate**
Date and time the transaction was processed
1/1/2020 10:00:00 AM
**xRefnumCurrent**
Current reference number
**Used for troubleshooting purposes only.** Returned when using a command that modifies an existing transaction, such as cc:void, cc:capture, or cc:adjust.
**xReviewed**
This will be returned only if account is configured to return this response field.
Y = Transaction was authenticated by 3ds. If authentication was submitted to the bank, the merchant will have chargeback protection.
P = Transaction was authenticated by 3ds. If authentication was submitted to the bank, the merchant may not have chargeback protection.
N =Transaction was not able to achieve 3ds authentication. If authentication was submitted to the bank, the merchant may not have chargeback protection.
F = The 3ds authentication process completed but the bank response indicated that the results were invalid. The merchant will not have fraud chargeback protection.
x3dsSubmitted
This indicates if the bank request included 3ds data elements.
1 = The bank request included 3ds data elements.
(xStatus)
The ACH status that you receive in webhooks
0 (Pending)
20 (Rejected)
5 (Cancelled)
6 (Awaiting Response)
14 (Chargeback)
16 (Settled)
18 (Returned)
19 (Hold)
xIssuerResponseCode
This code received from the card association / issuer will be returned when available.
[See All Error Codes](/api/error-codes)
---
# Account Boarding API | Cardknox
Last updated 11 days ago
[](#overview)
Overview
---------------------------
The Cardknox Account Boarding API gives ISV partners the ability to board PayFac accounts directly through their system, rather than from the Partner Portal. Using the Account Boarding API, ISVs can build a form within their system for collecting all the necessary merchant data to onboard Cardknox Go accounts. Once the ISV submits the application via the API, it is passed along to Cardknox for instant approval.
This page outlines the configuration process for integrating with Cardknox’s Account Boarding API.
Visualize and interact with the API using Swagger UI. Please note that only sandbox keys may be used when submitting accounts and the `Signature.Token` field is not required.
[](#api-endpoints)
API Endpoints
-------------------------------------
###
[](#gettiers)
GetTierNames
**URL**:
**Description:** The GetTierNames endpoint gives a list of available tiers that can be passed along to the SubmitGoApp request.
**Method**: POST
**Input**: JSON
####
[](#request)
Request **Headers**
####
[](#response)
Sample Request:
####
[](#response-1)
Response
**Sample Success Response:**
**Sample Error Response:**
###
[](#submitgoapp)
SubmitGoApp
The SubmitGoApp end point will create a GoPlus Application.
**Description:**
The SubmitGoApp endpoint validates the request and generates an application if the account associated with the API key is authorized to board Cardknox Go accounts. If it is a Sandbox request, the equipment will be created immediately.
**Method**: POST
**Input**: JSON
####
[](#request.1)
Request
**BankingDetails**
**SignerDetails**
**Address**
**Signature**
**Sample Request**
####
[](#response.1)
Response
**Sample Success Response**
**Sample Error Response:**
**URL**:
for more information on how to obtain tokens.
**Parameter**
**Description**
`status`
* Success
* Error
`refnum`
`error`
* Error Code
* Error Message
`tiers`
List of available tiers
**Parameter**
**Type**
**Description**
**Required**
ApiKey
String
Authentication Key
True
TierName
String
Name of tier
True
CorporateName
String
Business’s legal name
True
DBAName
String
Business’s DBA Name, if no DBA default to CorporateName
True
AnnualCreditCardSales
Number
Credit card sales for the last full year
False
OwnershipType
Enum
Ownership structure
Valid values are:
* SoleProprietor
* Partnership
* Corporation
* SoleOwnership
* LLC
* NonProfit
True
BusinessStartDate
Date
Start date of the business in YYYY-MM-DD format
True
AgentName
String
Full name of primary agent
False
AgentEmail
String
Email address of primary agent
False
Website
String
Business website
False
TaxId
String
Business EIN / Tax Identification Number
True
BusinessEmail
String
Business email address
True
BusinessPhone
String
Business phone number (format: 000-000-0000)
True
BusinessAddress
Object
Object containing business address fields
True
MailingAddress
Object
Object containing business mailing address fields
True
ProductSold
String
Short description of product sold
True
BankingInformation
Object
Object containing banking information including bank name, routing number, and account number
True
SecondaryBankingInformation
Object
Object containing banking information including bank name, routing number, and account number
False
SignerInformationList
Object
Object containing signer information
True
Signature
Object
Signature Object contains the Token string. Token is from the terms and conditions confirmation.
For production accounts, it must be set to a valid value.
True
AverageTicket
Number
Average value of each sale
True
MonthlySalesVolume
Number
Credit card sales for the last full month
True
HighTicket
Number
Largest ticket size
True
**Field Name**
**Description**
BankName
String, Required
RoutingNumber
String, Required, must be a valid 9-digit routing number
AccountNumber
String, Required, numeric value between 6 and 17 characters
**Field Name**
**Description**
SSN
String, Required
DateOfBirth
Date, Required, minimum age is 18
FirstName
String, Required
LastName
String, Required
Address
Address, Required
OwnershipPercentage
Decimal, Required
Title
String, Required
Valid Values:
* Treasurer
* Owner
* Partner
* CEO
* Secretary
* Director
* Other
* Sole Proprieter
OwnerCellPhone
String, Required (format: 000-000-0000)
**Field Name**
**Description**
StreetAddress
String, Required
City
String, Required
State
String, Required, 2 digit state code
Zip
String, Required, 5 digits
Country
String, Optional
**Field Name**
**Description**
Token
Token from the terms and conditions confirmation, Required
For production accounts, it must be set to a valid value
**Parameter**
**Description**
Status
* Success
* Error
Refnum
Error
* Error Code
* Error Messages - List of errors
AppId
**Parameter**
**Type**
**Description**
**Required**
ApiKey
String
Authentication credentials
True
[See this API on Swagger UI](https://psapi.cardknox.com/boarding/v1/swagger/index.html)
[https://psapi.cardknox.com/boarding/v1/GetTierNames](https://psapi.cardknox.com/boarding/v1/GetTierNames)
Copy
{
"apiKey": "0d48f767f1d34d088ae59a214fe11e25"
}
Copy
{
"tiers": [\
"123_tier1",\
"123_tier2"\
],
"refnum": "brd258465289",
"status": "Success"
}
Copy
{
"refnum": "brd258465289",
"status": "Error",
"error": {
"errorCode": "AccessDenied",
"errorMessages": [ \
"Access Denied" \
]
}
}
[https://psapi.cardknox.com/boarding/v1/SubmitGoApp](https://psapi.cardknox.com/boarding/v1/SubmitGoApp)
Copy
{
"apiKey": "{{API_KEY}}",
"tierName": "{{TIER}}",
"corporateName": "Acme Corp",
"dbaName": "Acme Corporation",
"annualCreditCardSales": "80000",
"monthlySalesVolume": 1000,
"highTicket": 500,
"averageTicket": 250,
"ownershipType": "corporation",
"businessStartDate": "2005-08-01",
"agentName": "John Smith",
"agentEmail": "john.smith@test.com",
"website": "http://www.acmecorporation.com/",
"taxId": "225555555",
"businessEmail": "robert@acmecorporation.com",
"businessPhone": "800-555-1212",
"businessAddress": {
"streetAddress": "1213 Main Street",
"city": "Anytown",
"state": "AL",
"zip": "11111",
"country": "United States"
},
"mailingAddress": {
"streetAddress": "1213 Main Street",
"city": "Anytown",
"state": "AL",
"zip": "11111",
"country": "United States"
},
"productSold": "Convenience Goods",
"bankingInformation": {
"bankName": "Chase",
"routingNumber": "021000021",
"accountNumber": "454545454545"
},
"secondaryBankingInformation": {
"bankName": "Chase",
"routingNumber": "121122676",
"accountNumber": "898989898989"
},
"signerInformationList": [\
{\
"ssn": "115668989",\
"dateOfBirth": "1955-07-14",\
"firstName": "Robert",\
"lastName": "Brown",\
"address": {\
"streetAddress": "1213 Main Street",\
"city": "Anytown",\
"state": "AL",\
"zip": "11111",\
"country": "United States"\
},\
"ownershipPercentage": 100,\
"title": "Owner",\
"ownerCellPhone": "222-333-4444"\
}\
],
"signature": {
"token": ""
}
}
Copy
{
"appId": 9854,
"refnum": "brd221002160",
"status": "Success"
}
Copy
{
"status": "Error",
"error": {
"errorCode": "BadRequest",
"errorMessages": [ \
"BusinessAddress.State: The State field is required.", \
"SignerInformationList[0].SSN: The SSN field is required." \
]
}
}
* [Overview](#overview)
* [API Endpoints](#api-endpoints)
* [GetTierNames](#gettiers)
* [SubmitGoApp](#submitgoapp)
[Click here](/api/account-boarding-api/account-boarding-merchant-agreement)
---