> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Funding events and reconciliation

> Understand how Straddle ACH payments settle, how funding events are generated, and how to reconcile charges, payouts, and fees with your accounting system.

Funding events represent the actual movement of money between Straddle and your linked bank accounts—the financial backbone that connects your payment operations to real bank transfers. While charges and payouts handle individual transactions, funding events track the net settlements that appear in your bank statements.

## Why Funding Events Matter

Understanding funding events is essential for:

* **Financial reconciliation**: Match bank statement entries to specific payments
* **Cash flow management**: Predict when funds will arrive or be withdrawn
* **Accounting accuracy**: Track deposits, withdrawals, and reversals with funding event IDs and trace numbers
* **Operational monitoring**: Identify settlement patterns and handle exceptions

This guide explains how charges and payouts translate into funding events, settlement timing, and reconciliation workflows that keep your books balanced.

## What Are Funding Events?

Funding events track all money movement between Straddle and your external bank accounts. They are automatically generated when:

* **Charges settle** - Deposits to your account from successful charges
* **Payouts are initiated** - Withdrawals from your account to fund payouts
* **Returns occur** - Reversals of previously settled charges
* **Payouts fail** - Returns of failed payout attempts

<Note>
  Funding events represent the **net settlement** to your bank account, not individual transactions. Multiple charges or payouts may be bundled into a single funding event.
</Note>

## Funding Event Types

Straddle uses four funding event types that describe both direction and reason:

| Event Type          | Direction          | Description                                 | When It Occurs                               |
| ------------------- | ------------------ | ------------------------------------------- | -------------------------------------------- |
| `charge_deposit`    | Deposit (credit)   | Successful charges being deposited          | Daily settlement of paid charges             |
| `charge_reversal`   | Withdrawal (debit) | Previously deposited charges being returned | When funded charges reverse (R01, R10, etc.) |
| `payout_withdrawal` | Withdrawal (debit) | Funds being withdrawn for payouts           | Before payouts are sent to recipients        |
| `payout_return`     | Deposit (credit)   | Failed payouts being returned               | When payouts fail or are returned            |

## Understanding Transfer Direction

The `direction` field describes money movement from your linked bank account's perspective:

| Direction    | Meaning                         | Impact on Your Balance |
| ------------ | ------------------------------- | ---------------------- |
| `deposit`    | Money coming INTO your account  | Increases balance      |
| `withdrawal` | Money going OUT of your account | Decreases balance      |

## Settlement Timing

Straddle's default funding time is **one business day** (`one_day`) based on the payment's effective date:

<Steps>
  <Step title="Payment Created">
    A charge or payout is created with a `payment_date`
  </Step>

  <Step title="Effective Date Determined">
    The `effective_date` is when the payment enters the payment date
  </Step>

  <Step title="Funding Event Created">
    Settlement occurs one business day after the effective date:

    * Monday effective → Tuesday funding
    * Friday effective → Monday funding (skips weekend)
  </Step>

  <Step title="Bank Account Activity">
    Your linked bank account receives the net settlement
  </Step>
</Steps>

### Example Timeline

**Monday Charge Example:**

* Created Monday 8pm → Effective Tuesday → Funded Wednesday

**Friday Charge Example:**

* Created Friday 2pm → Effective Friday → Funded Monday (skips weekend)

<Warning>
  **Critical Distinction for Payouts vs Charges:**

  * **Charges**: Funding events occur AFTER the charge completes (`paid` status)
  * **Payouts**: Funding events occur BEFORE the payout is sent (withdrawal to fund the payout)

  This means payout funding events represent Straddle collecting funds from you to send to recipients.
</Warning>

## Funding Event Structure

Each funding event contains:

```json theme={null}
{
  "id": "fe_abc123def456",
  "amount": 150000,  // $1,500.00 in cents
  "direction": "deposit",
  "event_type": "charge_deposit",
  "payment_count": 12,  // Number of payments in this event
  "transfer_date": "2024-10-23",
  "trace_number": "071000301234567",
  "trace_numbers": [
    "071000301234567",
    "071000301234568"
  ]
}
```

### Field Descriptions

| Field           | Description                                                                                               |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| `id`            | Unique identifier for the funding event. Primary key for bank reconciliation.                             |
| `amount`        | Total amount in cents                                                                                     |
| `direction`     | `deposit` or `withdrawal`                                                                                 |
| `event_type`    | Type of funding event                                                                                     |
| `payment_count` | Number of individual payments bundled                                                                     |
| `transfer_date` | Date funds were transferred                                                                               |
| `trace_number`  | Primary ACH trace number. Available on the funding event but not guaranteed to appear on bank statements. |
| `trace_numbers` | All trace numbers if multiple                                                                             |

## Reconciling to Your Bank Statement

Each funding event produces a single ACH transfer to or from your linked bank account. The ACH file includes an addenda record on that transfer containing:

* The funding event `id` (e.g., `fe_abc123def456`)
* A plain-text description matching the `event_type`: `charge deposit`, `payout withdrawal`, `charge reversal`, or `payout return`

Your bank displays the addenda alongside the transfer entry, giving you a direct reference back to the Straddle funding event. Reconciliation is circular: the `id` in the bank statement addenda is the same `id` returned by the Straddle API.

<Tip>
  Use the funding event `id` as the primary key when matching bank statement entries to Straddle records. It appears reliably in the ACH addenda record and maps directly to the identifier returned by the API.
</Tip>

**Trace numbers as a backup.** Trace numbers are available on every funding event (`trace_number`, `trace_numbers`), but they are not guaranteed to appear on bank statements. Some financial institutions strip or do not surface addenda fields in their transaction exports. Treat trace numbers as a secondary reference when the funding event `id` is unavailable.

## Charge Funding Flow

Understanding how charges become funding events:

1. **Charge Created** (Monday 8pm)
2. **Scheduled** for processing
3. **Pending** - Sent to network (Tuesday morning)
4. **Funding Event Created** (Tuesday) - Type: `charge_deposit`
5. **Paid** - Successfully completed (Wednesday morning)
6. Money deposited to your account

If a charge is later returned:
7\. **Reversed** status on charge
8\. **Reversal Funding Event** created (next day) - Type: `charge_reversal`
9\. Money withdrawn from your account

### Example: Multiple Charges, Single Funding Event

Monday's charges:

* Charge 1: \$100.00 - Paid Tuesday
* Charge 2: \$250.00 - Paid Tuesday
* Charge 3: \$75.00 - Paid Tuesday

Wednesday's funding event:

```json theme={null}
{
  "id": "fe_wednesday123",
  "amount": 42500,  // $425.00 total
  "direction": "deposit",
  "event_type": "charge_deposit",
  "payment_count": 3,
  "transfer_date": "2024-10-23"
}
```

## Payout Funding Flow

Payouts require funding BEFORE being sent:

1. **Payout Created** - Needs funding
2. **Funding Event Created** - Type: `payout_withdrawal`
3. **Money Withdrawn** from your account
4. **Payout Sent** to recipient
5. **Payout Paid** - Successfully completed

If payout fails:
6\. **Payout Failed** status
7\. **Return Funding Event** created - Type: `payout_return`
8\. **Money Deposited Back** to your account

### Example: Payout Funding Sequence

1. **Monday**: Create \$500 payout
2. **Monday**: Funding event withdraws \$500 from your account
3. **Tuesday**: Payout sent to recipient
4. **Wednesday**: Payout completes successfully

If payout fails:
5\. **Thursday**: Payout marked as `failed`
6\. **Friday**: Return funding event deposits \$500 back

## Searching Funding Events

Use the funding events API to search and filter:

```bash theme={null}
curl -X GET "https://sandbox.straddle.com/v1/funding_events?\
  created_from=2024-10-01&\
  created_to=2024-10-31&\
  direction=deposit&\
  event_type=charge_deposit" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Search Parameters

| Parameter      | Description             | Example                         |
| -------------- | ----------------------- | ------------------------------- |
| `created_from` | Start date (YYYY-MM-DD) | `2024-10-01`                    |
| `created_to`   | End date (YYYY-MM-DD)   | `2024-10-31`                    |
| `direction`    | Filter by direction     | `deposit`, `withdrawal`         |
| `event_type`   | Filter by type          | `charge_deposit`                |
| `trace_number` | Find by trace number    | `071000301234567`               |
| `sort_by`      | Sort field              | `transfer_date`, `amount`, `id` |
| `sort_order`   | Sort direction          | `asc`, `desc`                   |

## Getting Funding Event Details

Retrieve individual funding event with payment details:

```bash theme={null}
curl -X GET https://sandbox.straddle.com/v1/funding_events/{id} \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This returns the funding event with associated payment IDs for detailed reconciliation.

## Reconciliation Workflows

### Daily Reconciliation

```javascript theme={null}
async function dailyReconciliation(date) {
  // Get all funding events for the date
  const fundingEvents = await straddle.fundingEvents.list({
    created_from: date,
    created_to: date
  });
  
  for (const event of fundingEvents.data) {
    // Get detailed payment information
    const details = await straddle.fundingEvents.retrieve(event.id);
    
    // Match against your records using the funding event id.
    // This id appears in the ACH addenda record on your bank statement,
    // making it the reliable key for programmatic reconciliation.
    await reconcile({
      fundingEventId: event.id,   // primary reconciliation key
      amount: event.amount,
      direction: event.direction,
      type: event.event_type,
      paymentCount: event.payment_count,
      transferDate: event.transfer_date,
      traceNumber: event.trace_number  // backup: not guaranteed on all bank statements
    });
    
    // Update your ledger
    await updateLedger(event);
  }
}
```

### Matching Payments to Funding Events

Charges and payouts include `funding_ids` array:

```javascript theme={null}
async function matchPaymentToFunding(chargeId) {
  // Get charge details
  const charge = await straddle.charges.retrieve(chargeId);
  
  // Check funding IDs
  if (charge.funding_ids && charge.funding_ids.length > 0) {
    for (const fundingId of charge.funding_ids) {
      const fundingEvent = await straddle.fundingEvents.retrieve(fundingId);
      
      console.log(`Charge ${chargeId} settled in funding event ${fundingId}`);
      console.log(`Settlement date: ${fundingEvent.transfer_date}`);
      console.log(`Trace number: ${fundingEvent.trace_number}`);
    }
  } else {
    console.log(`Charge ${chargeId} not yet funded`);
  }
}
```

### Handling Reversals

Track both original deposits and subsequent reversals:

```javascript theme={null}
async function handleChargeReversal(chargeId) {
  const charge = await straddle.charges.retrieve(chargeId);
  
  if (charge.status === 'reversed') {
    // Find original deposit
    const originalDeposit = charge.funding_ids[0];
    
    // Look for reversal funding event
    const reversalEvents = await straddle.fundingEvents.list({
      event_type: 'charge_reversal',
      created_from: charge.updated_at.split('T')[0]
    });
    
    // Match and update records
    for (const reversal of reversalEvents.data) {
      // Update your ledger for the reversal
      await recordReversal({
        originalChargeId: chargeId,
        originalFundingId: originalDeposit,
        reversalFundingId: reversal.id,
        amount: reversal.amount,
        date: reversal.transfer_date
      });
    }
  }
}
```

## Common Patterns

### End-of-Day Settlement Report

```javascript theme={null}
async function generateSettlementReport(date) {
  const fundingEvents = await straddle.fundingEvents.list({
    transfer_date: date,
    sort_by: 'event_type'
  });
  
  const report = {
    date,
    summary: {
      charge_deposits: { count: 0, amount: 0 },
      charge_reversals: { count: 0, amount: 0 },
      payout_withdrawals: { count: 0, amount: 0 },
      payout_returns: { count: 0, amount: 0 }
    },
    events: []
  };
  
  for (const event of fundingEvents.data) {
    report.summary[event.event_type].count++;
    report.summary[event.event_type].amount += event.amount;
    report.events.push(event);
  }
  
  report.netSettlement = 
    report.summary.charge_deposits.amount + 
    report.summary.payout_returns.amount -
    report.summary.charge_reversals.amount -
    report.summary.payout_withdrawals.amount;
  
  return report;
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Daily Reconciliation" icon="calendar-check">
    Reconcile funding events daily against your bank statements
  </Card>

  <Card title="Reconcile by Funding Event ID" icon="hashtag">
    Use the funding event `id` as the primary key for bank statement reconciliation. It appears in the ACH addenda record and maps directly to the Straddle API response.
  </Card>

  <Card title="Monitor Reversals" icon="rotate-left">
    Set up alerts for charge reversals to handle returns promptly
  </Card>

  <Card title="Understand Timing" icon="clock">
    Account for business day delays in settlement calculations
  </Card>
</CardGroup>

## Troubleshooting

### Missing Funding Events

If expected funding events are missing:

1. **Check payment status** - Only `paid` charges create deposits
2. **Verify business days** - Weekends and holidays delay funding
3. **Review cutoff times** - Late payments may settle next day
4. **Check for holds** - Compliance holds can delay funding

### Reconciliation Mismatches

Common causes of discrepancies:

* **Timing differences** - Effective date vs transfer date
* **Bundled payments** - Multiple charges in one funding event
* **Returns/reversals** - Original deposit and reversal are separate events
* **Fee deductions** - Platform fees may be netted (if applicable)

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/funding/search">
    Funding events endpoint documentation
  </Card>

  <Card title="Payment Reports" icon="chart-line" href="/guides/payments/reports">
    Advanced reporting and searches
  </Card>

  <Card title="Webhook Events" icon="webhook" href="/webhooks/overview/events">
    Set up funding event notifications
  </Card>

  <Card title="Testing Funding" icon="flask" href="/guides/resources/sandbox-paybybank">
    Test funding flows in sandbox
  </Card>
</CardGroup>