---
name: straddle-integrate
description: >-
  This skill should be used when the user asks to "integrate Straddle",
  "create a customer", "create a charge", "create a payout", "connect a bank
  account", "set up Bridge", "onboard a merchant", "handle ACH returns",
  "check payment status", "use the Straddle SDK", or asks about Straddle
  entities, payment lifecycle, paykeys, webhooks, embed platforms, or the
  Straddle-Account-Id header. Guides integration decisions across all Straddle
  APIs and SDKs.

---

## Context gathering

Check the plugin's `.local.md` for `platform_type` and `sdk_language`. If either is not set, ask before proceeding:

1. **Platform type** (if missing): What are you building -- direct account, SaaS platform, or marketplace?
2. **SDK language** (if missing): Which language/SDK are you using -- TypeScript, Python, Go, Ruby, C#, or raw HTTP?

Use the SDK language to:
- Pass the `language` param when searching SDK docs (`search_docs` tool)
- Write code examples in the correct SDK
- Recommend the right package names and install commands

If the user has not completed initial setup, suggest running `/straddle-setup`.

### `Straddle-Account-Id` header rules

The header follows resource ownership. See <references/embed.md> for code examples.

| Operation | account | saas | marketplace |
|---|---|---|---|
| Customers / Paykeys | No header | Required (embedded account owns them) | No header (platform owns them) |
| Charges / Payouts | No header | Required | Required (attributes to seller) |
| Review / Decision | No header | Required (embedded account reviews) | No header (platform reviews) |
| Embed onboarding (steps 3-6) | N/A | Required (scoped to account being onboarded) | Required (scoped to account being onboarded) |
| Embed orgs + accounts (steps 1-2) | N/A | No header (platform-level) | No header (platform-level) |

### Behavioral rules by `platform_type`

**account:**
- Pay by Bank flow only. Embed is not applicable.
- Never include `Straddle-Account-Id`.

**saas:**
- Before making account-scoped calls, ask which embedded account the user is working with.
- Include `Straddle-Account-Id` header on all customer, paykey, payment, review, and onboarding (steps 3-6) calls.
- Push the hosted onboarding widget. API-based onboarding is a fallback.
- The embedded account reviews its own customers and paykeys.

**marketplace:**
- Customers and paykeys belong to the platform -- no header on those calls.
- Before making payment calls, ask which embedded account (seller) the payment is for.
- Include `Straddle-Account-Id` on charges, payouts, and onboarding (steps 3-6).
- Push the hosted onboarding widget.
- The platform reviews customers and paykeys directly.

## Tool routing

| Need | Tool | Use for |
|------|------|---------|
| Code execution | straddle API MCP | Run API calls, test methods, explore responses |
| SDK reference | `search_docs` MCP tool | Method signatures, parameters, response shapes, code examples. **Always pass `language` param.** |
| Product guides | product-docs skill | Payment guides, sandbox testing, compliance, ACH returns, risk scores. Searches docs.straddle.com via HTTP. |
| Terminal operations | Straddle CLI | Verify resources, test operations, inspect responses, debug API issues. See <references/cli.md> |

## Integration routing

| Building...                    | Reference                     | Covers                                                            |
| ------------------------------ | ----------------------------- | ----------------------------------------------------------------- |
| Payment flow                   | <references/pay-by-bank.md>   | Customer > Bridge > Paykey > Charge/Payout > Funding              |
| Platform / marketplace         | <references/embed.md>         | Organizations, accounts, onboarding, header rules by platform type |
| Entities and lifecycle         | <references/domain.md>        | Status machines, webhooks, ACH, identity, gotchas                 |
| SDK setup and code             | <references/sdk.md>           | All SDKs, TypeScript operations, Bridge Widget SDK, pagination, errors |
| CLI usage and output           | <references/cli.md>           | CLI command structure, output formats, data extraction, debugging         |
| MCP server setup               | <references/mcp-server.md>    | Connection methods, tool filtering, environments, production safety      |

Read the relevant reference file before answering any integration question or writing code.

## Doc search enforcement

Reference files contain stable structural and behavioral knowledge. Enumerated
factual lists (return codes, event names, numeric limits) have been replaced
with links to authoritative documentation pages.

When a reference file links to docs.straddle.com:
1. Search product docs by POSTing to `https://docs.straddle.com/mcp` with `{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_straddle_docs","arguments":{"query":"YOUR_QUERY"}},"id":1}` and header `Accept: application/json, text/event-stream`
2. If MCP search returns insufficient results, fetch the linked URL directly
3. MCP results and linked pages are authoritative -- they win on conflicts

**Documentation index:** https://docs.straddle.com/llms.txt -- complete sitemap
of all Straddle documentation pages with descriptions. Use as a fallback when
the search does not return the needed content.