Platform API Interactions
Learn when and how to use the Straddle-Account-Id header for API requests based on your platform type (Marketplace or SaaS) and the operation being performed.
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: No Header Used
When your platform is performing administrative actions on resources it directly manages or creates for its ecosystem. This typically includes creating the foundational Account entities for your users or managing resources directly tied to your platform’s users if they are not further sub-divided in Straddle.
General Rule: Header Used
General Rule: Header Used
When your platform is performing actions specifically scoped to one of its individual embedded accounts. This is particularly true when the action involves operations that are inherently the responsibility or activity of that embedded account, such as creating a customer for a specific SaaS client or initiating/receiving payments.
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-Idheader 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-Idheader 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 / Resource | Platform Type | Header Used? | Why? |
|---|---|---|---|
| Create Account | All | No | Platform is administratively creating a managed account. |
| Create Representative for an Account | All | No | Platform is administratively managing resources for its accounts. |
| Create Linked Bank Account for an Account | All | No | Platform is administratively managing resources for its accounts. |
| Create Customer | Marketplace | No | The customer is a direct user of the Marketplace platform. |
| Create Customer | SaaS | Yes | The customer belongs to an embedded client account; the SaaS platform acts on behalf of that client account. |
| Create Paykey (Bridge API) | Marketplace | No | The Paykey is for a direct customer of the Marketplace platform. |
| Create Paykey (Bridge API) | SaaS | Yes | The Paykey is for a customer of an embedded client account; the SaaS platform acts on behalf of that client account. |
| Create Charge (Payment) | All | Yes | All payments are actions of a specific embedded account. Header ensures correct attribution and compliance. |
| Create Payout (Payment) | All | Yes | All 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.