Error documentation for Fully Hosted integrations
With a Forage Fully Hosted integration, an EBT cardholder interacts with a prebuilt Forage UI that’s embedded in your website and app. In the case of an error, the UI responds with a message to the cardholder that details troubleshooting steps.
This reference documents error scenarios and their corresponding Forage UI messages. It also lists the Payments API errors that developers might encounter when building a Fully Hosted integration.
Cardholder-facing error messages
Error scenario | Forage UI message |
---|---|
The cardholder attempted to overpay with SNAP. | The SNAP total that you entered exceeds the SNAP-eligible total of the order. Please update the SNAP amount and try again. |
The cardholder tried to apply EBT Cash to their purchase, but the US State that issued their benefit card does not support online EBT Cash transactions. | Unfortunately, online EBT Cash is not supported for the US state that issued your card. Please remove the EBT Cash contribution and try again. |
Either the cardholder attempted to pay with an EBT Card issued from an entity that does not support online EBT transactions (like Guam, or the Virgin Islands), or they attempted to pay with a different unsupported payment method. | EBT Cards from your state cannot be used online. We apologize for the inconvenience! |
The card number could not be processed. This could be because the number is invalid, the EBT network can’t find an associated account, the card is marked as restricted, or for some other reason. | Invalid card number. Please check and re-enter your card |
The EBT Card is inactive. | This EBT Card may be inactive. Please call the number on the back of the card for assistance. |
For some unknown reason, the EBT Card has been disabled or could not be charged. | This EBT Card could not be charged. Please contact customer service at the phone number on the back of the card for help. |
The cardholder hasn’t yet activated their EBT Card. | This EBT Card hasn't been activated. Please contact customer service at the phone number on the back of the card. |
The EBT Card is restricted. | Oops! This EBT Card is restricted and can't be used. Please call the phone number on the back of the card for help. |
The EBT Card has insufficient funds to complete a purchase. | Insufficient Funds. Remaining balances are SNAP: {snap_balance}, EBT Cash: {ebt_cash_balance}. |
The EBT Card is expired. | This EBT Card is expired. Please contact customer service at the phone number listed on the back of the card for help. |
The cardholder entered an invalid PIN. | The PIN you entered is incorrect. Please try again. |
The cardholder entered an invalid PIN so many times that the EBT network locked their card. The number of allowed incorrect attempts varies by US State. | This EBT Card has been locked after too many PIN attempts. Please contact customer service at the phone number listed on the back of the card for help. |
Something has gone wrong with the EBT processing network. | Online EBT processing is experiencing an outage. Please try again later. |
There’s a key synchronization issue. This is typically a very brief error that can be resolved with a retry. | Oops! Something went wrong. Please try again at a later time. |
The EBT network suspected fraudulent activity and blocked the transaction. | Something went wrong. Please contact EBT customer service at the number on the back of your EBT card. |
The cardholder attempted to cancel an order that can no longer be canceled. | Oops! Something went wrong and we couldn't cancel the order. Please try again. |
For some reason, the order could not be captured. | Oops! Something went wrong and we couldn't process your order. Please try again. |
Forage is unable to connect to the EBT processor for the US state that issued the customer’s card. | Oops! We cannot connect to your state's EBT processor. Try again later. |
The cardholder’s checkout session expired. | We're sorry, but something went wrong. Please try again later. |
There was an issue processing the cardholder’s credit or debit card. | We're sorry, but your credit or debit card could not be processed. If this problem persists, please contact merchant support. |
There was an issue processing the cardholder’s credit card, and they should try the transaction again. | There was a problem processing your credit card. Please try again. |
Developer-facing Payments API Fully Hosted endpoint errors
Refer to the general Errors reference for more about the shape of Forage errors, a list of error
codes
that all endpoints can return, andcodes
returned by the endpoints common to all integration types.
A Payments API error response object includes a code
and message
pair that describes the failure, as in the following example:
{
"path": "/api/orders/{order_ref}/",
"errors": [
{
"code": "cannot_update_order",
"message": "Order <order_ref> has been canceled and therefore cannot be updated. Please create a new order to continue.",
"source": {
"resource": "Orders",
"ref": "{order_ref}"
}
}
]
}
In addition to the errors that all endpoints can return, Fully Hosted-specific endpoints can return a set of specific code
and message
pairs. These are all listed below, in addition to their corresponding troubleshooting steps.
cannot_cancel_order
cannot_cancel_order
Order {order_ref} is in the {order_status} state and therefore cannot be canceled. Only orders in the draft or failed states can be cancelled.
Confirm that order.status
is in a draft
or failed
state, and/or that you passed the correct order_ref
.
cannot_capture_order
cannot_capture_order
Order {order_ref} is in the {order_status} state and therefore cannot be captured. Only orders in the draft or failed states can be submitted for capture.
Confirm that the order.status
is in a draft
or failed
state, and/or that you passed the correct order_ref
.
cannot_update_order
cannot_update_order
Order {order_ref} has been canceled and therefore cannot be updated. Please create a new order to continue.
Confirm that the order.status
is in any state other than canceled
, and/or that you passed the correct order_ref
.
different_ebt_card
different_ebt_card
Order {order_ref} already has EBT Payment {payment_ref} with payment_method {payment_method_ref}. Your request included payment_method {other_payment_method_ref}. You must use the same EBT payment_method for all EBT Payments on an Order
Confirm that you're using the same payment method for all EBT order payments.
duplicate_funding_type
duplicate_funding_type
Order {order_ref} already has payment {payment_ref} with funding_type {funding_type}. Please modify the existing payment object instead of adding new payments with the same funding_type
Confirm that the payment_method
passed in the body of the request is accurate, and/or call the Update an order payment endpoint to modify the existing Order Payment
.
exceeds_ebt_cash_total
exceeds_ebt_cash_total
Order {order_ref} has EBT-Cash payments {payment_ref}s with amounts that exceed the Cash eligible total of {ebt_cash_total}. Please update the Order Payments before capturing the order
Confirm that the combined amount
of all Order Payment
s with funding type ebt_cash
is less than or equal to the Order
's ebt_cash_total
. Call the Update an order payment endpoint if you need to modify an existing Order Payment
.
exceeds_snap_total
exceeds_snap_total
Order {order_ref} has EBT-SNAP payments {payment_ref}s with amounts that exceed the SNAP eligible total of {ebt_cash_total}. Please update the Order Payments before capturing the order
Confirm that the combined amount
for all Order Payment
s with funding type ebt_snap
is less than or equal to the Order
's snap_total
. Call the Update an order payment endpoint if you need to to modify an existing Order Payment
.
generic_cc_failure
generic_cc_failure
A generic failure response on the credit card payment was requested through a special toggle on the Forage frontend.
No action required.
invalid_customer_id
invalid_customer_id
Your credit card processor can't identify a customer with the provided customer ID. Double check the ID and your implementation.
missing_stripe_client_secret
missing_stripe_client_secret
Stripe client secret from Payment Intent creation was never supplied to Forage Payment object or the client secret is malformed
Double check that your Stripe integration is set up correctly. Refer to the Stripe error documentation for details.
order_already_refunded
order_already_refunded
Payments associated with order {order_ref} have already been fully refunded.
Confirm that you passed the correct order_ref
.
order_is_cancelled
order_is_cancelled
Order {order_ref} has been cancelled and therefore cannot have new payments added. Please create a new order to continue.
Create a new Session to create a new Order
.
order_not_succeeded
order_not_succeeded
Order with ref {order_ref} has not completed successfully and therefore cannot be refunded. Current order status is {order_status}
Confirm that order.status
is succeeded
before attempting a refund, and/or confirm that the provided order_ref
is accurate.
refund_exceeds_order_total
refund_exceeds_order_total
Requested refund would push the total amount refunded above the original Payment amount. Total amount paid is {amount}. Existing total of refunds is {refund_amount}
Confirm that the requested refund amount is less than or equal to the original payment amount and try the refund again.
stripe_error
stripe_error
Unable to process payment with Stripe but generic exception was returned
Refer to the Stripe error documentation for more information. Only the PaymentIntent
, PaymentMethod
, Customer
, and Refunds
errors apply to Forage integrations.
unknown_braintree_error
unknown_braintree_error
Unable to process payment with Braintree but generic exception was returned
Refer to the Braintree documentation for more information.
unknown_stripe_error
unknown_stripe_error
Unable to process payment with Stripe but generic exception was returned
Refer to the Stripe error documentation for more information.
wait_for_batch_refund
wait_for_batch_refund
Order with ref {order_ref} has other active refunds and therefore cannot be batch refunded. Existing refunds in processing state are {refund_refs}
Confirm that the status
of all associated Order Refunds
is succeeded
, and/or wait a few minutes and try the Order Refund
again.
wrong_payment_total
wrong_payment_total
Order {order_ref} has payments {payment_ref}s with amounts that do not sum up to the order total of {order_total}. Please update the Payments before capturing the order
Confirm that the sum of the amount
values of Order Payment
s associated with the Order
matches the sum of the Order
's ebt_cash_total
and snap_total
values.