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.
Before processing payments, you’ll need to have verified customers and connected bank accounts set up through Straddle’s Identity and Bridge services.

​
Core Payment Concepts

Straddle organizes payment operations into three primary concepts:

Charges

Collect money from your customers’ bank accounts

Payouts

Send money to your customers’ bank accounts

Funding Events

Track money movement between Straddle and your business

​
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:

​
Quick Start Example

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

Create a verified customer

First, onboard your customer through Straddle’s Identity service:
curl --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
  --url https://sandbox.straddle.io/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"
  }
}'
2

Connect a bank account

Use Bridge to securely link the customer’s bank account and generate a paykey:
curl --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
  --url https://sandbox.straddle.io/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.
3

Create a charge

Use the paykey to charge the customer:
curl --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
  --url https://sandbox.straddle.io/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"
  }
}'
All fields shown are required. See the charges guide for complete parameter documentation.
4

Monitor the payment

Track the charge status through webhooks:
  • created → Payment initiated
  • scheduled → Queued for processing
  • pending → Sent to payment network
  • paid → Successfully completed
See payment statuses for complete lifecycle details.
5

Reconcile funding

View the corresponding funding event once the payment settles:
curl -X GET https://api.straddle.io/v1/funding?charge_id=ch_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
Learn more about funding and reconciliation.

​
Payment Security

Straddle implements multiple layers of security for payment processing:

Transaction Monitoring

Real-time fraud detection and risk scoring on every transaction

Balance Verification

Optional pre-transaction balance checks to reduce NSF returns

Velocity Controls

Configurable limits on transaction amounts and frequency

Hold & Review

Ability to pause suspicious transactions for manual review

​
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 for detailed examples.

​
Next Steps

Process Charges

Learn to collect payments from customers

Send Payouts

Understand disbursing funds to customers

Payment Statuses

Master payment lifecycles and status flows

API Reference

Explore the complete API documentation