Funding events and reconciliation

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

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.

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:

Payment Created

A charge or payout is created with a payment_date

Effective Date Determined

The effective_date is when the payment enters the payment date

Funding Event Created

Settlement occurs one business day after the effective date:

Monday effective → Tuesday funding
Friday effective → Monday funding (skips weekend)

Bank Account Activity

Your linked bank account receives the net settlement

Example Timeline

Monday Charge Example:

Created Monday 8pm → Effective Tuesday → Funded Wednesday

Friday Charge Example:

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

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.

Funding Event Structure

Each funding event contains:

{
  "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.

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.

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:

Charge Created (Monday 8pm)
Scheduled for processing
Pending - Sent to network (Tuesday morning)
Funding Event Created (Tuesday) - Type: charge_deposit
Paid - Successfully completed (Wednesday morning)
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:

{
  "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:

Payout Created - Needs funding
Funding Event Created - Type: payout_withdrawal
Money Withdrawn from your account
Payout Sent to recipient
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

Monday: Create $500 payout
Monday: Funding event withdraws $500 from your account
Tuesday: Payout sent to recipient
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:

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:

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

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:

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:

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

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

Daily Reconciliation

Reconcile funding events daily against your bank statements

Reconcile by Funding Event ID

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.

Monitor Reversals

Set up alerts for charge reversals to handle returns promptly

Understand Timing

Account for business day delays in settlement calculations

Troubleshooting

Missing Funding Events

If expected funding events are missing:

Check payment status - Only paid charges create deposits
Verify business days - Weekends and holidays delay funding
Review cutoff times - Late payments may settle next day
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

API Reference

Funding events endpoint documentation

Payment Reports

Advanced reporting and searches

Webhook Events

Set up funding event notifications

Testing Funding

Test funding flows in sandbox

​Why Funding Events Matter

​What Are Funding Events?

​Funding Event Types

​Understanding Transfer Direction

​Settlement Timing

​Example Timeline

​Funding Event Structure

​Field Descriptions

​Reconciling to Your Bank Statement

​Charge Funding Flow

​Example: Multiple Charges, Single Funding Event

​Payout Funding Flow

​Example: Payout Funding Sequence

​Searching Funding Events

​Search Parameters

​Getting Funding Event Details

​Reconciliation Workflows

​Daily Reconciliation

​Matching Payments to Funding Events

​Handling Reversals

​Common Patterns

​End-of-Day Settlement Report

​Best Practices

Daily Reconciliation

Reconcile by Funding Event ID

Monitor Reversals

Understand Timing

​Troubleshooting

​Missing Funding Events

​Reconciliation Mismatches

​Next Steps

API Reference

Payment Reports

Webhook Events

Testing Funding

Why Funding Events Matter

What Are Funding Events?

Funding Event Types

Understanding Transfer Direction

Settlement Timing

Example Timeline

Funding Event Structure

Field Descriptions

Reconciling to Your Bank Statement

Charge Funding Flow

Example: Multiple Charges, Single Funding Event

Payout Funding Flow

Example: Payout Funding Sequence

Searching Funding Events

Search Parameters

Getting Funding Event Details

Reconciliation Workflows

Daily Reconciliation

Matching Payments to Funding Events

Handling Reversals

Common Patterns

End-of-Day Settlement Report

Best Practices

Troubleshooting

Missing Funding Events

Reconciliation Mismatches

Next Steps