The Straddle API provides powerful tools for platforms—be it Marketplaces or SaaS solutions—to embed financial services for their users. A key aspect of interacting with the Straddle API as a platform is understanding the use of the Straddle-Account-Id HTTP header. This header is crucial for correctly scoping API operations to specific embedded accounts that your platform manages. This guide explains when to use, and when not to use, the Straddle-Account-Id header, ensuring your integration is both functional and compliant.

​
Core Concept: Acting on Behalf of an Embedded Account

When your platform interacts with the Straddle API, it can do so either as itself or on behalf of one of its embedded accounts (your users, merchants, or clients who are onboarded onto Straddle through your platform). The Straddle-Account-Id header is the mechanism you use to tell Straddle that a particular API request is being made on behalf of a specific embedded account. The value for this header should be the unique ID of the embedded account.

General Rule: No Header Used

General Rule: Header Used

The precise application of this rule varies by the type of operation and sometimes by your platform model (Marketplace vs. SaaS), as detailed below.
Consistency is Key Your platform operates either as a Marketplace or a SaaS model within Straddle. Once you’ve identified your platform type and understood its corresponding header logic, Straddle-Account-Id usage will apply consistently across your Straddle integration.

​
Specific Scenarios for Header Usage

Let’s break down header usage for common operations.

​
1. Managing Accounts & Core Account Resources

This category includes creating Straddle Account entities for your users, and then adding essential resources to these accounts, such as Representatives or Linked Bank Accounts.
  • Platform Types: All (Marketplaces and SaaS)
  • Straddle-Account-Id: NOT USED
  • Reasoning: When your platform creates a new Straddle Account for one of your users (e.g., a new merchant signs up to your marketplace, or a new client subscribes to your SaaS product), your platform is the actor performing this administrative setup. Similarly, when adding initial resources like legal representatives or linking bank accounts to that newly defined Straddle Account, your platform is still acting in its primary capacity as the manager and facilitator of these accounts within the Straddle ecosystem. These are considered foundational actions by the platform itself. Conceptual API Calls (Refer to specific API documentation for exact endpoint paths):

​
2. Managing Customers and Paykeys (Bridge API)

Creating Customer records and generating Paykeys (via the Bridge API) for them shows a key distinction based on platform type.

​
Marketplace Platforms

  • Straddle-Account-Id: NOT USED
  • Reasoning: In a marketplace model, the end-users (buyers or sellers transacting on the marketplace) are typically considered direct customers of the marketplace itself. When the marketplace platform creates a Customer record in Straddle for these users, or generates a Paykey for them, it is acting on its own behalf to manage its direct user base.
Conceptual API Calls:

​
SaaS Platforms

  • Straddle-Account-Id: IS USED
  • The header must contain the ID of the SaaS platform’s client (the specific embedded Straddle Account on whose behalf the customer is being created).
  • Reasoning: SaaS platforms often provide services to other businesses (their “accounts” or “tenants”). The end-users are customers of these client businesses. When the SaaS platform facilitates the creation of a Customer record or a Paykey in Straddle, it does so on behalf of one of its embedded client accounts. The Straddle-Account-Id header specifies which client account this new customer or paykey belongs to.
Conceptual API Calls:

​
3. Processing Payments (Charges and Payouts)

This is the most critical scenario for header usage and applies universally.
  • Platform Types: All (Marketplaces and SaaS)
  • Straddle-Account-Id: ALWAYS USED
  • The header must contain the ID of the embedded Straddle Account that is initiating (for payouts) or receiving (as the beneficiary of charges) the payment.
  • Reasoning: This is a fundamental part of Straddle’s design for compliance, risk management, and clear attribution of financial activity. All payment transactions (creating Charges or Payouts) are legally and financially the actions of a specific embedded account. The platform facilitates these transactions but is not a party in the flow of funds. By requiring the Straddle-Account-Id header for all payment operations, Straddle ensures that:
    • The correct embedded account is debited or credited.
    • Financial reporting and reconciliation are accurate for each embedded account.
    • The platform itself remains operationally separate from the direct movement of funds, which is often a regulatory requirement.
Conceptual API Calls:

​
Quick Reference Table

Action / ResourcePlatform TypeHeader Used?Why?
Create AccountAllNoPlatform is administratively creating a managed account.
Create Representative for an AccountAllNoPlatform is administratively managing resources for its accounts.
Create Linked Bank Account for an AccountAllNoPlatform is administratively managing resources for its accounts.
Create CustomerMarketplaceNoThe customer is a direct user of the Marketplace platform.
Create CustomerSaaSYesThe customer belongs to an embedded client account; the SaaS platform acts on behalf of that client account.
Create Paykey (Bridge API)MarketplaceNoThe Paykey is for a direct customer of the Marketplace platform.
Create Paykey (Bridge API)SaaSYesThe Paykey is for a customer of an embedded client account; the SaaS platform acts on behalf of that client account.
Create Charge (Payment)AllYesAll payments are actions of a specific embedded account. Header ensures correct attribution and compliance.
Create Payout (Payment)AllYesAll payments are actions of a specific embedded account. Header ensures correct attribution and compliance.

​
Important Reminders

Correct ID Format

Ensure the ID used in the Straddle-Account-Id header is associated with the correct client.

Path Parameters vs. Header

Be mindful of the difference between an {account_id} in an API endpoint’s path (which usually identifies the resource being acted upon) and the Straddle-Account-Id header (which identifies the acting embedded account, if the platform is acting on its behalf).

Impact of Incorrect Usage

Using the header incorrectly or omitting it when required can lead to misattributed resources, API errors (like 401 Unauthorized or 403 Forbidden), or unintended operational consequences.

​
Conclusion

Mastering the use of the Straddle-Account-Id header is essential for platforms integrating with Straddle Embed. It allows for precise control over operations performed on behalf of your embedded accounts, ensures correct financial attribution, and helps maintain a compliant and secure environment. Always refer to the specific endpoint documentation and consider your platform model (Marketplace or SaaS) and the nature of the operation to determine the appropriate use of this header.