> ## 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.

# Payments overview

> Learn how charges, payouts, and funding events work together in Straddle to power ACH bank payments, settlements, and reconciliation for your platform.

Straddle's payment system provides a unified API for moving money between your platform and your customers' bank accounts. This guide covers the core concepts and workflows for processing payments through Straddle.

<Note>
  Before processing payments, you'll need to have [verified customers](/guides/identity/customers) and [connected bank accounts](/guides/bridge/overview) set up through Straddle's Identity and Bridge services.
</Note>

## Core Payment Concepts

Straddle organizes payment operations into three primary concepts:

<CardGroup cols={3}>
  <Card title="Charges" icon="arrow-down-to-line" href="/guides/payments/charges">
    Collect money from your customers' bank accounts
  </Card>

  <Card title="Payouts" icon="arrow-up-from-line" href="/guides/payments/payouts">
    Send money to your customers' bank accounts
  </Card>

  <Card title="Funding Events" icon="building-columns" href="/guides/payments/funding">
    Track money movement between Straddle and your business
  </Card>
</CardGroup>

### Understanding the Flow

When you process payments through Straddle:

1. **Charges** pull money from customer accounts into Straddle's network
2. **Payouts** push money from Straddle's network to customer accounts
3. **Funding Events** represent the settlement of these transactions to your business bank account

## Payment Rails

Straddle automatically optimizes payment routing across multiple rails to balance speed, cost, and reliability. You don't need to specify which rail to use - Straddle selects the optimal option automatically:

<AccordionGroup>
  <Accordion title="ACH (Automated Clearing House)" icon="clock">
    **Processing Time**: 1-3 business days

    **Use Cases**:

    * Standard recurring payments
    * High-value transactions
    * Batch processing

    **Characteristics**:

    * Lower cost per transaction
    * Higher daily limits
    * Reversible for up to 60 days
  </Accordion>

  <Accordion title="RTP (Real-Time Payments)" icon="bolt">
    **Processing Time**: Seconds

    **Use Cases**:

    * Instant disbursements
    * Time-sensitive payments
    * Enhanced customer experience

    **Characteristics**:

    * 24/7/365 availability
    * Irrevocable once completed
    * Maximum \$1 million per transaction
  </Accordion>

  <Accordion title="FedNow" icon="building-columns">
    **Processing Time**: Seconds

    **Use Cases**:

    * Government payments
    * Instant settlement needs
    * Critical payment flows

    **Characteristics**:

    * Federal Reserve operated
    * 24/7/365 availability
    * Enhanced security and compliance
  </Accordion>

  <Accordion title="Same Day ACH" icon="calendar-day">
    **Processing Time**: Same business day

    **Use Cases**:

    * Urgent business payments
    * Payroll disbursements
    * Time-sensitive refunds

    **Characteristics**:

    * Multiple processing windows daily
    * Business days only
    * Higher limits than standard ACH
  </Accordion>
</AccordionGroup>

## Quick Start Example

Here's a complete payment flow from customer creation to fund settlement:

<Steps>
  <Step title="Create a verified customer">
    First, onboard your customer through Straddle's Identity service:

    ```bash theme={null}
    curl --request POST \
      --header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
      --url https://sandbox.straddle.com/v1/customers \
      --header 'Content-Type: application/json' \
      --data '{
      "name": "Ron Swanson",
      "type": "individual",
      "email": "user@example.com",
      "phone": "+12128675309",
      "device": {
        "ip_address": "192.168.1.1"
      }
    }'
    ```
  </Step>

  <Step title="Connect a bank account">
    Use Bridge to securely link the customer's bank account and generate a paykey:

    ```bash theme={null}
    curl --request POST \
      --header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
      --url https://sandbox.straddle.com/v1/bridge/plaid \
      --header 'Content-Type: application/json' \
      --data '{
      "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "plaid_token": "<string>"
    }'
    ```

    This returns a session for the customer to complete bank authentication, resulting in a `paykey`.
  </Step>

  <Step title="Create a charge">
    Use the paykey to charge the customer:

    ```bash theme={null}
    curl --request POST \
      --header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
      --url https://sandbox.straddle.com/v1/charges \
      --header 'Content-Type: application/json' \
      --data '{
      "paykey": "<string>",
      "description": "Monthly subscription fee",
      "amount": "10000",
      "currency": "<string>",
      "payment_date": "2019-12-27",
      "consent_type": "internet",
      "device": {
        "ip_address": "192.168.1.1"
      },
      "external_id": "<string>",
      "config": {
        "balance_check": "required"
      }
    }'
    ```

    <Note>
      All fields shown are required. See the [charges guide](/guides/payments/charges) for complete parameter documentation.
    </Note>
  </Step>

  <Step title="Monitor the payment">
    Track the charge status through [webhooks](/webhooks/overview/events):

    * `created` → Payment initiated
    * `scheduled` → Queued for processing
    * `pending` → Sent to payment network
    * `paid` → Successfully completed

    See [payment statuses](/guides/payments/statuses) for complete lifecycle details.
  </Step>

  <Step title="Reconcile funding">
    View the corresponding funding event once the payment settles:

    ```bash theme={null}
    curl -X GET https://api.straddle.com/v1/funding?charge_id=ch_abc123 \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    Learn more about [funding and reconciliation](/guides/payments/funding).
  </Step>
</Steps>

## Payment Security

Straddle implements multiple layers of security for payment processing:

<CardGroup cols={2}>
  <Card title="Transaction Monitoring" icon="shield-check">
    Real-time fraud detection and risk scoring on every transaction
  </Card>

  <Card title="Balance Verification" icon="scale-balanced">
    Optional pre-transaction balance checks to reduce NSF returns
  </Card>

  <Card title="Velocity Controls" icon="gauge">
    Configurable limits on transaction amounts and frequency
  </Card>

  <Card title="Hold & Review" icon="pause">
    Ability to pause suspicious transactions for manual review
  </Card>
</CardGroup>

## Common Workflows

### Recurring Subscriptions

Process regular charges using stored paykeys:

* Store customer paykeys after initial authentication
* Create charges on your billing schedule
* Handle failures and retries automatically
* Update payment methods when needed

### Marketplace Payouts

Distribute funds to your sellers or service providers:

* Verify recipient identity and bank accounts
* Create payouts with detailed descriptions
* Track payout status and handle failures
* Reconcile platform fees and net settlements

### Instant Transfers

Provide immediate fund availability:

* Use RTP rail for sub-second processing
* Verify account eligibility for instant payments
* Handle fallback to standard ACH if needed
* Communicate clear timing to customers

## Testing Payments

Straddle provides comprehensive sandbox testing capabilities:

* **Deterministic outcomes** - Control payment success/failure scenarios
* **Accelerated processing** - Payments process in minutes instead of days
* **Webhook simulation** - Test your event handling logic
* **Error scenarios** - Simulate NSF, closed accounts, and returns

See [sandbox testing guide](/guides/resources/sandbox-paybybank) for detailed examples.

## Next Steps

<CardGroup cols={2}>
  <Card title="Process Charges" icon="arrow-down-to-line" href="/guides/payments/charges">
    Learn to collect payments from customers
  </Card>

  <Card title="Send Payouts" icon="arrow-up-from-line" href="/guides/payments/payouts">
    Understand disbursing funds to customers
  </Card>

  <Card title="Payment Statuses" icon="list-check" href="/guides/payments/statuses">
    Master payment lifecycles and status flows
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/charges/create">
    Explore the complete API documentation
  </Card>
</CardGroup>