Handling Payout Failures

Learn how to view and handle Payout Failures

Payouts may fail for a number of reasons. Payout failures fall into three major categories:

Velocity Rule Failures: Failures for exceeding Velocity Rules
Balance Amount Failures: Failures for attempting to exceed the available balance in your account.
Third-Party Network Failures: Failures from the card networks (e.g. Visa, Mastercard) or ACH network.

Velocity Rule Failures

Velocity Rule failures can be the most common reasons why a payout fails. If you require a higher velocity limit, please email your Finix Point of Contact. We may follow up with additional documentation requests.

API response for Velocity Rules

Copy

Copied

{
    "id": "TRfb1QBrJVWY3UYpsX4qscDr",
    "created_at": "2024-07-23T18:21:58.51Z",
    "updated_at": "2024-07-23T18:21:58.51Z",
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "additional_purchase_data": null,
    "address_verification": null,
    "amount": 987650,
    "amount_requested": 987650,
    "application": "AP9oVc9EjXbupwTqXJ9BRR2N",
    "currency": "USD",
    "destination": null,
    "externally_funded": "UNKNOWN",
    "failure_code": "VELOCITY_LIMIT_EXCEEDED",
    "failure_message": "Daily volume limit exceeded for APPLICATION; Monthly volume limit exceeded for APPLICATION; Daily volume limit exceeded for SENDER; Monthly volume limit exceeded for SENDER",
    "fee": 0,
    "idempotency_id": null,
    "merchant": "MUvYobRWG33L5XKiDZmArTGu",
    "merchant_identity": "ID2wWmoMhhhLZxveU2qCJ4mp",
    "messages": [
        
    ],
    "operation_key": "PULL_FROM_CARD",
    "parent_transfer": null,
    "parent_transfer_trace_id": null,
    "raw": null,
    "ready_to_settle_at": null,
    "receipt_last_printed_at": null,
    "security_code_verification": null,
    "source": "PIt7H487HYBZTHXNLjuHESp8",
    "split_transfers": [
        
    ],
    "state": "FAILED",
    "statement_descriptor": null,
    "subtype": "API",
    "tags": {
        "test": "Velocity Limit Exceeded"
    },
    "tip_amount": null,
    "trace_id": "f339e82c-39eb-42bc-85c6-a9515ea9419a",
    "type": "DEBIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/AP9oVc9EjXbupwTqXJ9BRR2N"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRfb1QBrJVWY3UYpsX4qscDr"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/ID2wWmoMhhhLZxveU2qCJ4mp"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRfb1QBrJVWY3UYpsX4qscDr/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRfb1QBrJVWY3UYpsX4qscDr/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRfb1QBrJVWY3UYpsX4qscDr/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRfb1QBrJVWY3UYpsX4qscDr/disputes"
        },
        "source": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIt7H487HYBZTHXNLjuHESp8"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPoiqRAzS2Yo33RqqS5995db"
        }
    }
}

Velocity Rule Error Codes

Error Code	Description
VELOCITY_RULE_NOT_FOUND	Velocity rule not found. Please contact support if you have any questions.
VELOCITY_VALIDATION_FAILED	Velocity validation failed. Please contact support if you have any questions.
VELOCITY_LIMIT_EXCEEDED	See below for Velocity Limit Exceeded possible values:

Velocity Limit Exceeded Possible Values

When exceeding the velocity rules, Finix will return a list of values that exceeded the velocity rules.

These are the possible values:

Monthly count limit exceeded for APPLICATION
Monthly count limit exceeded for RECIPIENT
Monthly count limit exceeded for SENDER
Daily count limit exceeded for APPLICATION
Daily count limit exceeded for RECIPIENT
Daily count limit exceeded for SENDER
Monthly volume limit exceeded for APPLICATION
Monthly volume limit exceeded for RECIPIENT
Monthly volume limit exceeded for SENDER
Daily volume limit exceeded for APPLICATION
Daily volume limit exceeded for RECIPIENT
Daily volume limit exceeded for SENDER
Maximum amount exceeded for APPLICATION
Maximum amount exceeded for RECIPIENT
Maximum amount exceeded for SENDER

Balance Amount Failures

Each payout customer has a Balance that they can use to send payouts to recipients. When sending a payout, your Balance is decremented. Finix returns the following error when you attempt to send more than your available balance.

API Response for Balance Amount Failures

Copy

Copied

{
    "id": "TRfjvCVjrwwVSHRxukXFVRJr",
    "created_at": "2024-07-23T18:22:00.50Z",
    "updated_at": "2024-07-23T18:22:00.50Z",
    "additional_buyer_charges": null,
    "additional_healthcare_data": null,
    "additional_purchase_data": null,
    "address_verification": null,
    "amount": 8,
    "amount_requested": 8,
    "application": "AP9oVc9EjXbupwTqXJ9BRR2N",
    "currency": "USD",
    "destination": "PItQHHw4ooFYgSFAcvoLKbX9",
    "externally_funded": "UNKNOWN",
    "failure_code": "INSUFFICIENT_BALANCE",
    "failure_message": "Your account balance is insufficient for this operation. Please contact support if you have any questions.",
    "fee": 0,
    "idempotency_id": null,
    "merchant": "MUf8sYLSLqKzN1FaPZjLRrhW",
    "merchant_identity": "IDvHPSftftx9RjUKnibnhHN5",
    "messages": [
        
    ],
    "operation_key": "PUSH_TO_CARD",
    "parent_transfer": null,
    "parent_transfer_trace_id": null,
    "raw": null,
    "ready_to_settle_at": null,
    "receipt_last_printed_at": null,
    "security_code_verification": null,
    "source": null,
    "split_transfers": [
        
    ],
    "state": "FAILED",
    "statement_descriptor": null,
    "subtype": "API",
    "tags": {
        "test": "Disbursements P2C"
    },
    "tip_amount": null,
    "trace_id": "82087d5e-fe69-4253-9773-13c3917fcab4",
    "type": "CREDIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/AP9oVc9EjXbupwTqXJ9BRR2N"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRfjvCVjrwwVSHRxukXFVRJr"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDvHPSftftx9RjUKnibnhHN5"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRfjvCVjrwwVSHRxukXFVRJr/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRfjvCVjrwwVSHRxukXFVRJr/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRfjvCVjrwwVSHRxukXFVRJr/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TRfjvCVjrwwVSHRxukXFVRJr/disputes"
        },
        "destination": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PItQHHw4ooFYgSFAcvoLKbX9"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPoiqRAzS2Yo33RqqS5995db"
        }
    }
}

Balance Amount Error Codes

Error Code	Description
INSUFFICIENT_BALANCE	Your account balance is insufficient for this operation. Please contact support if you have any questions.
BALANCE_ACCOUNT_NOT_FOUND	Balance Account not found. Please contact support if you have questions.
BALANCE_VALIDATION_FAILED	Balance Validation failed.

Third-Party Network Failures

Third-party networks occasionally return an error to Finix for a Payout. A common example could include attempting a payout to an unsupported card.

Finix will return a Failed Transfer. In these scenarios, we recommend viewing the Transfer#messages object for additional details.