Filtering Failed Transfers
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.
Last updated
Was this helpful?