​
Getting Started

Welcome! Follow the instructions below to learn how to start building with Straddle.

Get Sandbox Access

  1. Visit straddle.io/sign-up
  2. Enter your name and email
  3. Define your use case:
    • Choose ‘Business’ if you’re building directly into Straddle
    • Choose ‘Platform’ if your software is enabling payments for other businesses
  4. Verify your email and log in to the dashboard
An organization will be created that your Account or Platform will belong to.

Invite Your Team

Assign roles to your team members:
  • Admin
  • Developer
  • Member

Generate API Keys

  1. In the dashboard, navigate to the API Keys section
  2. Generate a new API key
  3. Store your API key securely - you won’t be able to view it again
Never share your API keys or commit them to version control. Use environment variables to store them securely.

Configure Webhooks

  1. In the dashboard, go to the Webhooks section
  2. Add a new webhook endpoint URL
  3. Select the events you want to receive
  4. Save your webhook configuration

​
Start Building

Now that you’ve set up your account, let’s start integrating Straddle into your application.

Onboard Customers

Verify and onboard customers with Straddle Identity.

Connect with Bridge

Generate a secure paykey with our Bridge widget or bring your own token.

Get paid

Initiate transactions and move money between accounts.

​
Create a Customer

First, let’s create a customer: 
curl -X POST https://api.straddle.io/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "type": "individual",
    "email": "john@example.com",
    "address": {
      "address1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "12345"
    },
    "phone": "+1234567890",
    "external_id": "cust_123",
    "device": {
      "ip_address": "192.168.1.1"
    },
    "metadata": {
      "user_id": "12345"
    }
  }'
All customers are automatically verified by Straddle Identity. The response will contain a unique id and the status of the customer.
Verified Customer
{
  "meta": {
    "api_request_id": "b4d5e6f7-g8h9-i0j1-k2l3-m4n5o6p7q8r9"
  },
  "response_type": "object",
  "data": {
    "id": "cus_1a2b3c4d5e6f7g8h9i0j1k2l3",
    "name": "Jane Smith",
    "type": "individual",
    "email": "jane.smith@example.com",
    "phone": "+14155551234",
    "external_id": "CUST-001",
    "address": {
      "address1": "456 Oak Street",
      "address2": "Apt 7B",
      "type": "residential",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102"
    },
    "compliance_profile": {
      "dob": "1985-03-15",
      "ssn": "***-**-1234"
    },
    "device": {
      "ip_address": "192.168.1.1"
    },
    "metadata": {
      "referral_source": "website",
      "customer_segment": "premium"
    },
    "status": "verified",
    "created_at": "2023-11-08T15:30:45Z",
    "updated_at": "2023-11-08T15:30:45Z"
  }
}
After creating a customer, you can optionally review the underlying score data. This is useful if you want to understand the risk of the customer or if they are flagged for manual review.

Learn more about the Review Endpoint [[future link]]

​
Use Bridge to generate a paykey

Straddle uses a new kind of payment token called a paykey to securely link bank accounts to customers. Paykeys are generated using our proprietary machine learning model, WALDO, which algorithmically matches customer profile data to account ownership details sourced directly from the bank. You can generate a paykey in two ways:
  1. Using a Plaid token from an existing integration
  2. With ‘raw’ bank account details
curl -X POST https://api.straddle.io/v1/bridge/plaid \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "{customer_id}",
    "plaid_token": "PLAID_PROCESSOR_TOKEN",
    "metadata": {
      "user_id": "12345"
    }
  }'
Replace {customer_id} with the actual customer ID and fill in the appropriate fields depending on the type of paykey you are generating. The API response will contain the paykey:
Paykey Response
{
  "meta": {
    "api_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "response_type": "paykey",
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "label": "John's Checking Account",
    "source": "bank_account",
    "institution_name": "Bank of America",
    "status": "active",
    "status_details": {
      "message": "Account successfully verified",
      "reason": "OK",
      "source": "system"
    },
    "expires_at": "2023-11-07T05:31:56Z",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "paykey": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "bank_data": {
      "routing_number": "123456789",
      "account_number": "****5678",
      "account_type": "checking"
    },
    "metadata": {
      "user_id": "user_9876543210"
    }
  }
}
In this example, the value of the paykey is vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D.

​
Create a Payment

Now that you have a paykey, you can send money to customers via payouts or collect money from them via charges: 
curl -X POST https://api.straddle.io/v1/charges \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paykey": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "description": "Test charge",
    "amount": 1000,
    "currency": "usd",
    "payment_date": "2023-06-01",
    "consent_type": "internet",
    "device": {
      "ip_address": "192.168.1.1"
    },
    "external_id": "charge_123",
    "config": {
      "balance_check": "required"
    },
    "metadata": {
      "order_id": "12345"
    }
  }'