You can view this page on our documentation site here.
This guide will help you get started with Straddle, from setting up your account to making your first transaction. Follow these steps to quickly integrate Straddle into your application.
The Basics
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 dashboardAn 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
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.
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": "[email protected]",
"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": "[email protected]",
"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"
}
} Note: 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.
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
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"
}
}'
Use a Bank Account
curl -X POST https://api.straddle.io/v1/bridge/bank_account \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "{customer_id}",
"routing_number": "110000000",
"account_number": "000123456789",
"account_type": "checking",
"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:
Create a Charge
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"
}
}'
Create a Payout
curl -X POST https://api.straddle.io/v1/payouts \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"paykey": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"description": "Test payout",
"amount": 1000,
"currency": "usd",
"payment_date": "2023-06-01",
"device": {
"ip_address": "192.168.1.1"
},
"external_id": "payout_123",
"metadata": {
"refund_id": "12345"
}
}'