Fraud

Overview

This page contains all API documentation for Gift Card transactions. For more information regarding account access, navigate to the Transaction API parent page.

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

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. Click here 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.

Endpoints

Health Check

HTTP Request Method: GET

https://x1.cardknox.com/status

Transactions

HTTP Request Method: POST

Cardknox allows you to send the data in FormData, JSON, and XML formats.

Add to the base URL any of the following formats to indicate which format you are sending it as:

FormData	/gatewayform	https://x1.cardknox.com/gatewayform
JSON	/gatewayjson	https://x1.cardknox.com/gatewayjson
XML	/gatewayxml	https://x1.cardknox.com/gatewayxml

Transactions

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

Name	Type	Description
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.

Fraud Submit - Request Payload Example

{ 
    "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": "[e-mail]", 
    "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": "[e-mail]", 
    "xAllowDuplicate": "TRUE" 
}