Create a SandboxContact Us

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:

Transactions

Issue

POST gift:issue

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

Request Body

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

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

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

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

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

Last updated