Gift Card

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

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

Issue

POST gift:issue

xCommand = gift:issue The Issue command is used to issue funds to a Cardknox gift card.

Request Body

Name
Type
Description

xCardNum*

String

The customer card number. *Alternatively, xToken xMagStripe or SUT can be used.

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.

xToken

String

The Cardknox token that references a previously used payment card. When using this variable, xCardNumand xMagstripe should not be used maximum 50 alphanumeric characters).

xCustom01*

String

20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.

xMagstripe

String

The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum xExp and xToken should not be used. Encryptedcard data can also be sent using xMagstripe

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)

xInvoice

String

The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling.

xPONum

String

The merchant’s purchase order number for the transaction

xComments

String

Additional data that is optionally passed along to the receipt

xDescription

String

Additional data that is optionally passed along for reporting

xIP

String

The customer’s IP address. Typically used for fraud detection.

xEmail

String

The customer’s email address

xFax

String

The customer’s fax number

xBillFirstName

String

The customer’s first name for their billing profile

xBillMiddleName

String

The customer’s middle name or initial for their billing profile

xBillLastName

String

The customer’s last/family name for their billing profile

xBillCompany

String

The customer’s company name for their billing profile

xBillStreet

String

The customer’s street address for their billing profile

xBillStreet2

String

The customer’s street address 2nd line 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

xBillCountry

String

The customer’s country for their billing profile

xBillPhone

String

The customer’s phone number for their billing profile

xBillMobile

String

The customer’s mobile number for their billing profile

xShipFirstName

String

The customer’s first name for their shipping profile

xShipMiddleName

String

The customer’s middle name or initial for their shipping profile

xShipLastName

String

The customer’s last/family name for their shipping profile

xShipCompany

String

The customer’s company name for their shipping profile

xShipStreet

String

The customer’s street address for their shipping profile

xShipStreet2

String

The customer’s street address 2nd line 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

xShipCountry

String

The customer’s country for their shipping profile

xShipPhone

String

The customer’s phone number for their shipping profile

xShipMobile

String

The customer’s mobile number for their shipping profile

xAllowDuplicate

String

By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed.

xOrderID

String

Unique order number for FraudWatch verification

xExistingCustomer

String

Yes/No value indicating if the customer is a repeat customer

xExp

String

Gift card expiration number. Format: MMYY. For sandbox accounts, use any date in the future. *Required and available only when xCardNum is used.

xCVV

String

3-digit code from the back of the card (for Amex, 4-digit code from the front of the card)

xStreet

String

The billing street address of the cardholder

xZip

String

The billing zip code of the cardholder

xDUKPT

String

The DUK/PT key for PIN debit and EBT transactions.The first 16 characters are the encrypted PIN block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN pad serial number and transaction counter.

xTimeoutSeconds

String

Configurable amount of seconds in which the request will wait for a response.

xSupports64BitRefnum

String

True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

Issue - Request Payload Example
{ 
    "xCardNum": "4444333322221111", 
    "xKey": "[xkeycredentials]", 
    "xVersion": "4.5.9", 
    "xSoftwareName": "YourSoftwareName", 
    "xSoftwareVersion": "1.0.0", 
    "xCommand": "gift:issue",
    "xAmount": "35.00",
    "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", 
    "xDUKPT": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;444433", 
    "xTax": "2.00", 
    "xTip": "2.00", 
    "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", 
    "xOrderID": "12356", 
    "xExistingCustomer": "TRUE", 
    "xAllowDuplicate": "TRUE",
    "xTimeoutSeconds": "10"
}

Redeem

POST gift:redeem

xCommand = gift:redeem

The Redeem command is used to debit funds from a Cardknox gift card.

Request Body

Name
Type
Description

xCardNum*

String

The customer card number. *Alternatively, xToken xMagStripe or SUT can be used.

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.

xToken

String

The Cardknox token that references a previously used card. When using a variable, xCardNumand xMagstripe should no be used (maximum 50 alphanumeric characters).

xCustom01*

String

20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.

xMagstripe

String

The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe.

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)

xInvoice

String

The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling.

xPONum

String

The merchant’s purchase order number for the transaction

xComments

String

Additional data that is optionally passed along to the receipt

xDescription

String

Additional data that is optionally passed along for reporting

xIP

String

The customer’s IP address. Typically used for fraud detection.

xEmail

String

The customer’s email address

xFax

String

The customer’s fax number

xBillFirstName

String

The customer’s first name for their billing profile

xBillMiddleName

String

The customer’s middle name or initial for their billing profile

xBillLastName

String

The customer’s last/family name for their billing profile

xBillCompany

String

The customer’s company name for their billing profile

xBillStreet

String

The customer’s street address for their billing profile

xBillStreet2

String

The customer’s street address 2nd line 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

xBillCountry

String

The customer’s country for their billing profile

xBillPhone

String

The customer’s phone number for their billing profile

xBillMobile

String

The customer’s mobile number for their billing profile

xShipFirstName

String

The customer’s first name for their shipping profile

xShipMiddleName

String

The customer’s middle name or initial for their shipping profile

xShipLastName

String

The customer’s last/family name for their shipping profile

xShipCompany

String

The customer’s company name for their shipping profile

xShipStreet

String

The customer’s street address for their shipping profile

xShipStreet2

String

The customer’s street address 2nd line 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

xShipCountry

String

The customer’s country for their shipping profile

xShipPhone

String

The customer’s phone number for their shipping profile

xShipMobile

String

The customer’s mobile number for their shipping profile

xAllowDuplicate

String

By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed.

xOrderID

String

Unique order number for FraudWatch verification

xExistingCustomer

String

Yes/No value indicating if the customer is a repeat customer

xExp

String

Gift card expiration number. Format: MMYY. For sandbox accounts, use any date in the future. *Required and available only when xCardNum is used.

xCVV

String

3-digit code from the back of the card (for Amex, 4-digit code from the front of the card).

xStreet

String

The billing street address of the cardholder

xZip

String

The billing zip code of the cardholder

xDUKPT

String

The DUK/PT key for PIN debit and EBT transactions.The first 16 characters are the encrypted PIN block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN pad serial number and transaction counter.

xTimeoutSeconds

String

Configurable amount of seconds in which the request will wait for a response.

xSupports64BitRefnum

String

True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

Redeem - Request Payload Example
{ 
    "xCardNum": "4444333322221111", 
    "xKey": "[xkeycredentials]", 
    "xVersion": "4.5.9", 
    "xSoftwareName": "YourSoftwareName", 
    "xSoftwareVersion": "1.0.0", 
    "xCommand": "gift:redeem",
    "xAmount": "35.00",
    "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", 
    "xDUKPT": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;444433", 
    "xTax": "2.00", 
    "xTip": "2.00", 
    "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", 
    "xOrderID": "12356", 
    "xExistingCustomer": "TRUE", 
    "xAllowDuplicate": "TRUE",
    "xTimeoutSeconds": "10"
}

Balance

POST gift:balance

xCommand = gift:balance The Balance command is used to check the available balance on a Cardknox gift card.

Request Body

Name
Type
Description

xCardNum*

String

The customer card number. *Alternatively, xToken xMagStripe or SUT can be used.

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

xToken

String

The Cardknox token that references a previously used payment method. When using a token, xCardNum xExp and xMagstripe should not be used.

xMagstripe

String

The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum xExp and xToken should not be used. Encrypted card data can also be sent using xMagstripe.

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)

xInvoice

String

The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling.

xPONum

String

The merchant’s purchase order number for the transaction

xComments

String

Additional data that is optionally passed along to the receipt

xDescription

String

Additional data that is optionally passed along for reporting

xIP

String

The customer’s IP address. Typically used for fraud detection

xEmail

String

The customer’s email address

xFax

String

The customer’s fax number

xBillFirstName

String

The customer’s first name for their billing profile

xBillMiddleName

String

The customer’s middle name or initial for their billing profile

xBillLastName

String

The customer’s last/family name for their billing profile

xBillCompany

String

The customer’s company name for their billing profile

xBillStreet

String

The customer’s street address for their billing profile

xBillStreet2

String

The customer’s street address 2nd line 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

xBillCountry

String

The customer’s country for their billing profile

xBillPhone

String

The customer’s phone number for their billing profile

xBillMobile

String

The customer’s mobile number for their billing profile

xShipFirstName

String

The customer’s first name for their shipping profile

xShipMiddleName

String

The customer’s middle name or initial for their shipping profile

xShipLastName

String

The customer’s last/family name for their shipping profile

xShipCompany

String

The customer’s company name for their shipping profile

xShipStreet

String

The customer’s street address for their shipping profile

xShipStreet2

String

The customer’s street address 2nd line 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

xShipCountry

String

The customer’s country for their shipping profile

xShipPhone

String

The customer’s phone number for their shipping profile

xShipMobile

String

The customer’s mobile number for their shipping profile

xAllowDuplicate

String

By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed.

xOrderID

String

Unique order number for FraudWatch verification

xExistingCustomer

String

Yes/No value indicating if the customer is a repeat customer

xExp

String

The card expiration number. Format: MMYY. For sandbox test transactions, use any date in the future. *xExp is required when sending in xCardnum and cannot be used with xMagstripe.

xCVV

String

3-digit code from the back of the card (for Amex, 4-digit code from the front of the card).

xStreet

String

The billing street address of the cardholder

xZip

String

The billing zip code of the cardholder

xDUKPT

String

The DUK/PT key for PIN debit and EBT transactions.The first 16 characters are the encrypted PIN block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN pad serial number and transaction counter.

Custom01

String

20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.

xAuthCode

String

xAuthCode is a verification number provided by the issuing bank to be used with the cc:postauth command

xRefNum

String

Used to reference a previous transaction when processing a follow-up transaction, typically a refund, void, or capture. (Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String).

xMICR

String

The routing, account, and check number data from the bottom of a check in MICR (Magnetic Ink Character Recognition) format, typically generated by a check scanner

xRouting

String

The check ABA routing number

xGatewayRefNum

String

Transaction RefNum received from gateway for FraudWatch verification

xGatewayResult

String

Transaction status received from gateway for FraudWatch verification (Approved/Declined/Error)

xGatewayError

String

Transaction RefNum received from gateway for FraudWatch verification.

xGatewayCVV

String

CVV for for FraudWatch verification.

xOrderType

String

Specifies if the order origin is internet OR phone for FraudWatch verification

xGatewayAVS

String

Street address for FraudWatch verification

xOrderItems

String

Summary of products ordered

xCustomerComments

String

Comments submitted by thecustomer along with the order

xShipMethod

String

The shipping carrier/service used

xShipAmount

String

The total cost of shipping charges

xShipEmail

String

The ShipTo email address

xSupports64BitRefnum

String

True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

Balance - Request Payload Example
{ 
    "xCardNum": "4444333322221111", 
    "xKey": "[xkeycredentials]", 
    "xVersion": "4.5.9", 
    "xSoftwareName": "YourSoftwareName", 
    "xSoftwareVersion": "1.0.0", 
    "xCommand": "gift:balance", 
    "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" 
}

Activate

POST gift:activate

xCommand = gift:activate The Activate command is used to activate a Cardknox gift card.

Request Body

Name
Type
Description

xCardNum*

String

The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used.

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

xSupports64BitRefnum

String

True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

Activate - Request Payload Example
{ 
    "xCardNum": "4444333322221111", 
    "xKey": "[xkeycredentials]", 
    "xVersion": "4.5.9", 
    "xSoftwareName": "YourSoftwareName", 
    "xSoftwareVersion": "1.0.0", 
    "xCommand": "gift:activate"
}

Deactivate

POST gift:deactivate

xCommand = gift:deactivate The Deactivate command is used to deactivate a Cardknox gift card.(note: you can still check the balance of the gift card even after it has been deactivated).

Request Body

Name
Type
Description

xCardNum*

String

The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used.

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

xSupports64BitRefnum

String

True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

Deactivate - Request Payload Example
{ 
    "xCardNum": "4444333322221111", 
    "xKey": "[xkeycredentials]", 
    "xVersion": "4.5.9", 
    "xSoftwareName": "YourSoftwareName", 
    "xSoftwareVersion": "1.0.0", 
    "xCommand": "gift:deactivate"
}

Last updated