⚠️ Important: Upcoming Breaking API Change Notification
We are reaching out to inform you about upcoming breaking changes to our API that may impact your integration.
When Will This Take Effect?
The changes will be effective starting 5/14/25 7:00PM (PST).
Feature Change: Additional Failure Codes
What’s Changing?
We will add six additional failure_code enumerators that will provide more context as to why a transaction failed. These six new failure codes will be only applied to the FINIX_V1 processor. Customers who want to switch to the improved failure codes will need to integrate into the FINIX_V1 processor.
Please see below for the list of new enumerators for failure_code.
NOTE: Please select the full failure_code in the table below as the column width may truncate the value visually.
|
New failure_code |
Description |
FRAUD_DETECTED_BY_FINIX
|
The card was declined because of suspected fraud by Finix. Please contact Finix for additional information. |
FRAUD_DETECTED_BY_ISSUER
|
The card was declined because of suspected fraud by the issuing bank. Please have the cardholder contact their issuing bank for additional information. |
CARD_NOT_ACTIVATED_OR_BLOCKED
|
The card was declined because it has not been activated or has been temporarily blocked. Please ask the cardholder to activate their card or contact their issuing bank for additional information. |
INVALID_CARD_NUMBER_OR_EXPIRED_CARD
|
The card was declined because the issuing bank indicated that the card number is not valid, closed, or the expiration date is invalid. |
ISSUER_POLICY_VIOLATION
|
The card was declined because the issuing bank has an internal rule that prevents the transaction from being permitted. The rule can prohibit certain MCCs, merchant accounts, issuer country codes or other restrictions. Please have the cardholder contact their issuing bank for additional information. |
ADDRESS_VERIFICATION_AND_CVV_FAILED_RISK_RULES
|
The Risk Profile associated with the Merchant declined the transaction because both AVS and CVV failed. The cardholder needs to create a card with the correct address and CVV. |
What action is needed?
If you are integrated into FINIX_V1 and use the failure_code field, you will need to account for these new failure codes. Customers who want to switch to the improved failure codes will need to integrate into the FINIX_V1 processor.
Why are we changing this?
We’re adding these fields to make it easier to understand why certain payments and authorizations have failed. These new failure codes will reduce the number of GENERIC_DECLINE codes that are currently being returned.
Feature Change: Additional Operation Key Values for Settlement Transfers
What’s Changing?
Finix currently returns null for the operation_key field on Settlement Funding Transfers. Going forward, we will return values to help convey the rail and speed of the funding transfer.
These operation_key enumerators follow this syntax {funding_speed}_{resource}_{direction}_{rail}.
- Funding_speed:
-
- Definition: When funds are made available to be paid out.
-
- Options:
-
-
-
- STANDARD: This funding follows the standard schedule made available by the card networks (ie next business day).
- INSTANT: This funding is available as soon as a transaction is captured, which is prior to when Finix receives funds from the card networks. This incurs an additional fee.
-
-
- Resource:
-
- Definition: Whom the funding transfers are being paid out to.
-
- Options:
-
-
-
- MERCHANT_FUNDING: These are for payouts to merchants.
- APPLICATION_FUNDING: These are for collecting Application Fees.
-
-
- Direction:
-
- Definition: This indicates whether a transaction is pulling or pushing funds.
-
- Options:
-
-
-
- PUSH_TO: This indicates a credit is being made to the merchant’s operating account.
- PULL_FROM: This indicates a debit is being made to the merchant’s operating account.
-
-
- Rail:
-
- Definition: Which payment rail is being used to move the funds.
-
- Options:
-
-
-
- ACH: Standard next day ACH
- SAME_DAY_ACH: Same day ACH
- CARD: Uses Visa Direct or Mastercard Send
-
-
Below is a table that shows all the newly available operator keys and their funding speeds.
NOTE: Please select the full Operator Key in the table below as the column width may truncate the value visually.
|
Operator Key |
Funding Speed |
Transaction Date |
Funding Transfer Created |
Hits Bank |
STANDARD_MERCHANT_FUNDING_PUSH_TO_ACH |
T+2 |
Mon |
Tues over Next Day ACH |
Wed |
STANDARD_MERCHANT_FUNDING_PUSH_TO_SAME_DAY_ACH |
T+1 |
Mon |
Tues over Same Day ACH |
Tues |
STANDARD_MERCHANT_FUNDING_PUSH_TO_CARD |
T+1 |
Mon |
Tues over Visa Direct |
Tues |
INSTANT_MERCHANT_FUNDING_PUSH_TO_CARD |
T+0 |
Mon |
Mon over Visa Direct |
Mon |
INSTANT_MERCHANT_FUNDING_PUSH_TO_ACH |
T+1 |
Mon |
Mon over Next Day ACH |
Tues |
INSTANT_MERCHANT_FUNDING_PUSH_TO_SAME_DAY_ACH |
T+0 |
Mon |
Mon over Same Day ACH |
Mon |
STANDARD_MERCHANT_FUNDING_PULL_FROM_ACH |
T+2 |
Mon |
Tues over Next Day ACH |
Wed |
STANDARD_MERCHANT_FUNDING_PULL_FROM_SAME_DAY_ACH |
T+1 |
Mon |
Tues over Same Day ACH |
Tues |
STANDARD_MERCHANT_FUNDING_PULL_FROM_CARD |
T+1 |
Mon |
Tues over Visa Direct |
Tues |
INSTANT_MERCHANT_FUNDING_PULL_FROM_CARD |
T+0 |
Mon |
Mon over Visa Direct |
Mon |
INSTANT_MERCHANT_FUNDING_PULL_FROM_ACH |
T+1 |
Mon |
Mon over Next Day ACH |
Tues |
INSTANT_MERCHANT_FUNDING_PULL_FROM_SAME_DAY_ACH |
T+0 |
Mon |
Mon over Same Day ACH |
Mon |
STANDARD_APPLICATION_FUNDING_PUSH_TO_ACH |
T+2 |
Mon |
Tues over Next Day ACH |
Wed |
STANDARD_APPLICATION_FUNDING_PUSH_TO_SAME_DAY_ACH |
T+1 |
Mon |
Tues over Same Day ACH |
Tues |
STANDARD_APPLICATION_FUNDING_PUSH_TO_CARD |
T+1 |
Mon |
Tues over Visa Direct |
Tues |
INSTANT_APPLICATION_FUNDING_PUSH_TO_CARD |
T+0 |
Mon |
Mon over Visa Direct |
Mon |
INSTANT_APPLICATION_FUNDING_PUSH_TO_ACH |
T+1 |
Mon |
Mon over Next Day ACH |
Tues |
INSTANT_APPLICATION_FUNDING_PUSH_TO_SAME_DAY_ACH |
T+0 |
Mon |
Mon over Same Day ACH |
Mon |
STANDARD_APPLICATION_FUNDING_PULL_FROM_ACH |
T+2 |
Mon |
Tues over Next Day ACH |
Wed |
STANDARD_APPLICATION_FUNDING_PULL_FROM_SAME_DAY_ACH |
T+1 |
Mon |
Tues over Same Day ACH |
Tues |
STANDARD_APPLICATION_FUNDING_PULL_FROM_CARD |
T+1 |
Mon |
Tues over Visa Direct |
Tues |
INSTANT_APPLICATION_FUNDING_PULL_FROM_CARD |
T+0 |
Mon |
Mon over Visa Direct |
Mon |
INSTANT_APPLICATION_FUNDING_PULL_FROM_ACH |
T+1 |
Mon |
Mon over Next Day ACH |
Tues |
INSTANT_APPLICATION_FUNDING_PULL_FROM_SAME_DAY_ACH |
T+0 |
Mon |
Mon over Same Day ACH |
Mon |
What action is needed?
You should update your system to handle these new operation keys that will be returned in our API and sent in our webhooks.
Why are we changing this?
We are adding enumerators to Settlement Funding transfers to help clarify the type of money movement (i.e. rail and speed).
What You Need to Do
- Review Your Integration: Ensure your application is compatible with the new API behavior.
- Make Necessary Updates: Modify your implementation accordingly before the change takes effect.
- Test in Sandbox: The changes will be available for testing in sandbox starting 5/1/25 7:00PM (PST).
Need Help?
If you have any questions or need assistance, our support team is ready to help. Please reach out to support@finix.com or submit a Support ticket. Please also refer to our documentation here.
We appreciate your attention to this update and your continued partnership.