Skip to main content

List Funding Transfers for a Settlement

Overview​

Retrieve a list of Funding Transfers (ACH, Wire, or other payment transfers) that were created for paying out a Settlement to a merchant. Typically each settlement has one funding transfer, but may have multiple in case of failures or retries.

Resource Access​

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

Arguments​

ParameterTypeRequiredDescription
settlement_idstringYes (path)The unique ID of the Settlement
limitintegerNoMaximum number of records to return (default: 10)

Example Request​

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

Example Response​

{
  "_embedded": {
    "transfers": [
      {
        "id": "TRfundingTransfer001",
        "created_at": "2023-12-11T09:00:00Z",
        "updated_at": "2023-12-11T09:05:00Z",
        "amount": 935000,
        "currency": "USD",
        "state": "SUCCEEDED",
        "trace_id": "ACH123456789",
        "destination": "MImerchantIdentity123",
        "merchant_identity": "MImerchantIdentity123",
        "application": "APapplicationExample123",
        "type": "FUNDING",
        "subtype": "PLATFORM_CREDIT",
        "tags": {
          "settlement_id": "STsettlementExample123"
        },
        "failure_code": null,
        "failure_message": null,
        "ready_to_settle_at": "2023-12-11T09:00:00Z",
        "externally_funded": "EXTERNALLY_FUNDED",
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/transfers/TRfundingTransfer001"
          },
          "settlement": {
            "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123"
          },
          "application": {
            "href": "https://api.ahrvo.network/payments/na/applications/APapplicationExample123"
          },
          "merchant_identity": {
            "href": "https://api.ahrvo.network/payments/na/identities/MImerchantIdentity123"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 10,
    "count": 1
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123/funding_transfers?limit=10"
    },
    "settlement": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123"
    }
  }
}

Additional Information​

  • Funding Transfer: The actual ACH or wire transfer that pays the merchant
    • Created after settlement approved
    • Moves funds from platform account to merchant bank account
    • Amount = settlement net_amount
  • Transfer States:
    • PENDING: Transfer created, waiting to process
    • SUCCEEDED: Funds successfully sent to merchant
    • FAILED: Transfer failed (insufficient funds, invalid account, etc.)
    • CANCELED: Transfer canceled before processing
  • Transfer Types:
    • type = FUNDING: Indicates payout to merchant
    • subtype = PLATFORM_CREDIT: Credits merchant account
  • Externally Funded:
    • EXTERNALLY_FUNDED: Platform sends ACH/wire externally
    • NOT_EXTERNALLY_FUNDED: Internal ledger movement only
  • Multiple Funding Transfers:
    • Normally 1 transfer per settlement
    • May have multiple if:
      • First transfer failed (wrong account, insufficient funds)
      • Retry attempted with corrected information
      • Settlement split into multiple payouts
  • Trace ID: ACH trace number or wire reference
    • Used for bank reconciliation
    • Appears on merchant's bank statement
    • Required for investigating failed transfers
  • Use Cases:
    • Settlement Reconciliation: Verify payout sent to merchant
    • Failure Investigation: Check why merchant didn't receive funds
    • Bank Statement Matching: Find trace ID for merchant's bank
    • Retry Analysis: View history of failed/retried transfers
    • Accounting: Confirm settlement funding status
  • Common Scenarios:

    • Successful Settlement:

      • 1 funding transfer in SUCCEEDED state
      • Amount matches settlement net_amount
      • Merchant receives funds in 1-3 business days

    • Failed Then Succeeded:

      • First transfer FAILED (invalid account)
      • Merchant updates bank information
      • Second transfer SUCCEEDED
      • Both visible in list

    • Still Pending:

      • Transfer in PENDING state
      • Awaiting processing by bank
      • Check back in 24 hours
  • Failure Codes: When state = FAILED
    • failure_code: Machine-readable error code
    • failure_message: Human-readable explanation
    • Common codes:
      • INVALID_ACCOUNT_NUMBER: Bank account invalid
      • INSUFFICIENT_FUNDS: Platform account insufficient balance
      • ACCOUNT_FROZEN: Merchant account frozen/closed
      • ROUTING_NUMBER_INVALID: Invalid routing number
  • Related Endpoints:
    • GET /transfers/{id}: Full transfer details
    • GET /settlements/{id}: Settlement summary
    • POST /settlements/{id}/funding_transfer_attempts: Create instant payout (push to debit card)