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.

The Sample Code can be found here.

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]
xCommand	Yes	Command specifying which transaction.	ebtonline:initiate
xCardNum	Yes	The customer card number. Alternatively, xToken xMagStripe or SUT can be used.	6004861944321111844
xShipMethod	Yes*	Denotes Shipping Method	DirectDelivery CustomerPickup CommercialShipping Other

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]
xCommand	Yes	Command specifying which transaction.	ebtonline:fssale
xAmount	Yes	The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction.	9.99
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
xShipMethod	Yes*	Denotes Shipping Method	Supported methods: DirectDelivery CustomerPickup CommercialShipping Other

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]
xCommand	Yes	Command specifying which transaction.	cbsale
xAmount	Yes	The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction.	9.99
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.
xShipMethod	Yes*	Shipping method.	Supported methods: DirectDelivery CustomerPickup CommercialShipping Other

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]
xCommand	Yes	Command specifying which transaction.	balance
xRefnum	Yes	A unique request ID.
xShipMethod	Yes*	Denotes Shipping Method	Supported methods: DirectDelivery CustomerPickup CommercialShipping Other

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]
xCommand	Yes	Command specifying which transaction.	refund
xAmount	No	The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction.	9.99
xRefnum	Yes	A unique request ID.

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]
xCommand	Yes	Command specifying which transaction.	void
xRefnum	Yes	A unique request ID.

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.

Response Codes

Responses that can be returned.

Response Code	Response Message
0
1	Missing Parameter
3	Invalid Merchant/Terminal
4	Command Not Supported
5	Command Not Authorized
6	Decline
12	Invalid Transaction
13	Invalid Amount
14	The EBT card you entered is invalid. Please try again.
23	Unacceptable Transaction Fee
40	Request Not Supported
41	The EBT card you used is restricted and cannot be used. Please call the number on the back of your card for assistance or use a different payment method.
42	Invalid Account
43	The EBT card you used is restricted and cannot be used. Please call the number on the back of your card for assistance or use a different payment method.
51	Your SNAP (or Cash) payment failed for insufficient funds.
54	Expired Card
55	The PIN you entered is incorrect. Please re-enter your PIN.
56	The EBT card you entered is invalid. Please try again.
57	Your credit / debit card has been declined. Please try again or add a different payment method.
59	Your credit / debit card has been declined. Please try again or add a different payment method.
60	Card Acceptor Contact Acquirer
61	The refund amount requested exceeds the original sales amount.
62	The EBT card you used is restricted and cannot be used. Please call the number on the back of your card for assistance or use a different payment method.
67	Decline
75	Your card was locked after too many incorrect PIN attempts. Please call the number on the back of your card for assistance.
76	Key Synchronization Error
89	CVV Failed
90	No Account On File
92	There has been an error while processing your PIN. Please try again.
96	There has been an error while processing your PIN. Please try again.
9	There has been an error while processing your PIN. Please try again.

Error Codes

Errors that can be returned.

Error Code	Error Message
501	Invalid IP Address
502	Invalid User Credentials
503	Request Validation Failed
504	Invalid Hash Value
602	Invalid User
603	Original Transaction Not Found
604	Payment provider could not read card. Please try again
605	Track Data Error
607	RSA Token Key Error
608	Tokenazation Error
609	Transaction Type can not be reversed
610	Invalid Currency
611	Invalid BIN
612	BIN Error
616	Merchant Descriptor Error
618	Our payment solution provider is not responding. Please try again.
621	Duplicate Reference Key
622	Transaction Type Not Supported
702	Error With Transaction Number
703	SAF Error
704	EFT Connection Error
712	Declined transaction
713	Our payment solution provider is not responding. Please try again.

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: URL Redirection

This endpoint can only be called from the browser.

Format: FormData

Redirect 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
6104342148913849	54	Expired card
6104341215511833	55	Incorrect PIN
6004861487521029713	56	Invalid card
6004861804921225354	60	Card acceptor contact acquirer
6104341821716867	61	Exceeds withdrawal limit
6104341606718450	62	Restricted card
6104341108310343	75	PIN tries exceeded
6004861908615095260	76	Key synchronization error
6004861170115289659	89	CVV failed
	90	No account on file
6004861035618530794	92	System error
6004861904512646719	96	System error
6004861141211040767	99	System error

---

Frequently Asked Questions

Can I view the EBT online commands in Cardknox reporting?

The initiate and balance commands are available for internal users in the report:log and sale commands are available in all reports.

What's the difference between a void and a refund?

The void command voids the entire transaction, so no amount is allowed; a refund can partially refund the transaction, so an amount is allowed.

Can I use a token instead of a card number for the initiate?

Yes

Are partial approvals supported?

No

Is there a separate command for food stamps and cash benefits?

For balance, refund, and void, there is no need to specify. For sales, there is a separate command for food stamps (ebtonline:fssale) and cash benefits (ebtonline:cbsale).