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


## Related topics

- [Payment status and lifecycle reference](/guides/payments/statuses.md)
- [Identity verification overview](/guides/identity/overview.md)
- [Bridge API overview](/guides/bridge/overview.md)
- [Straddle Embed for platforms overview](/guides/embed/overview.md)
- [Integrations overview](/integrations/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.