HomeGuidesReference
Log In

SDK

Errors documentation for SDK integration-related endpoints

A Payments API error response object includes a code and message pair that describes the failure, as in the following example:

{
  "path": "/api/payments/{payment_ref}/refunds/",
  "errors": [
    {
      "code": "cannot_refund_after_90_days",
      "message": "Per federal regulations, refunds to EBT payment methods cannot be processed after 90 days. Payment <payment_ref> succeeded on <payment_success_date>",
      "source": {
        "resource": "Payments",
        "ref": "{payment_ref}"
      }
    }
  ]
}

In addition to the errors that all endpoints can return, SDK integration-related endpoints can return a set of specific code and message pairs. These are all listed below, in addition to their corresponding troubleshooting steps.

📘

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.

Payments API SDK endpoint errors

amount_mismatch

Payment amount needs to equal to products amount. Payment amount: {payment_amount}, products amount: {products_amount}.

Prompt the cardholder to update the {payment_amount} to match the {products_amount}.

✅

Any failed Payment can be retried.

If a transaction fails, then attempt to process the original Payment object again before creating a new one, updating it first if you need to.

You only need to create a new Payment if the old one is canceled.

cannot_capture_payment

One of several possible messages might accompany this code.

Payment with ref {payment_ref} is either processing, succeeded, or canceled and therefore cannot be captured.

or

Amount value is null. Payment with ref {payment.ref} with funding_type {payment.funding_type} cannot be captured with a null amount value

or

'is_delivery' value is null. Payment with ref {payment.ref} requires a valid 'is_delivery' value for capture.

Depending on the message, confirm that the payment.status, payment.funding_type, or payment.is_delivery value is correct before capturing the payment, and/or double check that there isn't a typo in the provided payment_ref. If all else fails, create a new Payment for the cardholder and prompt them to retry.

cannot_refund_after_90_days

Per federal regulations, refunds to EBT payment methods cannot be processed after 90 days. Payment {payment_ref} succeeded on {payment_success_date}

If this error occurs in development, then confirm that the payment_ref in the request is accurate. If this error occurs during production, then alert the customer or merchant clerk in the front-end user interface that the refund date has passed.

cannot_refund_payment

One of several messages might accompany this code.

Only Payments in the succeeded state can be refunded, but Payment with ref {payment_ref} is in the state {payment_state}

or

Only Payments with a non-null amount can be refunded, but Payment with ref {} has no amount provided.

or

Refund for payment ref {} misses a pin. Please use the SDK to collect pin first.

If this error occurs in development, then confirm that the payment_ref in the request is accurate. If this error occurs during production, then alert the customer or merchant clerk in the front-end user interface that the refund date has passed.

cannot_void

Payment with ref {payment_ref} cannot be voided because it is in the {payment_state} state. Only payments in the succeeded state can be voided

Confirm that the payment_ref and/or refund_ref in the request is accurate and that its status value is succeeded.

card_not_reusable

Payment method {payment_method_ref} is not reusable

Prompt the cardholder to try the transaction again with a reusable payment method.

different_ebt_card

SNAP payment method ref {payment_method_ref} is different from EBT Cash payment method ref {payment_method_ref}. You must use the same EBT payment_method for all EBT Payments on an Order

Prompt the cardholder to reenter their EBT Card details.

ebt_cash_not_supported

Ebt cash payment cannot be captured in {US State}

Prompt the cardholder to update their payment method and try again.

ebt_error_* codes

✅

In the case of an ebt_error_* code , the response always includes the original resource, in addition to the errors field.

For example, an ebt_error_43 returned in the case of a lost or stolen card takes the following shape: 

{
    "ref": "55ca7f3c35",
    "merchant": "9000034",
    "funding_type": "ebt_snap",
    "amount": "1.00",
    "description": "Testing app payments (SNAP Purchase)",
    "metadata": {},
    "payment_method": "6sc7bcd229",
    "delivery_address": null,
    "is_delivery": false,
    "created": "2024-05-07T11:04:58.967491-07:00",
    "updated": "2024-05-07T11:05:15.432620-07:00",
    "status": "failed",
    "last_processing_error": null,
    "success_date": null,
    "receipt": {
        "ref_number": "55ca7f3c35",
        "is_voided": false,
        "snap_amount": "1.00",
        "ebt_cash_amount": "0.00",
        "cash_back_amount": "0.00",
        "other_amount": "0.00",
        "sales_tax_applied": "0.00",
        "balance": null,
        "last_4": "4443",
        "message": "Lost/stolen card - Cannot Process - Call Customer Service",
        "transaction_type": "Payment",
        "created": "2024-05-07T11:05:15.427552-07:00",
        "sequence_number": "PA022ba7"
    },
    "expires_at": "2024-05-07T18:35:15.432620Z",
    "pos_terminal": {
        "terminal_id": "0783f5a4",
        "provider_terminal_id": "Android Emulator"
    },
    "sequence_number": "PA022ba7",
    "external_location_id": null,
    "merchant_destination_account": null,
    "errors": [
        {
            "code": "ebt_error_43",
            "message": "Lost/stolen card - Cannot Process - Call Customer Service",
            "source": {
                "resource": "Payments",
                "ref": "55ca7f3c35"
            }
        }
    ],
    "previous_errors": [
        {
            "code": "ebt_error_43",
            "message": "Lost/stolen card - Cannot Process - Call Customer Service",
            "source": {
                "resource": "Payments",
                "ref": "55ca7f3c35"
            }
        }
    ],
    "refunds": []
}

The Payment details precede the errors details.

ebt_error_02

Bad FNS status for merchant - Cannot Process - Call Customer Service

There’s an issue between the merchant and FNS. Double check that the FNS number in the Merchant-Account header is accurate. If there’s no typo, then reach out to FNS or to your Forage account manager for help.

ebt_error_03

Invalid merchant - Cannot Process - Call Customer Service

The merchant’s FNS number is not valid. Double check that the FNS number in the Merchant-Account header is accurate. If there’s no typo, then reach out to FNS or your Forage account manager for help.

ebt_error_05

General denial - Cannot Process - Call Customer Service

The EBT network can’t complete the transaction.

ebt_error_06

Invalid transaction - Invalid Transaction

The EBT network can’t complete the transaction.

ebt_error_10

Partial approval - Approved

in-store only

The EBT network went down during an in-store transaction, but the brick-and-mortar merchant treated the transaction as a success, following the “store and forward” protocol. The EBT network came back online and the merchant attempted to process the transaction, but the EBT Card has insufficient funds. The merchant collects the entire available balance, and the network returns an ebt_error_10. Per FNS regulations, in this rare case the merchant absorbs any outstanding balance as a loss.

ebt_error_12

Invalid transaction type - Transaction Not Defined

The EBT network can’t complete the transaction.

ebt_error_13

Invalid amount field - Re-enter Transaction

The EBT network can’t process the entered transaction amount.

ebt_error_14

Invalid card number - Re-enter Transaction

There’s an issue with the EBT Card number.

ebt_error_19

Re-enter transaction - Re-enter Transaction

The EBT network can’t complete the transaction, possibly due to a typo.

ebt_error_23

Unacceptable transaction fee - Cannot Process - Call Customer Service

The EBT network can’t complete the transaction, possibly because of merchant errors.

ebt_error_30

Format error - Cannot Process - Call Customer Service

The EBT network can’t complete the transaction, likely because of a typo.

ebt_error_31

Card has invalid ISO prefix - Cannot Process - Call Customer Service

Forage and the EBT network are having trouble communicating. This error is extremely rare.

ebt_error_40

Function not available - Function Unavailable

The EBT network can’t complete the transaction.

ebt_error_41

Lost Card - Cannot Process - Call Customer Service

The EBT network associates the card number with a lost card.

ebt_error_42

No account - Cannot Process - Call Customer Service

There’s an issue with the EBT Card number.

ebt_error_43

Lost/stolen card - Cannot Process - Call Customer Service

The EBT network reports that the EBT Card number belongs to a lost or stolen card.

ebt_error_51

Insufficient funds - Insufficient Funds. Remaining balances are SNAP: {number}, EBT Cash: {number}

The EBT and/or SNAP charges exceed the customer’s available EBT Card balance. Update the transaction amounts to match the available balance. For more details, check out the Forage insufficient funds guide.

The complete error object takes the following shape:

{
    "ref": "414d656d28",
    "merchant": "9000034",
    "funding_type": "ebt_snap",
    "amount": "1.00",
    "description": "Testing POS certification app payments (SNAP Purchase)",
    "metadata": {},
    "payment_method": "5d96ef34ac",
    "delivery_address": null,
    "is_delivery": false,
    "created": "2024-05-07T09:02:39.151663-07:00",
    "updated": "2024-05-07T09:03:02.312241-07:00",
    "status": "failed",
    "last_processing_error": null,
    "success_date": null,
    "receipt": {
        "ref_number": "414d656d28",
        "is_voided": false,
        "snap_amount": "1.00",
        "ebt_cash_amount": "0.00",
        "cash_back_amount": "0.00",
        "other_amount": "0.00",
        "sales_tax_applied": "0.00",
        "balance": {
            "id": 231529,
            "snap": "1000.00",
            "non_snap": "1000.00",
            "updated": "2024-05-07T09:03:02.281341-07:00"
        },
        "last_4": "4451",
        "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $1000.00, EBT Cash: $1000.00",
        "transaction_type": "Payment",
        "created": "2024-05-07T09:03:02.303324-07:00",
        "sequence_number": "PA022b56"
    },
    "expires_at": "2024-05-07T16:33:02.312241Z",
    "pos_terminal": {
        "terminal_id": "0783f5a4",
        "provider_terminal_id": "Android Emulator"
    },
    "sequence_number": "PA022b56",
    "external_location_id": null,
    "merchant_destination_account": null,
    "errors": [
        {
            "code": "ebt_error_51",
            "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $1000.00, EBT Cash: $1000.00",
            "source": {
                "resource": "Payments",
                "ref": "414d656d28"
            },
            "details": {
                "cash_balance": "1000.00",
                "snap_balance": "1000.00"
            }
        }
    ],
    "previous_errors": [
        {
            "code": "ebt_error_51",
            "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $1000.00, EBT Cash: $1000.00",
            "source": {
                "resource": "Payments",
                "ref": "414d656d28"
            },
            "details": {
                "cash_balance": "1000.00",
                "snap_balance": "1000.00"
            }
        }
    ],
    "refunds": []
}

ebt_error_52

No account on file - Cannot Process - Call Customer Service

There’s an issue with the EBT Card number.

ebt_error_54

Expired card - Expired Card

The EBT network associates the customer’s EBT Card number with an expired card.

ebt_error_55

Invalid PIN or PIN not selected - Invalid PIN

The EBT PIN that the customer entered is incorrect.

ebt_error_56

Card number not found - Cannot Process - Call Customer Service

The EBT network doesn’t recognize the customer’s EBT Card number.

ebt_error_57

Transaction not permitted to cardholder - Transaction Not Defined

The EBT network can’t complete the transaction.

ebt_error_58

Invalid transaction - Invalid Transaction

The EBT network can’t complete the transaction.

ebt_error_59

Fraud (return card) - Cannot Process - Call Customer Service

The EBT network associates the customer’s EBT Card number with unusual activity.

ebt_error_61

Return exceeds benefit authorization - Invalid Transaction

The requested return amount exceeds the issuer’s limit for the customer.

ebt_error_62

Restricted card - Cannot Process - Call Customer Service

The EBT network reports an issue with the EBT Card.

ebt_error_75

PIN tries exceeded - PIN Tries Exceeded

The customer entered an incorrect PIN four times, so the EBT network canceled the transaction and locked the account for 24 hours.

ebt_error_76

Key synchronization error - Cannot Process - Call Customer Service

Forage and FNS are having trouble communicating.

ebt_error_80

Voucher expired - Cannot Process - Call Customer Service

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports that the voucher is expired.

ebt_error_90

Processor not logged on - Host Not Available

The EBT network is currently offline.

ebt_error_91

Authorizer not available (time-out) - Host Not Available

The EBT network is currently offline.

ebt_error_92

Transaction destination cannot be found for routing - Cannot Process

There’s been an issue processing an out-of-state EBT Card number.

ebt_error_96

System malfunction - Cannot Process - Call Customer Service

The EBT network can’t complete the transaction.

ebt_error_A1

Invalid Voucher ID - Invalid Transaction

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports that the voucher ID is incorrect.

ebt_error_A2

Invalid authorization number (approval code does not match voice approval code) - Invalid Transaction

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports an issue with the voucher authorization number.

ebt_error_A3

Amount greater than original voice authorization - Invalid Transaction

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports an issue with the authorized transaction amount.

ebt_error_A4

Original voice authorization not found for cardholder - Invalid Transaction

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports an issue authenticating the cardholder identity.

ebt_error_A5

FNS number does not match original voice authorization - Invalid Transaction

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports an issue authenticating the merchant FNS number.

ebt_error_A6

Item already cleared - Invalid Transaction

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network fails to process a voucher.

ebt_error_FF

Invalid HIP Amount - Re-enter Transaction

The Healthy Incentives Program (HIP) benefits amount that the customer entered is not authorized.

ebt_error_S5

PIN not selected - PIN Not Selected

A PIN number has not been assigned to this EBT Card.

ebt_error_S6

PIN already selected - PIN Already Selected

There’s an issue processing this EBT Card number.

ebt_error_S7

Unmatched voucher information - Unmatched Voucher Information

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports something wrong with the voucher input.

user_error

A user submitted incorrect or incomplete information.

ebt_processor_timeout

Unable to contact EBT processor, please try again shortly.

Prompt the cardholder to try the transaction again in a few minutes.

fixed_settlement_not_applicable

The merchant_fixed_settlement and platform_fixed_settlement fields are only applicable to EBT Cash Payments.

Remove the merchant_fixed_settlement and platform_fixed_settlement fields from the request, or update the funding_type of the Payment.

inconsistent_funding_and_payment_method

Payment was posted with a funding_type of {funding_type}, but the payment_method is {other_funding_type} card.

Update the funding_type of the Payment, or use a different payment_method.

Payment with ref {payment_ref} has already been submitted for capture and therefore cannot be canceled. To reverse this payment, please use a normal refund.

Confirm that the payment_ref passed in the request is correct, or call the Create a Payment Refund endpoint to refund the payment.

payment_already_captured

Payment with ref {payment_ref} has already been submitted for capture and therefore cannot be canceled. To reverse this payment, please use a normal refund.

Confirm that the payment_ref passed in the request is correct, or call the Create a Payment Refund endpoint to refund the payment.

pin_caching_error

Unable to cache encrypted PIN value

Use the corresponding SDK method to collect a cardholder’s PIN, and then try the transaction again.

pin_retrieval_error

One of several possible messages might accompany this code.

Unable to retrieve encrypted PIN value

or

Unable to find encrypted PIN for key value

or

Refund for payment ref {payment_ref} requires a pin which is missing

Use the corresponding SDK method to collect a cardholder’s PIN, and then try the transaction again.

processor_timeout

External processor timed out

Forage was unable to receive a response from the EBT network. Retry the request. If you keep receiving the error, then increase the amount of time that you wait between retries exponentially.

refund_exceeds_order_total

One of several possible messages might accompany this code.

Requested refund would push the total amount refunded above the original Payment amount. Total amount paid is {amount_paid}. Existing total of refunds is {refund_amount}

or

Requested refund would push the total amount settled to the Merchant above the original Payment amount. Total fixed amount allocated to the Merchant is {}. Existing total of refunds is {}

or

Requested refund would push the total amount settled to the Platform above the original Payment amount. Total fixed amount allocated to the Platform is {}. Existing total of refunds is {}

or

Must allocate funds to merchant_fixed_settlement and platform_fixed_settlement correctly. Merchant funds to be allocated: {merchant_fixed_amount_still_available_for_refund}, Platform funds to be allocated: {platform_fixed_amount_still_available_for_refund}

or

Refund must be greater than zero!

Confirm that the requested refund amount is less than or equal to the original payment amount (or is not equal to zero) and try the refund again.

settlement_greater_than_amount

{merchant_fixed_settlement} + {platform_fixed_settlement} must be equal to or less than the amount charged. Fixed settlement charged of {amount} is greater than amount of {amount}

Update the fixed settlement charges to be less than or equal to the amount charged.