Platform API Interactions

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.

The precise application of this rule varies by the type of operation and sometimes by your platform model (Marketplace vs. SaaS), as detailed below.

​

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

  • POST /v1/accounts
  • POST /v1/accounts//representatives
  • POST /v1/accounts//linked_bank_accounts

​

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:

• PATCH /v1/customers
• POST /v1/bridge/initialize

​

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:

• POST /v1/customers
• POST /v1/bridge/bank_account

​

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:

• POST /v1/charges
• POST /v1/payouts

​

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

​

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.