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.

Velocity Rule Failure Example

Payout Transfer failed due to velocity rule

{
    "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

Transfer `failure_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.

Balance Amount Failure Example

Payout Transfer failed due to balance amount

{
    "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

Transfer `failure_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.