Declines and Retries

A payment can be stopped at three points: the fraud decision, 3DS authentication, or authorization at the processor. This page explains how each outcome is reported, and how Forter and your integration can recover from it.

Declines Are Not Errors

A processor decline is a valid payment outcome, not an API error. When the issuer declines, POST /api/payments and confirm still return a success HTTP status, with the payment in status failed and the decline details under authorization:

{
  "id": "pi_v1r1a3f9c2e4b5d6478a9b0c1d2e3f4a5b6c",
  "status": "failed",
  "processor": {
    "name": "braintree",
    "transactionId": "k3m9x2p1"
  },
  "authorization": {
    "processorResponseCode": "insufficient_funds",
    "rawResponseCode": "2001",
    "rawResponseMessage": "Insufficient Funds"
  }
}

Always check status on the response body. Don't rely on the HTTP status alone. HTTP errors are reserved for requests that could not be processed. See Errors.

Authorization Details

Field	Description
authorization.processorResponseCode	A normalized response code that means the same thing for every processor. Omitted when the processor's code has no normalized equivalent.
authorization.rawResponseCode, authorization.rawResponseMessage	The processor's original code and message, unchanged. Use them for logging and support investigations.
authorization.authorizationCode	The issuer's approval code, for approved authorizations.
authorization.checks	Address (addressCheck) and CVC (cvcCheck) verification results: pass, fail, unavailable or unchecked.
processor.name, processor.transactionId	The processor that handled the final attempt, and its transaction ID.

Normalized Response Codes

processorResponseCode	Meaning
approved	The authorization was approved.
do_not_honor, generic_decline	The issuer declined without giving a specific reason.
insufficient_funds	The account doesn't have enough funds.
limit_exceeded	The amount or frequency exceeds the card's limits.
expired_card	The card has expired.
invalid_card_number, invalid_account	The card number or account is not valid.
cvv_mismatch, avs_mismatch	The CVC or billing address didn't match the issuer's records.
call_issuer	The issuer asks the cardholder to contact them.
lost_or_stolen_card, pickup_card, fraudulent	The issuer flagged the card or transaction. Don't retry with the same card.
transaction_not_allowed, card_type_not_supported	The card can't be used for this kind of transaction, or with this processor.
duplicate_transaction	The processor considers this a duplicate of a recent transaction.
invalid_amount	The amount isn't valid for this card or processor.
processor_unavailable	The processor couldn't be reached or returned an error.
invalid_request, configuration_error	The payment was rejected before reaching the issuer, for example because of a processor account setup issue. Contact your Forter representative if these persist.

New response codes may be added over time. Treat unknown values like generic_decline.

Automatic Rerouting

When an authorization is declined or fails, Forter can retry it automatically with a different processor in the same request, using a new Predictive Payment Routing recommendation. Rerouting is transparent:

The response reflects the final attempt. processor.name tells you which processor handled it.

You aren't charged twice. A payment holds at most one successful authorization.

No integration work is required.

If the payment is still failed after rerouting, you can ask the customer for another payment method and create a new payment. You can also retry the same payment by calling POST /api/payments/{id}/confirm with a new Idempotency-Key, which starts a new authorization attempt. Avoid retrying codes that indicate the card itself is unusable, such as lost_or_stolen_card, pickup_card, fraudulent, expired_card and invalid_card_number.

Fraud Decisions

The payment's fraud object reports Forter's decisions:

{
  "fraud": {
    "preAuth": { "decision": "approve" },
    "postAuth": { "decision": "approve" }
  }
}

decision is approve, decline or not_reviewed.

preAuth is the decision taken before authorization. A decline stops the payment before it reaches a processor. On POST /api/payments, this is not an error: the payment is returned with a success HTTP status and status canceled. A decline when you call confirm after 3DS is returned as an HTTP 400 error instead (see 3DS Outcomes).

postAuth is present when post-authorization decisioning is enabled for your site.

3DS Outcomes

When 3DS is required, the payment is returned with status requires_action, and you call confirm after the customer completes authentication (see Payment Lifecycle). If the payment can't proceed, confirm returns an HTTP 400 error:

errorCode	Meaning
3DS_FAILED	The customer failed or abandoned 3DS authentication. The payment is canceled.
3DS_REQUIRED	The payment can only be approved with a successful 3DS authentication, and none was completed. The payment is canceled.
FRAUD_DECLINE	Forter declined the payment.

The authentication result is reported on the payment as authentication.threeDSecure, with status (authenticated, attempted, failed, rejected, challenge_required or unavailable), version and eci.