Fully Hosted

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

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, and codes 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

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

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

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

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

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

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 Payments 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

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 Payments 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

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

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

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

Payments associated with order {order_ref} have already been fully refunded.

Confirm that you passed the correct order_ref.

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 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

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

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

Unable to process payment with Braintree but generic exception was returned

Refer to the Braintree documentation for more information.

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

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

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.