Skip to content

Handling 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_FOUNDVelocity rule not found. Please contact support if you have any questions.
VELOCITY_VALIDATION_FAILEDVelocity validation failed. Please contact support if you have any questions.
VELOCITY_LIMIT_EXCEEDEDSee 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_BALANCEYour account balance is insufficient for this operation. Please contact support if you have any questions.
BALANCE_ACCOUNT_NOT_FOUNDBalance Account not found. Please contact support if you have questions.
BALANCE_VALIDATION_FAILEDBalance Validation failed. Please try again.

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.