​
Getting Started

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

​
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

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:

Core ConceptsPay by Bank