List Funding Transfer Attempts for a Settlement

Overview

Retrieve a list of Funding Transfer Attempts (instant payouts) for a Settlement. Funding Transfer Attempts represent real-time push payments to merchant debit cards, as an alternative to standard ACH transfers.

Resource Access

User Permissions: Admin users only
Endpoint: GET /settlements/\{settlement_id}/funding_transfer_attempts

Arguments

Parameter	Type	Required	Description
settlement_id	string	Yes (path)	The unique ID of the Settlement
limit	integer	No	Maximum number of records to return (default: 10)

Example Request

curl -X GET \
  'https://api.ahrvo.network/payments/na/settlements/STsettlementExample123/funding_transfer_attempts?limit=10' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response

{
  "_embedded": {
    "funding_transfer_attempts": [
      {
        "id": "FTAattemptExample001",
        "created_at": "2023-12-11T10:00:00Z",
        "updated_at": "2023-12-11T10:00:15Z",
        "amount": 935000,
        "currency": "USD",
        "state": "SUCCEEDED",
        "settlement_id": "STsettlementExample123",
        "payment_instrument_id": "PIdebitCardExample123",
        "processor": "MASTERCARD_SEND",
        "trace_id": "MS123456789",
        "failure_code": null,
        "failure_message": null,
        "tags": {
          "instant_payout": "true",
          "merchant_request": "urgent"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/funding_transfer_attempts/FTAattemptExample001"
          },
          "settlement": {
            "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123"
          },
          "payment_instrument": {
            "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIdebitCardExample123"
          }
        }
      },
      {
        "id": "FTAattemptExample002",
        "created_at": "2023-12-11T09:50:00Z",
        "updated_at": "2023-12-11T09:50:10Z",
        "amount": 935000,
        "currency": "USD",
        "state": "FAILED",
        "settlement_id": "STsettlementExample123",
        "payment_instrument_id": "PIdebitCardExample456",
        "processor": "VISA_DIRECT",
        "trace_id": null,
        "failure_code": "CARD_NOT_ELIGIBLE",
        "failure_message": "The debit card is not eligible for instant payouts",
        "tags": {
          "instant_payout": "true"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/funding_transfer_attempts/FTAattemptExample002"
          },
          "settlement": {
            "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123"
          },
          "payment_instrument": {
            "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIdebitCardExample456"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 10,
    "count": 2
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123/funding_transfer_attempts?limit=10"
    },
    "settlement": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123"
    }
  }
}

Additional Information

Funding Transfer Attempts: Instant payout alternative to ACH
- Push to merchant's debit card
- Funds available in minutes (not days)
- Higher fees than ACH
- Optional service for merchants who need fast access to funds
vs. Regular Funding Transfers:
- Funding Transfers: Standard ACH to bank account (1-3 days)
- Funding Transfer Attempts: Instant push to debit card (minutes)
- Settlement can have either/both depending on merchant preference
Processors:
- VISA_DIRECT: Visa's instant payout network
- MASTERCARD_SEND: Mastercard's instant payout network
- Must have merchant debit card on file
States:
- PENDING: Attempt submitted, awaiting processor response
- SUCCEEDED: Funds successfully pushed to card
- FAILED: Attempt failed (see failure_code)
Failure Codes (when state = FAILED):
- CARD_NOT_ELIGIBLE: Card doesn't support instant payouts
  - Only debit cards eligible (not credit cards)
  - Card must be enabled for push payments
- INSUFFICIENT_FUNDS: Platform account lacks funds
- CARD_EXPIRED: Merchant's card expired
- CARD_BLOCKED: Card frozen or blocked
- PROCESSOR_ERROR: Visa/Mastercard network error
- AMOUNT_EXCEEDS_LIMIT: Amount exceeds instant payout limits
Payment Instrument: The debit card receiving funds
- Must be type PAYMENT_CARD with subtype DEBIT
- Credit cards not supported for payouts
- Merchant must have card on file
Use Cases:
- Instant Payout Verification: Confirm merchant received instant payout
- Troubleshoot Failed Instant Payout: Check why card payout failed
- Compare Payout Methods: View both ACH and instant payout history
- Fee Analysis: Track instant payout usage (higher fees)
- Merchant Support: Help merchant understand payout status
Common Scenarios:
- Successful Instant Payout:
  - Settlement approved
  - Merchant requests instant payout
  - Attempt created via POST endpoint
  - State = SUCCEEDED
  - Merchant receives funds in minutes
- Failed Then Fallback:
  - Instant payout attempt failed (CARD_NOT_ELIGIBLE)
  - System automatically creates regular ACH transfer
  - Both visible: failed attempt + successful ACH
- Multiple Attempts:
  - First card attempt failed (expired card)
  - Merchant adds new card
  - Second attempt succeeds
  - Both attempts listed
Best Practices:
- Verify card eligibility before creating attempt
- Have fallback to ACH if instant payout fails
- Monitor failure rates by processor
- Communicate instant payout fees to merchant
- Track which merchants prefer instant vs standard payouts
Fees: Instant payouts cost more than ACH
- Typical: $0.50 - $2.00 per payout
- Percentage-based: 1-2% of payout amount
- Merchant must opt-in and agree to fees
Limits:
- Daily/monthly limits on instant payout amounts
- Per-transaction maximums (often $10,000 - $25,000)
- Varies by processor and merchant risk profile
Related Endpoints:
- POST /settlements/{id}/funding_transfer_attempts: Create new instant payout
- GET /settlements/{id}/funding_transfers: View standard ACH transfers
- GET /payment_instruments/{id}: Check card details and eligibility

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​