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

# Build your first integration

> Use the Straddle Wizard to plan, build, and test Pay by Bank in your application.

Add Straddle to your application with your coding agent. The Wizard guides the work from a plan you review to code changes and recorded sandbox test results.

## Before you begin

Prepare the following:

* An application repository and Node.js 22.18 or later.
* Claude Code, Codex, or Cursor. For Auto mode, install and sign in to the client's command-line tool: `claude`, `codex`, or `cursor-agent`.
* A sandbox API key from the [Straddle Dashboard](https://dashboard.straddle.com), available as `STRADDLE_API_KEY` in the environment that starts your agent.

Use your secret manager or shell configuration to supply the API key. The [plugin installation guide](/developer-tools/agent-plugin/install) covers client setup and connection checks.

## Build and verify

<Steps>
  <Step title="Open your application repository">
    In a terminal at the repository root, select sandbox:

    ```bash theme={null}
    export STRADDLE_ENVIRONMENT=sandbox
    ```

    If you set `STRADDLE_BASE_URL`, use `https://sandbox.straddle.com`. The Wizard reports conflicting environment settings before the request steps start.
  </Step>

  <Step title="Start the Wizard">
    Launch the guided integration:

    ```bash theme={null}
    npx @straddlecom/wizard@latest
    ```

    Confirm the detected language and framework. Choose charges, payouts, or both; your integration type; an SDK; and a notification path. Select **Not decided yet** for a choice you want to work through with the agent.

    Choose your client and **Auto** to let the Wizard start it. In **Manual**, follow the displayed setup steps and paste the Wizard's generated message into your agent. Review and accept any plugin download or installation needed for the run.
  </Step>

  <Step title="Review the integration plan">
    The agent checks the project and writes `straddle-integration-plan.md`. Give it the application context it asks for. For a charge integration, adapt this request in the agent session:

    <Prompt description="Describe a Pay by Bank integration" actions={["copy"]}>
      Add Pay by Bank to this application's checkout. Follow the Straddle Wizard program for this repository. Identify how the app stores customers, collects payments, and receives payment updates. Ask me to resolve the integration type and bank connection method before writing the plan. Show the files you propose to change and the sandbox scenarios you will test.
    </Prompt>

    Read the plan's application changes, account rules, and test scenarios. Approve the plan when it matches the integration you want. If the repository already uses another payment provider, the Wizard also includes a migration step.
  </Step>

  <Step title="Build and test in sandbox">
    The agent implements the approved plan, then runs its test workflow. Review each sandbox write preview, including the environment, acting account, operation, and payload, before approving it.

    Complete any application interaction the agent needs, such as connecting a bank through the Bridge widget. The agent records the checks it ran and any scenario that still needs attention in `straddle-test-evidence.md`.
  </Step>

  <Step title="Read the evidence and next steps">
    Inspect the saved run:

    ```bash theme={null}
    npx @straddlecom/wizard@latest status
    ```

    Open `straddle-integration-report.md` for the code changes and `straddle-test-evidence.md` for the results. A finished Test step has `Status: complete` for the current approved plan. Review the latest run's scenario table and its `live-observed` evidence for sandbox behavior.

    Read `straddle-go-live-report.md` for the production readiness review and any remaining gaps. Review the changed files and the agent's **Verify before merging** checklist before merging your integration.
  </Step>
</Steps>

## Continue an unfinished run

After resolving a missing setting, unanswered question, or failed check, continue from the same repository:

```bash theme={null}
npx @straddlecom/wizard@latest resume
```

The Wizard reads the plan and reports to find the first unfinished step. See [Run and resume an integration](/developer-tools/wizard/integrate) for completion states, Manual mode, and finishing after sandbox testing.


## Related topics

- [Build your Straddle integration with AI](/developer-tools/overview.md)
- [Choose your tools](/developer-tools/routing.md)
- [Set up a project with the Wizard](/developer-tools/wizard/overview.md)
- [Use Straddle skills](/developer-tools/skills/use-kit.md)
- [Run and resume an integration](/developer-tools/wizard/integrate.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.