Failed transfers can occur for various reasons during the payment process, such as insufficient funds, invalid account information, or network issues. The Search Transfers API provides powerful filtering capabilities to help you identify, analyze, and manage failed transfers efficiently.

By leveraging the Search Transfers API’s filtering capabilities, you can:

  • Quickly identify and categorize transfer failures
  • Provide better support to merchants experiencing transfer issues

Regular monitoring and prompt resolution of failed transfers help ensure a positive experience for both your platform and your merchants. This guide will walk you through the process of filtering failed transfers, understanding error information, and implementing best practices for handling transfer failures.

​
Understanding Transfer Status

When filtering for failed transfers, you’ll be searching against the FAILED status. This status indicates that the transfer could not be completed successfully due to various reasons, which are detailed in the errors array of the Transfer object. To learn about the Transfer object in detail, refer to the Transfer page in our documentation.

​
Basic Failed Transfer Filtering

To retrieve all failed transfers, use the Search Transfers API with the status parameter set to FAILED:

curl --request POST \
  --url https://sandbox-api.violet.io/v1/payments/transfers \
  --header 'Content-Type: application/json' \
  --header 'X-Violet-App-Id: <X-Violet-App-ID>' \
  --header 'X-Violet-App-Secret: <X-Violet-App-Secret>' \
  --header 'X-Violet-Token: <X-Violet-Token>' \
  --data '{
    "status": "FAILED"
  }'

This will return all failed transfers across your account, providing a comprehensive view of transfer failures.

​
Advanced Filtering Options

​
Filtering by Merchant

To focus on failed transfers for a specific merchant, combine the status filter with merchant_id:

curl --request POST \
  --url https://sandbox-api.violet.io/v1/payments/transfers \
  --header 'Content-Type: application/json' \
  --header 'X-Violet-App-Id: <X-Violet-App-ID>' \
  --header 'X-Violet-App-Secret: <X-Violet-App-Secret>' \
  --header 'X-Violet-Token: <X-Violet-Token>' \
  --data '{
    "merchant_id": 12345,
    "status": "FAILED"
  }'

​
Filtering by Date Range

To analyze failed transfers within a specific timeframe, use the date range parameters:

curl --request POST \
  --url https://sandbox-api.violet.io/v1/payments/transfers \
  --header 'Content-Type: application/json' \
  --header 'X-Violet-App-Id: <X-Violet-App-ID>' \
  --header 'X-Violet-App-Secret: <X-Violet-App-Secret>' \
  --header 'X-Violet-Token: <X-Violet-Token>' \
  --data '{
    "status": "FAILED",
    "created_after": "2025-07-05T00:00:00Z",
    "created_before": "2025-07-12T23:59:59Z"
  }'

​
Understanding Failed Transfer Response

The Search API will return a Page of FAILED transfers with the queries above. Each Transfer will be present in the content array of the response, and will contain details about the errors that caused the failure.

{
      "content": [
          {
            "id": 123,
            "status": "FAILED",
            "amount": 10000,
            "currency": "USD",
            "merchant_id": 12345,
            "payout_account_id": 789,
            "payment_provider": "STRIPE",
            "errors": [
              {
                "payout_transfer_id": 123,
                "error_code": 1001,
                "error_message": "Insufficient funds in source account",
                "date_created": "2023-11-07T05:31:56Z",
              }
            ],
            "date_created": "2023-11-07T05:31:56Z",
            "date_last_modified": "2023-11-07T05:31:56Z"
          }
      ],
      "pageable": {
          "page_number": 0,
          "page_size": 20,
          "sort": {
              "sorted": true,
              "unsorted": false,
              "empty": false
          },
          "offset": 0,
          "paged": true,
          "unpaged": false
      },
      "total_pages": 1,
      "total_elements": 1,
      "last": true,
      "number_of_elements": 1,
      "first": true,
      "size": 20,
      "number": 0,
      "sort": {
          "sorted": true,
          "unsorted": false,
          "empty": false
      },
      "empty": false
  }
}

​
Error Analysis and Common Failure Reasons

Failed transfers typically fall into several categories. The most common failures are from:

Account-Related Failures

  • Missing Payout Accounts
  • Account verification issues

Compliance and Regulatory Failures

  • KYC (Know Your Customer) verification pending
  • Regulatory restrictions in destination country

When transfers fail, the associated Distribution objects remain in the PENDING state, allowing you to retry the transfer once the issues are resolved. You can use the following APIs to settle PENDING distributions that were a result of failed transfers:

​
Integration with Webhook Events

Violet provides a dedicated FAILED_TRANSFER webhook event that notifies you when a transfer fails. This event includes detailed information about the transfer and the associated errors, allowing you to take immediate action. Learn more about handling webhooks in our Transfers Events page.