Document error messages

Learn how to prepare documentation for FNS about customer-facing EBT error messages.

As part of the process to receive FNS approval to accept EBT online, merchants must submit documentation, in the form of a table, about how they communicate errors to customers.

Use the template error table as a starting point to draft the required documentation. The table lists common error scenarios, along with their corresponding descriptions and customer-facing error messages.

Most, but not all, errors and their corresponding customer-facing messages are submitted to FNS. For more obscure errors and developer details like the HTTP status codes, refer to the API Reference docs.

FNS doesn’t need to review all possible error messages or HTTP status codes. The template below includes only what is required.

How to use the template error table

Tailor the template to your Forage integration type before submitting it to FNS:

Fully Hosted

If you’re building a Fully Hosted integration, then you can submit the template table as is. The customer-facing messages match the Forage Checkout interface.

Custom

If you’re building a Custom integration, then the template table is either everything that you need to submit or a starting point. The customer-facing messages match the Forage Checkout interface, but if you want to support more error scenarios, then you need to add rows. Refer to the developer documentation for EBT-related error codes to explore more possible errors.

Whatever you submit to FNS must match what your app displays to the customer.

SDKs

If you’re integrating a Forage SDK, then you’re building your own checkout interface. You’re welcome to use the same customer-facing error messages that Forage Checkout does, documented in the table below, or you can write your own. If you want to support more possible errors, then you need to add rows. Refer to the developer documentation for EBT-related error codes to explore more possible errors.

Whatever you submit to FNS must match what your app displays to the customer.

Template error table for FNS documentation

🚧

The customer-facing messages match Forage Checkout exactly.

If you’re integrating a Forage SDK and building your own interface, then the customer-facing message is up to you. You’re welcome to use the messages below or to change them. Just be sure that whatever you submit in the table is the same as what appears to your customers.

Error scenarioResponse codeTPP error descriptionCustomer-facing error message
Invalid PINebt_error_55Invalid PIN or PIN not selectedThe PIN you have entered is incorrect. Please try again.
PIN Attempts Exceededebt_error_75PIN tries exceededYour card was locked after too many incorrect PIN attempts. Please call the number on the back of your card for assistance.
Insufficient Fundsebt_error_51Insufficient FundsYour SNAP (or Cash) payment failed for insufficient funds. Your available balance is $___.
Invalid Card/Accountebt_error_14
ebt_error_56
Invalid card number

Card number not found
Invalid card number. Please check the card number and try again or call the number on the back of your EBT card for assistance.
EBT Lost/Stolen cardebt_error_41
ebt_error_43
ebt_error_62
Lost Card

Lost/stolen Card
Restricted card, cannot be used. Please call the number on the back of your EBT card for assistance.
Other Processor Hard Denial/General Denialebt_error_05
ebt_error_76
ebt_error_90
ebt_error_91
ebt_error_92
ebt_error_96
General denial

Processor not logged on

Authorizer not available (time-out)

Transaction destination cannot be found for routing

System malfunction

Key synchronization error
Oops! Something went wrong. Please try again. If this problem persists, please contact merchant support.
TPP Errorebt_error_76
ebt_error_90
ebt_error_91
ebt_error_92
ebt_error_96
Processor not logged on

Authorizer not available (time-out)

Transaction destination cannot be found for routing

System malfunction

Key synchronization error
Oops! Something went wrong. Please try again. If this problem persists, please contact merchant support.
Credit/Debit-only denialN/AN/A - Forage not handling credit-only paymentsThere was a problem processing your payment. Please try another payment method or contact your payment provider for more information.
Credit/Debit denial after EBT approvedC1
C2
Internal error, system malfunction or server timeoutThere was a problem processing your payment. Please try another payment method or contact your payment provider for more information.
TPP does not respondT1Internal error, system malfunction or server timeoutOops! Something went wrong. Please try again. If this problem persists, please contact member services.
Credit/Debit issuer does not respondC1
C2
Internal error, system malfunction or server timeoutOops! Something went wrong. Please try again. If this problem persists, please contact member services.
Credit/Debit issuer does not respond after EBT payments madeC1
C2
Internal error, system malfunction or server timeoutThere was a problem processing your payment.Please try again. If this problem persists, please contact member services.
Credit/Debit issuer does not respond to final authorization when fulfilling orderN/AMerchant Admin system errorThere was a problem processing your payment.Please try again. If this problem persists, please contact member services.
Refund Errors
Refund Exceeds 90 day limit for EBTN/AMerchant Admin system errorN/A - during refund processing there is no customer facing error message. Merchant admin will prevent refunds from being initiated for transactions more than 90 days old.
Refund Amount Exceeds Original PurchaseN/AMerchant Admin system errorN/A - during refund processing there is no customer facing error message. A refund for more than the original purchase will not be permitted by the merchant’s admin system.
Refund Exceeds Benefit Authorization (EBT Cash)ebt_error_61Merchant Admin system errorN/A - during refund processing there is no customer facing error message. Merchant Admin error, “Please contact merchant support to complete the refund with an alternate payment method.”
TPP does not respond to refund request while changing orderebt_error_76
ebt_error_90
ebt_error_91
ebt_error_92
ebt_error_96
Processor not logged on

Authorizer not available (time-out)

Transaction destination cannot be found for routing

System malfunction

Key synchronization error
Oops! Something went wrong. Please try again. If this problem persists, please contact merchant support.
TPP does not respond to refund request while fulfilling orderN/AMerchant Admin system errorN/A - at fulfillment there is no customer facing error message. This will be handled on the merchant/TPP side by repeated attempts to complete the refund or by registering an EBT adjustment request with the Processor. Customer will be notified by phone or email.
TPP does not respond to refund request post-deliveryN/AMerchant Admin system errorN/A - at this stage of the order there is no customer facing error message. This will be handled on the merchant/TPP side by repeated attempts to complete the refund or registering an EBT adjustment request with the Processor. Customer will be notified by phone or email.
Internal Errors or Time-out Errors
Before Order Processing/PIN Entry Beginsebt_error_76
ebt_error_90
ebt_error_91
ebt_error_92
ebt_error_96
T1
Processor not logged on

Authorizer not available (time-out)

Transaction destination cannot be found for routing

System malfunction

Key synchronization error
Oops! Something went wrong. Please try again. If this problem persists, please contact merchant support.
Between PIN entry and EBT Processor responseebt_error_76
ebt_error_90
ebt_error_91
ebt_error_92
ebt_error_96
T1
Processor not logged on

Authorizer not available (time-out)

Transaction destination cannot be found for routing

System malfunction

Key synchronization error
Oops! Something went wrong. Please try again. If this problem persists, please contact merchant support.
Between SNAP approval and Cash responseebt_error_76
ebt_error_90
ebt_error_91
ebt_error_92
ebt_error_96
T1
Processor not logged on

Authorizer not available (time-out)

Transaction destination cannot be found for routing

System malfunction

Key synchronization error
Oops! Something went wrong. Please try again. If this problem persists, please contact merchant support.
Between EBT approval(s) and credit/debit pre-authC1
C2
Internal error, system malfunction or server timeoutThere was a problem processing your payment. Your EBT payment was refunded. Please try another payment method or contact your payment provider for more information.
During order fulfillmentN/AMerchant Admin system errorn/a