Handling Declined Payments

Learn why some payments fail and how to handle declines.

Payments can fail for a variety of reasons. Most times, payments fail because:

When a payment, or Transfer, fails:

  • The Transfer gets marked as FAILED.
  • The Transfer gets updated to include an ACH return code in failure_code and steps you need to take to complete the payment in failure_message . For more details, see Errors .
  • If the payment was a debit, the return of the Transfer could indicate a situation where suspicious behavior is involved.

Most times you can get the payment processed by confirming the payment details with your buyer and following the steps in failure_message.

Finix offers several tools to help minimize the risk of declines and ensure payments you process get submitted and completed.

Card Declined by Issuer

When a charge gets submitted to the issuer of your buyer's card, they have automated systems and models in place that determine whether or not to authorize payments.

These systems analyze various signals, such as your customer’s spending habits, account balance, and card information such as the expiration date, address information and CVC.

If your customer’s card issuer declines a payment, Finix shares with you all the information we receive from the issuer in failure_code and failure_message.

One common reason card issuers decline payments is because the information used was incorrect, or a bank account couldn't be located using the information provided.

Use Finix's Account Updater to keep the payment information of your buyers correct and up-to-date. Doing so will reduce the likely hood of having a transaction fail due to incorrect information.

You can also use our Card Verification Checks to confirm a card is valid and will process a transaction.

Additionally, using 3D Secure and Level 2/3 processing to authenticate transactions can decrease decline rates by confirming the cardholder's identity at the time of payment.

Restricted Countries

Finix supports transactions from all countries (e.g., United States, Canada, United Kingdom, Mexico) except for:

  • Afghanistan (AF)
  • Albania (AL)
  • Belarus (BY)
  • Burma/Myanmar (MM)
  • Central African Republic (CF)
  • Cuba (CU)
  • Democratic Republic of the Congo (CD)
  • Ethiopia (ET)
  • Iran (IR)
  • Iraq (IQ)
  • Lebanon (LB)
  • Libya (LY)
  • Mali (ML)
  • Nicaragua (NI)
  • North Korea aka Democratic People's Republic of Korea (KP)
  • Russia (RU)
  • Somalia (SO)
  • South Sudan (SS)
  • Sudan (SD)
  • Syria aka Syrian Arab Republic (SY)
  • Turkey (TR)
  • Ukraine (UA)
  • Venezuela (VE)
  • Yemen (YE)
  • Zimbabwe (ZW)

Transactions from these high-risk countries will not be accepted and will be blocked at an API level. Finix supports transactions from all other countries in either USD or CAD.

Fraud Decline

Use Finix's Fraud Detection API to minimize chargeback losses on your e-commerce sales by detecting and stopping potentially fraudulent transactions performed by bad actors.

See Fraud Detection for more information.

API Calls Declined

As you develop your integration with Finix, good testing should identify any bugs or requests that would lead to invalid API calls.

In turn, with good testing in sandbox, these failures should be rare when you take your integration live. Refer to our API Reference for a guide on how to make requests to Finix's API.