> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard merchants with Straddle Embed

> Build a custom merchant onboarding flow with Straddle Embed APIs, including KYB verification, representative collection, and bank account linking.

## 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:

<CardGroup cols={2}>
  <Card title="API Flow" icon="code">
    For sophisticated platforms requiring full control and customization.
  </Card>

  <Card title="Hosted Flow" icon="globe">
    For platforms seeking rapid market entry with pre-built components.
  </Card>
</CardGroup>

## API Flow

The API flow is designed for platforms with specific requirements and the technical resources to implement a fully customized onboarding experience.

<Warning>
  The API flow should only be used by sophisticated platforms with the necessary development resources and compliance expertise.
</Warning>

### Data Model Overview

The onboarding process involves several interconnected objects:

<AccordionGroup>
  <Accordion title="Organizations" icon="building">
    Top-level entities that can contain multiple accounts. Organizations allow for centralized management and grouping of related accounts.
  </Accordion>

  <Accordion title="Accounts" icon="file-contract">
    Represent individual merchants or businesses using Straddle services. Each account belongs to an organization and can have multiple representatives and linked bank accounts.
  </Accordion>

  <Accordion title="Representatives" icon="person">
    Individuals associated with an account, typically with legal authority or significant responsibility within the business. Each account must have at least one representative.
  </Accordion>

  <Accordion title="Linked Bank Accounts" icon="building-columns">
    External bank accounts connected to a Straddle account for payment operations. These are essential for facilitating transactions and fund transfers.
  </Accordion>

  <Accordion title="Capabilities" defaultOpen={false} icon="bell-concierge">
    Manage Straddle features and payment settings for an account. &#x20;
  </Accordion>
</AccordionGroup>

<Note>
  These objects form a hierarchical structure, with Organizations at the top level.
</Note>

### Object Relationships

<CardGroup cols={2}>
  <Card title="Organization" icon="building">
    Contains one or more Accounts
  </Card>

  <Card title="Account" icon="file-contract">
    Belongs to an Organization
  </Card>

  <Card title="Representative" icon="person">
    Belongs to an Account
  </Card>

  <Card title="Linked Bank Account" icon="building-columns">
    Belongs to an Account
  </Card>
</CardGroup>

### 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`

```json theme={null}
"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

<Steps>
  <Step title="Create Organization">
    Use the `POST /v1/organizations` endpoint
  </Step>

  <Step title="Create Account">
    Use the `POST /v1/accounts` endpoint, referencing the Organization
  </Step>

  <Step title="Add Representative">
    Use the `POST /v1/representatives` endpoint, referencing the Account
  </Step>

  <Step title="Link Bank Account">
    Use the `POST /v1/linked_bank_accounts` endpoint, referencing the Account
  </Step>

  <Step title="Request Capabilities">
    Use the `POST /v1/capability_requests` endpoint, referencing the Account
  </Step>

  <Step title="Initiate Onboarding">
    Use the `POST /v1/accounts/{account_id}/onboard` endpoint
  </Step>
</Steps>

### 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

<Tip>
  Refer to the [API Reference](/api-reference) for detailed endpoint specifications and request/response formats.
</Tip>

## 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.

<Warning>
  Seriously.
</Warning>

## 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

<Tip>
  Thoroughly test your integration in the sandbox environment before going live.
</Tip>

## Going Live

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

<Steps>
  <Step title="Review and Update">
    Review and update your integration based on sandbox testing results.
  </Step>

  <Step title="Obtain Production Keys">
    Obtain production API keys from the Straddle dashboard.
  </Step>

  <Step title="Update Integration">
    Update your integration to use production endpoints and keys.
  </Step>

  <Step title="Phased Rollout">
    Implement a phased rollout to minimize potential issues.
  </Step>

  <Step title="Monitor Closely">
    Monitor your integration closely during the initial live period.
  </Step>
</Steps>

## Support and Resources

For additional assistance and resources:

<AccordionGroup>
  <Accordion title="Technical Support" icon="headset">
    For integration assistance, contact [support@straddle.com](mailto:support@straddle.com).
  </Accordion>

  <Accordion title="Documentation and Updates" icon="rss">
    Access the latest technical information:

    * [API Documentation](https://straddle.com/docs)

    * [Changelog](https://straddle.com/changelog)

    * [Developer Blog](https://straddle.com/blog)
  </Accordion>
</AccordionGroup>