> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox Environment Setup and Simulation Endpoints

> Set up Lead's sandbox environment, advance ACH and wire transfers using simulation endpoints, and validate your integration before go-live.

Lead's sandbox is an isolated test environment where you can build and validate your integration without moving real money. Every call you make hits real API infrastructure — the only difference is that transactions are simulated and no funds settle on actual networks.\\

## Access and Credentials

Your Technical Account Manager provides sandbox credentials — a client\_id and client\_secret — during kickoff. API and SFTP credentials are separate, and both are separate from your production credentials.

|             | **Sandbox**                                                    | **Production**                                 |
| ----------- | -------------------------------------------------------------- | ---------------------------------------------- |
| API base    | [https://api.sandbox.lead.bank](https://api.sandbox.lead.bank) | [https://api.lead.bank](https://api.lead.bank) |
| SFTP host   | [sftp.sandbox.lead.bank](http://sftp.sandbox.lead.bank)        | [sftp.lead.bank](http://sftp.lead.bank)        |
| Port        | 22                                                             | 22                                             |
| Credentials | Provided at kickoff                                            | Issued after go-live approval                  |
| Real money  | No                                                             | Yes                                            |

<Note>
  **No Credentials?**

  If you do not have credentials, contact your Technical Account Manager.
</Note>

## Set Up Your Integration

Lead supports three integration paths. Your sandbox setup covers whichever paths apply to your program — most partners use a hybrid approach of API and file.

### **API Only**

If your program uses APIs exclusively, sandbox setup requires:

1. Lead issues your `client_id` and `client_secret` for the sandbox API.
2. You register your webhook endpoint URL with your Technical Account Manager.
3. You configure your IP allowlist with your Technical Account Manager.

[→ Start with the Quickstart: Make Your First Payment API Call](/get-started/quickstart/make-your-first-payment-api-call)

### File Only (SFTP)

If your program uses SFTP file delivery exclusively, sandbox setup requires:

1. Generate an SSH keypair: `ssh-keygen -t ed25519 -C "lead-integration" -f lead_sftp_key`
2. Send your public key to your Implementation Manager as plain text.
3. Verify Lead's sandbox host fingerprint: `ssh-keyscan sftp.sandbox.lead.bank 2>&1 | ssh-keygen -lf -`
   * Expected: `2048 SHA256:rCdk4LeHvxn5G3j7VDJvqH6oEMh844E7sHxoaxih2dE sftp.sandbox.lead.bank (RSA)`
4. Add Lead's key to your known hosts: `ssh-keyscan sftp.sandbox.lead.bank >> ~/.ssh/known_hosts`
5. Connect: `sftp -v -i ~/.ssh/your_key username@sftp.sandbox.lead.bank`

Once connected, your SFTP directory follows this structure:

* **Read/Write**: Folders where you are the submitter (customer, accounts, balances, transactions, etc.)
* **Read Only**: Folders where Lead is the submitter (bank-account-reports, ach/incoming, etc.)

The full folder structure and file naming conventions are in [File Delivery](/file-integrations/file-delivery/overview).

### Hybrid (Most Common)

Most programs use APIs for real-time money movement and entity onboarding, and SFTP files for daily reporting and reconciliation. Complete both the API and file setup steps above.

## What is Simulated

All payment rails are available in sandbox, but no transactions submit to real networks. ACH entries do not go to the Fed, wires do not move through Fedwire or Swift, and FedNow payments do not reach real receiving institutions. SFTP files are validated against your schema but do not trigger real reconciliation or settlement.

Because sandbox transactions do not follow real network timing, Lead provides simulation endpoints that let you advance a transfer through its lifecycle states manually. These endpoints exist only in sandbox — they return 404 in production.

| Action                                     | Endpoint                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------- |
| Advance an ACH through states              | `POST /v1/simulate/ach/{ach_id}/advance`                                  |
| Trigger an inbound ACH                     | `POST /v1/simulate/ach/incoming_ach`                                      |
| Trigger an incoming ACH return             | `POST /v1/simulate/ach/{ach_id}/incoming_return`                          |
| Advance a wire through states              | `POST /v1/simulate/wires/{wire_id}/advance`                               |
| Trigger an inbound wire                    | `POST /v1/simulate/wires/incoming`                                        |
| Trigger an incoming wire return            | `POST /v1/simulate/wires/{wire_id}/incoming_return`                       |
| Trigger an inbound instant payment         | `POST /v1/simulate/instant_payments/incoming`                             |
| Trigger an incoming instant payment return | `POST /v1/simulate/instant_payments/{instant_payment_id}/incoming_return` |
| Advance a funding (lending)                | `POST /v0/fundings/{id}/advance`                                          |

## Key Differences From Production

<AccordionGroup>
  <Accordion title="ACH transactions require manual advancement. Instant payments do not.">
    In production, ACH transfers progress through their lifecycle automatically based on network timing (for example, `created → submitted → posted`). In sandbox, ACH transfers remain in the `created` state until you explicitly advance them using the simulation endpoints.

    Use `POST /v1/simulate/ach/{ach_id}/advance` and the other simulation endpoints to move ACH transfers through different states and test your webhook handling, status polling, and reconciliation logic.

    **Instant payments behave differently.** Their statuses advance automatically in sandbox, so no manual advancement is required.
  </Accordion>

  <Accordion title="International wires reach accepted but do not settle automatically. ">
    Payments move to accepted status but do not advance further without manual simulation. Use `POST /v1/simulate/wires/{wire_id}/advance` to move them through the remaining states.
  </Accordion>

  <Accordion title="KYC and OFAC are not enforced. ">
    Sandbox accepts placeholder screening results — you can pass "result": "approved" and "result": "clear" without running a real identity check. In production, your screening results must reflect actual verification.
  </Accordion>

  <Accordion title="Rate limits are looser. ">
    Sandbox has higher per-minute request limits than production to support active integration work. Production limits are set per program and defined in your contract.
  </Accordion>

  <Accordion title="Simulation endpoints return 404 in production. ">
    Any path under `/v1/simulate` (and the lending funding advance endpoint) is sandbox-only. Do not call these endpoints in production — they return `404`.
  </Accordion>

  <Accordion title="SFTP file validation runs but does not trigger reconciliation.">
    Files you submit in sandbox are validated against your schema and will surface errors the same way production does — but they do not feed real reconciliation or accounting processes.
  </Accordion>
</AccordionGroup>

## Data Persistence and Resets

Entities, accounts, and account numbers you create persist until you request a reset. If you need to reset your sandbox environment — for example, before a new test phase or to clear conflicting test data — contact your Technical Account Manager.

## What to Test Before Go-Live

Before go-live, complete testing for each of the following:

* Create entities, including KYC and OFAC fields
* Create accounts and account numbers
* Send and receive payments for each contracted rail
* Trigger and handle returns and reversals
* Receive and process webhook events
* Submit SFTP files and confirm schema validation passes
* Handle common error responses (401, 403, 409, 422)

The specific testing milestones required before go-live are covered in [Program Launch](/get-started/program-launch).