# 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](https://www.fns.usda.gov/snap/retailer-requirements-provide-online-purchasing). 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. Sola'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](#workflow-sample-code). {% hint style="info" %} In order to use EBT Online, it must be activated on your account. To request activation, please contact support. {% endhint %} ## Endpoints The base URL to send transactions to is `https://x1.cardknox.com` Additionally, the backup URL is `https://b1.cardknox.com` \ Sola 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 | | | JSON | /gatewayjson | | | XML | /gatewayxml | | As noted above, you can use “`https://b1.cardknox.com`" as an alternative backup URL. ## Request Method Method: **POST**\ Sola/Cardknox Gateway requires an HTTP POST method to be used for enhanced security.\ We do not support the GET method. ## Request / Commands to the Sola/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 Sola 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
| {% hint style="info" %} **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 {% endhint %} *** ### **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 Sola 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
| {% hint style="info" %} **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 {% endhint %} ### **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 Sola 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
| {% hint style="info" %} **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 {% endhint %} ### **ebtonline:balance** Check the available balance on an EBT card | **Variable** | **Required** | **Description** | **Sample data** | | ---------------- | ------------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | xKey | Yes | Your Sola 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
| {% hint style="info" %} **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 {% endhint %} ### **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 Sola 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 Sola 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 | Sola 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 Sola 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 {% hint style="info" %} This endpoint can only be called from the browser. {% endhint %} **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. Sola will return the necessary pieces to render a PIN pad for the user. **Request** {% code lineNumbers="true" %} ```json { "xKey": "xxxxxxxxxxxxxxxxxxxxxxx", "xVersion": "4.5.9", "xSoftwareName": "YourSoftwareName", "xSoftwareVersion": "1.0.0", "xCommand": "ebtonline:initiate", "xCardNum": "6004861944321111844", "xShipMethod": "CustomerPickup" } ``` {% endcode %} **Response** {% code lineNumbers="true" %} ```json { "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" } ``` {% endcode %} #### **2) Redirect the user to the PIN pad** Redirect the user to the `xPinPadURL` for the user to enter their pin.
**Request** {% code lineNumbers="true" %} ```html
``` {% endcode %} **Response** {% code lineNumbers="true" %} ``` AccuLanguage=en-US& AccuId=ce8da934-fe7c-47f4-90bd-46fd0e3ff99e& AccuResponseCode=ACCU000& AccuResponseMsg=SUCCESS ``` {% endcode %} #### **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 Sola gateway to complete the transaction. If you receive any other response code, allow the user to try again or cancel the transaction.\ \ **Request** {% code lineNumbers="true" %} ```json { "xKey": "xxxxxxxxxxxxxxxxxxxxxxx", "xVersion": "4.5.9", "xSoftwareName": "YourSoftwareName", "xSoftwareVersion": "1.0.0", "xCommand": "ebtonline:fssale", "xAmount": "1", "xRefNum": "123456789" } ``` {% endcode %} **Response** {% code lineNumbers="true" %} ```json { "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" } ``` {% endcode %} ## 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 Sola 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`).
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.solapayments.com/products/ebt-online.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.