Getting Started
Welcome! Follow the instructions below to learn how to start building with Straddle.
Get Sandbox Access
Visit straddle.io/sign-up
Enter your name and email
Define your use case:
Choose ‘Business’ if you’re building directly into Straddle
Choose ‘Platform’ if your software is enabling payments for other businesses
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:
Generate API Keys
In the dashboard, navigate to the API Keys section
Generate a new API key
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
In the dashboard, go to the Webhooks section
Add a new webhook endpoint URL
Select the events you want to receive
Save your webhook configuration
Start Building
Now that you’ve set up your account, let’s start integrating Straddle into your application.
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.
{
"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:
Using a Plaid token from an existing integration
With ‘raw’ bank account details
Use a Plaid Token
Use a Bank Account
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:
{
"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:
Create a Charge
Create a Payout
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"
}
}'