EBT Online

Overview
EBT (Electronic Benefits Transfer) cards allow customers to pay for food and other products through government-funded financial assistance programs. One of the largest such programs is the Supplemental Nutrition Assistance Program (SNAP). SNAP is managed by the U.S. Department of Agriculture (USDA).
To qualify for SNAP EBT online processing, retailers must meet SNAP's food stocking requirements as well as their online purchasing requirements. One of the online purchasing requirements for retailers is to integrate their online shopping cart with a third-party processor that offers a digital PIN pad. Cardknox’s EBT solution utilizes a third-party PIN pad so that EBT cardholders can securely type in their PIN online just as they would in-store. Once the customer makes a payment with their EBT card, they are able to see the remaining balance on their card and complete the transaction.
During the implementation process, keep in mind that when submitting a sale transaction, you can add up to a 10% padding to the amount if the final price needs to be adjusted upon completing the order. When completing the order, the retailer would refund the remaining amount. Retailers must follow the refund process and not issue refunds using cash or gift cards.
Endpoints
The base URL to send transactions to is https://x1.cardknox.com
Additionally, the backup URL is https://b1.cardknox.com

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:
Format
Addtional URL
Full URL
FormData
/gateway
https://x1.cardknox.com/gateway
JSON
/gatewayjson
https://x1.cardknox.com/gatewayjson
XML
/gatewayxml
https://x1.cardknox.com/gatewayxml
As noted above, you can use “https://b1.cardknox.com" as an alternative backup URL.
Request Method
Method: POST
Cardknox Gateway requires an HTTP POST method to be used for enhanced security.
We do not support the GET method.
Request / Commands to the Cardknox Gateway
ebtonline:initiate
This API call will return the information needed to redirect the user to the PIN pad.
A PIN is needed for the ebtonline:fssale, ebtonline:cbsale, and ebtonline:balance commands.
Variable
Required
Description
Sample data
xKey
Yes
Your Cardknox API Key.
[xkeycredentials]
xVersion
Yes
Gateway API Version. The current version is 4.5.9
4.5.9
xSoftwareName
Yes
Name of your software.
[xsoftwarecredentials]
xSoftwareVersion
Yes
Version number of your software.
[xversioncredentials]
xCardNum
Yes
The customer card number. Alternatively, xToken xMagStripe or SUT can be used.
6004861944321111844
xBillLastName
Yes*
The customer’s last/family name for their billing profile.
 
xBillCompany
Yes*
Customer's company name for their billing profile.
 
xBillStreet
Yes*
Customer's street address for their billing profile.
 
xBillStreet2
Yes*
Customer's street address second line for their billing profile.
 
xBillCity
Yes*
Customer's city for their billing profile.
 
xBillState
Yes*
Customer's state for their billing profile.
 
xBillZip
Yes*
Customer's ZIP code or postal code for their billing profile.
 
xBillCountry
Yes*
Customer's country for their billing profile.
 
xBillPhone
Yes*
Customer's phone number for their billing profile.
 
xBillMobile
Yes*
Customer's mobile number for their billing profile.
 
xShipMethod
Yes
Identify the shipping method
DirectDelivery
CustomerPickup
CommercialShipping
Other
xShipFirstName
Yes*
Customer’s first name for their shipping profile.
 
xShipMiddleName
Yes*
Customer’s middle name or initial for their shipping profile.
 
xShipLastName
Yes*
Customer’s last/family name for their shipping profile.
 
Parameter Notes:
*This field can be sent either on the initiate transaction or follow up command transaction
**Required if xShipMethod is anything other than customer pickup
​
ebtonline:fssale
Process an EBT Online transaction to transfer funds from an EBT card to the retailer.
Variable
Required
Description
Sample data
xKey
Yes
Your Cardknox API Key.
[xkeycredentials]
xVersion
Yes
Gateway API Version. The current version is 4.5.9
4.5.9
xSoftwareName
Yes
Name of your software.
[xsoftwarecredentials]
xSoftwareVersion
Yes
Version number of your software.
[xversioncredentials]
xAmount
Yes
The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction.
9.99
xBillStreet
Yes*
Customer's street address for their billing profile.
 
xBillStreet2
Yes*
Customer's street address second line for their billing profile.
 
xBillCity
Yes*
Customer's city for their billing profile.
 
xBillState
Yes*
Customer's state for their billing profile.
 
xBillZip
Yes*
Customer's ZIP code or postal code for their billing profile.
 
xBillCountry
Yes*
Customer's country for their billing profile.
 
xBillPhone
Yes*
Customer's phone number for their billing profile.
 
xBillMobile
Yes*
Customer's mobile number for their billing profile.
 
xShipFirstName
Yes*
Customer’s first name for their shipping profile.
 
xShipMiddleName
Yes*
Customer’s middle name or initial for their shipping profile.
 
xShipLastName
Yes*
Customer’s last/family name for their shipping profile.
 
xShipCompany
Yes*
Customer’s company name for their shipping profile.
 
xShipPhone
No
Customer’s phone number for their shipping profile.
 
xShipMobile
No
Customer’s mobile number for their shipping profile.
 
Parameter Notes:
*This field can be sent either on the initiate transaction or follow up command transaction
**Required if xShipMethod is anything other than customer pickup
​
ebtonline:cbsale
Process an EBT Online cash benefits transaction to transfer funds from an EBT card to the retailer.
Variable
Required
Description
Sample data
xKey
Yes
Your Cardknox API Key.
[xkeycredentials]
xVersion
Yes
Gateway API Version. The current version is 4.5.9
4.5.9
xSoftwareName
Yes
Name of your software.
[xsoftwarecredentials]
xSoftwareVersion
Yes
Version number of your software.
[xversioncredentials]
xAmount
Yes
The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction.
9.99
xBillStreet
Yes*
Customer's street address for their billing profile.
 
xBillStreet2
Yes*
Customer's street address second line for their billing profile.
 
xBillCity
Yes*
Customer's city for their billing profile.
 
xBillState
Yes*
Customer's state for their billing profile.
 
xBillZip
Yes*
Customer's ZIP code or postal code for their billing profile.
 
xBillCountry
Yes*
Customer's country for their billing profile.
 
xBillPhone
Yes*
Customer's phone number for their billing profile.
 
xBillMobile
Yes*
Customer's mobile number for their billing profile.
 
xShipFirstName
Yes*
Customer’s first name for their shipping profile.
 
xShipMiddleName
Yes*
Customer’s middle name or initial for their shipping profile.
 
xShipLastName
Yes*
Customer’s last/family name for their shipping profile.
 
xShipCompany
Yes*
Customer’s company name for their shipping profile.
 
xShipPhone
No
Customer’s phone number for their shipping profile.
 
xShipMobile
No
Customer’s mobile number for their shipping profile.
 
Parameter Notes:
*This field can be sent either on the initiate transaction or follow up command transaction
**Required if xShipMethod is anything other than customer pickup
ebtonline:balance
Check the available balance on an EBT card
Variable
Required
Description
Sample data
xKey
Yes
Your Cardknox API Key.
[xkeycredentials]
xVersion
Yes
Gateway API Version. The current version is 4.5.9
4.5.9
xSoftwareName
Yes
Name of your software.
[xsoftwarecredentials]
xSoftwareVersion
Yes
Version number of your software.
[xversioncredentials]
xBillStreet
Yes*
Customer's street address for their billing profile.
 
xBillStreet2
Yes*
Customer's street address second line for their billing profile.
 
xBillCity
Yes*
Customer's city for their billing profile.
 
xBillState
Yes*
Customer's state for their billing profile.
 
xBillZip
Yes*
Customer's ZIP code or postal code for their billing profile.
 
xBillCountry
Yes*
Customer's country for their billing profile.
 
xBillPhone
Yes*
Customer's phone number for their billing profile.
 
xBillMobile
Yes*
Customer's mobile number for their billing profile.
 
xShipFirstName
Yes*
Customer’s first name for their shipping profile.
 
xShipMiddleName
Yes*
Customer’s middle name or initial for their shipping profile.
 
xShipLastName
Yes*
Customer’s last/family name for their shipping profile.
 
xShipCompany
Yes*
Customer’s company name for their shipping profile.
 
xShipPhone
No
Customer’s phone number for their shipping profile.
 
xShipMobile
No
Customer’s mobile number for their shipping profile.
 
xRefnum
Yes
A unique request ID.
 
Parameter Notes:
*This field can be sent either on the initiate transaction or follow up command transaction
**Required if xShipMethod is anything other than customer pickup
​
ebtonline:refund
Process an EBT online refund transaction to return funds from the retailer to the cardholder.
Variable
Required
Description
Sample data
xKey
Yes
Your Cardknox API Key.
[xkeycredentials]
xVersion
Yes
Gateway API Version. The current version is 4.5.9
4.5.9
xSoftwareName
Yes
Name of your software.
[xsoftwarecredentials]
xSoftwareVersion
Yes
Version number of your software.
[xversioncredentials]
xAmount
No
The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction.
9.99
xBillStreet
Yes*
Customer's street address for their billing profile.
 
xBillStreet2
Yes*
Customer's street address second line for their billing profile.
 
xBillCity
Yes*
Customer's city for their billing profile.
 
xBillState
Yes*
Customer's state for their billing profile.
 
xBillZip
Yes*
Customer's ZIP code or postal code for their billing profile.
 
xBillCountry
Yes*
Customer's country for their billing profile.
 
xBillPhone
Yes*
Customer's phone number for their billing profile.
 
xBillMobile
Yes*
Customer's mobile number for their billing profile.
 
xShipFirstName
Yes*
Customer’s first name for their shipping profile.
 
xShipMiddleName
Yes*
Customer’s middle name or initial for their shipping profile.
 
xShipLastName
Yes*
Customer’s last/family name for their shipping profile.
 
xShipCompany
Yes*
Customer’s company name for their shipping profile.
 
xShipPhone
No
Customer’s phone number for their shipping profile.
 
xShipMobile
No
Customer’s mobile number for their shipping profile.
 
Parameter Notes:
*This field can be sent either on the initiate transaction or follow up command transaction
**Required if xShipMethod is anything other than customer pickup
​
ebtonline:void
Process an EBT Online void transaction to cancel out a sale.
Variable
Required
Description
Sample data
xKey
Yes
Your Cardknox API Key.
[xkeycredentials]
xVersion
Yes
Gateway API Version. The current version is 4.5.9
4.5.9
xSoftwareName
Yes
Name of your software.
[xsoftwarecredentials]
xSoftwareVersion
Yes
Version number of your software.
[xversioncredentials]
xBillStreet
Yes*
Customer's street address for their billing profile.
 
xBillStreet2
Yes*
Customer's street address second line for their billing profile.
 
xBillCity
Yes*
Customer's city for their billing profile.
 
xBillState
Yes*
Customer's state for their billing profile.
 
xBillZip
Yes*
Customer's ZIP code or postal code for their billing profile.
 
xBillCountry
Yes*
Customer's country for their billing profile.
 
xBillPhone
Yes*
Customer's phone number for their billing profile.
 
xBillMobile
Yes*
Customer's mobile number for their billing profile.
 
xShipFirstName
Yes*
Customer’s first name for their shipping profile.
 
xShipMiddleName
Yes*
Customer’s middle name or initial for their shipping profile.
 
xShipLastName
Yes*
Customer’s last/family name for their shipping profile.
 
xShipCompany
Yes*
Customer’s company name for their shipping profile.
 
xShipPhone
No
Customer’s phone number for their shipping profile.
 
xShipMobile
No
Customer’s mobile number for their shipping profile.
 
xRefnum
Yes
A unique request ID.
 
Parameter Notes:
*This field can be sent either on the initiate transaction or follow up command transaction
**Required if xShipMethod is anything other than customer pickup
Response Parameters
Variable
Description
Sample data
Variable
Description
Sample data
xResult
Transaction status
A
D
E
xDate
 
 
xStatus
Result verbiage
Approved
Declined
Error
xMaskedCardNumber
 
 
xToken
 
 
xError
Error message, if applicable
 
xRefnum
Cardknox reference number
 
xCardType
Type of card
EBT
xPinPadURL
This field is returned on the initiate command and you would send it when redirecting to the PIN pad
 
xAccuID
This field is returned on the initiate command and you would send it when redirecting to the PIN pad
 
xRemainingBalanceEBTCB
Indicates the remaining EBT cash benefits balance
 
xRemainingBalanceEBTFS
Indicates the remaining EBT cash benefits balance
 
xBatch
Batch into which transaction will settle
 
xAuthAmount
The total amount authorized, inclusive
 
xEbtOnlineErrorMessage
Error message as received from the EBT online provider.
 
xEbtOnlineErrorCode
Error code as received from the EBT online provider.
 
xEbtOnlineResponseCode
Response code as received from the EBT online provider.
 
PIN Pad Implementation
Overview
After the ebtonline:initiate command, the Cardknox gateway will return the necessary pieces to render the PIN pad. The website will take care of redirecting the user to the PIN pad.

To render the PIN pad redirect the consumer to the xPinPadURL (PaySecure) using a POST with the following parameters. Once the consumer has completed entry of their PIN, PaySecure will redirect the consumer back to your site using the URL in the AccuReturnURL field. PaySecure will determine the viewport (desktop or mobile) and render the PIN pad in an adaptive manner, meaning there are distinct layouts based on screen size. PaySecure does not use responsive web design as it interferes with the PIN pad functionality.
Endpoint: xPinPadURL that was returned in the initiate command
Method: POST/URL Redirection
Format: FormData
Request Parameters
Variable
Description
Sample data
AccuId
xAccuID that was returned in the initiate command
 
AccuReturnURL
Fully qualified retailer’s URL; PaySecure will use to redirect the user upon completion of the PIN pad.
URL encoding required
 
AccuLanguage
Language in which the PIN pad will be displayed to the user
en-US (English)
es-MX (Spanish)
[Client Echoed Fields]
You may pass additional form fields that will be passed back to your AccuReturnURL
There are no restrictions on these fields, provided their names are not the same as the reserved PaySecure names. Many retailers utilize these fields to pass session IDs used to identify the user upon return to the AccuReturnURL.
 
​
Response/Redirect Parameters
Variable
Description
Sample data
AccuResponseCode
Response code from PaySecure indicating if the pin process was successful
Accu000 = PIN successfully collected
Accu200 = Cardholder pressed cancel button
Accu400 = Cardholder inactivity timeout
Accu600 = Invalid data received by terminal
Accu710 = Terminal security issue
Accu720 = Terminal communication issue
Accu730 = Terminal internal error
Accu800 = General error encountered
AccuResponseMsg
Response message from PaySecure indicating if the pin process was successful
see AccuResponseCode
AccuId
xAccuID that was submitted
 
[Client Echoed Fields]
Fields that you sent in the Redirect Parameters to the pin pad in [Client Echoed Fields]
 
Workflow/Sample code
Overview
ebtonline:fssale, ebtonline:cbsale, and ebtonline:balance transactions require the user to enter a PIN during the transaction process (for ebtonline:refund and ebtonline:void skip to step 3). As per the EBT requirement (certification), The PIN is not sent with the transaction to the gateway, the Acculynk PIN pad must be used. Acculynk sends the PIN directly to PaySecure and it’s identified by a unique transaction ID.
1) Submit an Initiate Request
The ebtonline:initiate will begin the PIN process. Cardknox will return the necessary pieces to render a PIN pad for the user.
Request
{
  "xKey": "xxxxxxxxxxxxxxxxxxxxxxx",
  "xVersion": "4.5.9",
  "xSoftwareName": "YourSoftwareName",
  "xSoftwareVersion": "1.0.0",
  "xCommand": "ebtonline:initiate",
  "xCardNum": "6004861944321111844",
  "xShipMethod": "CustomerPickup"
}
Response
{
  "xResult": "A",
  "xStatus": "Approved",
  "xError": "",
  "xErrorCode": "00000",
  "xRefNum": "600546727",
  "xAvsResultCode": "",
  "xAvsResult": "Unmapped AVS response",
  "xCvvResultCode": "",
  "xCvvResult": "No CVV data available",
  "xMaskedCardNumber": "6xxxxxxxxxxxxxx1844",
  "xCardType": "EBT",
  "xToken": "hp6h31h29phnh6p48pm6024mp8278q96",
  "xInternalID": "5c3d7ba7-80d4-4437-b4cb-c259cf0757c6",
  "xPinPadURL": "https://test.paysecure.acculynk.net/PINpad",
  "xAccuID": "ce8da934-fe7c-47f4-90bd-46fd0e3ff99e",
  "xMID": "xxxxxxxxxxxTest",
  "xDate": "3/1/2022 12:51:52 PM",
  "xEntryMethod": "Keyed",
  "xRemainingBalanceEBTCB": "0.00",
  "xRemainingBalanceEBTFS": "0.00",
  "xEbtOnlineErrorCode": "00",
  "xEbtOnlineErrorMessage": "SUCCESS"
}
2)  Redirect the user to the PIN pad

Redirect the user to the xPinPadURL for the user to enter their pin.

Request
<form action="https://test.paysecure.acculynk.net/PINpad" method="post">
    <label>AccuId:</label>
    <input type="text" id="AccuId" name="AccuId" value="">
    <label>AccuReturnURL:</label>
    <input type="text" id="AccuReturnURL" name="AccuReturnURL" value="">
    <label>AccuLanguage:</label>
    <input type="text" id="AccuLanguage" name="AccuLanguage" value="en-US">
    <input type="submit" value="Submit">
</form>
Response
AccuLanguage=en-US&
AccuId=ce8da934-fe7c-47f4-90bd-46fd0e3ff99e&
AccuResponseCode=ACCU000&
AccuResponseMsg=SUCCESS
3) Submit the final command to the gateway

Once the user is redirected back to your site with the response code Accu000 submit the final request (ebtonline:fssale, ebtonline:cbsale, or ebtonline:balance) to the Cardknox gateway to complete the transaction. If you receive any other response code, allow the user to try again or cancel the transaction.

Request
{
  "xKey": "xxxxxxxxxxxxxxxxxxxxxxx",
  "xVersion": "4.5.9",
  "xSoftwareName": "YourSoftwareName",
  "xSoftwareVersion": "1.0.0",
  "xCommand": "ebtonline:fssale",
  "xAmount": "1",
  "xRefNum": "123456789"
}
Response
{
  "xResult": "A",
  "xStatus": "Approved",
  "xError": "",
  "xErrorCode": "00000",
  "xRefNum": "600548315",
  "xAuthCode": "452251",
  "xBatch": "6329524",
  "xAvsResultCode": "",
  "xAvsResult": "Unmapped AVS response",
  "xCvvResultCode": "",
  "xCvvResult": "No CVV data available",
  "xAuthAmount": "1.00",
  "xMaskedCardNumber": "6xxxxxxxxxxxxxx1844",
  "xCardType": "EBT",
  "xMID": "xxxxxxxxxxxTest",
  "xDate": "3/1/2022 12:54:39 PM",
  "xEntryMethod": "Unknown",
  "xRemainingBalanceEBTCB": "932.62",
  "xRemainingBalanceEBTFS": "235.25",
  "xEbtOnlineResponseCode": "00",
  "xEbtOnlineErrorCode": "00",
  "xEbtOnlineErrorMessage": "SUCCESS"
}
Test Cards
Test Card
Response Code
Error Message
6004861944321111844
0
(Approved)
 
1
Missing parameter
 
3
Invalid merchant/terminal
6104341675219380
4
Command not supported
6104341397212234
5
Command not authorized
6104342085618120
6
Decline
6004861835913142835
41
Decline
6004861659118294500
43
Decline
6104341476018981
57
Decline
6004861674715978348
59
Decline
6004861469721133669
67
Decline
6104341094217098
12
Invalid transaction
6104341339116774
13
Invalid amount
6104342179210040
14
Invalid card number
6004861283711548772
15
Invalid card
6004861936221520819
23
Unacceptable transaction fee
 
40
Request not supported
6104341157820259
42
Invalid account
6004861118116374806
51
Insufficient funds
​
Frequently Asked Questions
​
Can I view the EBT online commands in Cardknox reporting?
What's the difference between a void and a refund?
Can I use a token instead of a card number for the initiate?
Are partial approvals supported?
Is there a separate command for food stamps and cash benefits?
​