​
Introduction

This guide provides a detailed overview of the Straddle Embed onboarding process, focusing on the data model, object relationships, and implementation options. It is designed to help developers understand and implement the onboarding flow effectively.

​
Onboarding Options

Straddle offers two approaches for merchant onboarding:

API Flow

For sophisticated platforms requiring full control and customization.

Hosted Flow

For platforms seeking rapid market entry with pre-built components.

​
API Flow

The API flow is designed for platforms with specific requirements and the technical resources to implement a fully customized onboarding experience.
The API flow should only be used by sophisticated platforms with the necessary development resources and compliance expertise.

​
Data Model Overview

The onboarding process involves several interconnected objects:
These objects form a hierarchical structure, with Organizations at the top level.

​
Object Relationships

Organization

Contains one or more Accounts

Account

Belongs to an Organization

Representative

Belongs to an Account

Linked Bank Account

Belongs to an Account

​
Detailed Object Descriptions

​
Organizations

Organizations serve as the top-level container for Accounts. They allow for centralized management of multiple Accounts. Key properties:
  • id: Unique identifier
  • name: Organization name
  • external_id: Your system’s identifier (optional)

​
Accounts

Accounts represent individual merchants or businesses using Straddle services. Key properties:
  • id: Unique identifier
  • organization_id: Associated Organization
  • type: Account type (e.g., ‘business’)
  • status: Current account status
  • business_profile: Business details
  • capabilities: Enabled features

​
Representatives

Representatives are individuals associated with an Account, typically with legal authority or significant responsibility. Key properties:
  • id: Unique identifier
  • account_id: Associated Account
  • first_name: First name
  • last_name: Last name
  • email: Email address
  • phone: Phone number
  • relationship: Role within the organization

​
Linked Bank Accounts

Linked Bank Accounts connect external bank accounts to a Straddle Account for payment operations. Key properties:
  • id: Unique identifier
  • account_id: Associated Account
  • status: Current status
  • bank_account: Bank account details

​
Capabilities

Capabilities allow you define the types of payments (and their associated limits), customers, and consent mechanisms that can be used by an Account for payment operations. Key properties:
  • id: Unique identifier
  • account_id: Associated Account
  • status: Current status
  • settings 
"charges": {
   "enable": true,
   "max_amount": 1,
   "daily_amount": 1,
   "monthly_count": 1,
   "monthly_amount": 1
 },
 "payouts": {
   "enable": true,
   "max_amount": 1,
   "daily_amount": 1,
   "monthly_count": 1,
   "monthly_amount": 1
 },
 "internet": {
   "enable": true
 },
 "individuals": {
   "enable": true
 },
 "businesses": {
   "enable": true
 },
 "signed_agreement": {
   "enable": true
 }
}

​
API Onboarding Flow

1

Create Organization

Use the POST /v1/organizations endpoint
2

Create Account

Use the POST /v1/accounts endpoint, referencing the Organization
3

Add Representative

Use the POST /v1/representatives endpoint, referencing the Account
4

Link Bank Account

Use the POST /v1/linked_bank_accounts endpoint, referencing the Account
5

Request Capabilities

Use the POST /v1/capability_requests endpoint, referencing the Account
6

Initiate Onboarding

Use the POST /v1/accounts/{account_id}/onboard endpoint

​
API Considerations

  • Use the Straddle-Account-Id header for multi-tenant operations
  • Implement proper error handling for each API call
  • Utilize webhooks for asynchronous updates on onboarding status changes
Refer to the API Reference for detailed endpoint specifications and request/response formats.

​
Hosted Flow

For platforms looking to go to market quickly, Straddle offers a hosted flow with pre-built form components. This solution provides:
  • Rapid implementation
  • Compliance with data collection requirements
  • Reduced development overhead

​
Implementing the Hosted Flow

  1. Obtain the Straddle Embed script from your dashboard
  2. Include the script in your application
  3. Initialize the Straddle Embed component with your configuration
  4. Handle the callback with the onboarding result

​
Compliance Considerations

You don’t have to worry about onboarding compliance, KYC, AML, or any other regulations. Straddle handles all compliance requirements for you.
Seriously.

​
Testing and Sandbox Environment

Straddle provides a sandbox environment for testing your integration:
  • Use test API keys for all sandbox operations
  • Simulate various onboarding scenarios and edge cases
  • Test webhook integrations with simulated events
Thoroughly test your integration in the sandbox environment before going live.

​
Going Live

Once you’ve completed testing and are ready to go live, follow these steps:
1

Review and Update

Review and update your integration based on sandbox testing results.
2

Obtain Production Keys

Obtain production API keys from the Straddle dashboard.
3

Update Integration

Update your integration to use production endpoints and keys.
4

Phased Rollout

Implement a phased rollout to minimize potential issues.
5

Monitor Closely

Monitor your integration closely during the initial live period.

​
Support and Resources

For additional assistance and resources: