Testing in sandbox

Sandbox is a full, live copy of the v3 API. Same endpoints, same webhooks, same routing logic, pointed at the aggregators’ own sandbox banks (Finicity FinBank, MX Bank) plus the FDE Ledgersync Bank, not synthetic fixtures. You link a real test bank, sign in with test credentials, and watch real accounts, transactions, and statements flow back exactly as they will in production.

Sandbox uses https://api-sandbox.ledgersyncappv2.com/v3 and an sk_test_... key. Live traffic never touches sandbox and vice-versa. See Authentication for how to get and send your key.

What sandbox gives you

The real routing engine. When you initiate a connection, v3 picks the source (Finicity, MX, or FDE) from the institution catalog, server-side, just like production. You never pass a source.
Real widgets. Finicity and MX open their own aggregator sandbox widgets. FDE opens the LedgerSync-hosted connect page. You still never see or transmit credentials.
Real webhooks. Every state transition publishes a real Kafka event and fires the matching webhook, HMAC-signed exactly like production.

Sandbox institution IDs

Pass one of these as institution_id on POST /v3/clients/{id}/connections. v3 resolves the source from the catalog row, you don’t pass a source field.

FinBank (Finicity)

ins_3c97c5da90335a04Finicity’s sandbox bank. Widget renders on connect2.finicity.com (Finicity institutionId 8906).

MX Bank (MX)

ins_73df5077e90a1b63MX’s sandbox bank (mxbank). Hands off to MX Connect’s sandbox on int-widgets.moneydesktop.com. Unlimited test aggregations.

Ledgersync Bank (FDE)

ins_a7397a8d0656e1b7FDE’s credential-based extractor. Returns a LedgerSync-hosted connect page (not an aggregator widget); accepts any login, offers one account. The only sandbox bank that returns check images.

Prove your integration in 6 calls: (1) mint an sk_test_ key, (2) register a webhook endpoint, (3) POST /v3/clients to create a test end-user, (4) POST /v3/clients/{id}/connections with institution_id=ins_3c97c5da90335a04, open the widget, sign in customer1 / go, (5) confirm connection.active lands, then GET /v3/accounts (Checking 1111 + Savings 2222), (6) repeat step 4 with ins_73df5077e90a1b63 and mxuser / correct to prove the MX path.

The 60-second smoke test (FinBank)

FinBank is Finicity’s sandbox bank. It flips to active immediately, with no MFA, and auto-populates accounts, transactions, and statements. It is the fastest way to prove your integration works end-to-end.

Find FinBank

Search the catalog and pick the row named exactly FinBank — the sandbox has several FinBank * variants (see the table below) and only the plain one is the no-friction path.

curl "https://api-sandbox.ledgersyncappv2.com/v3/institutions?q=FinBank" \
  -H "Authorization: Bearer sk_test_..."

Grab the id (ins_3c97c5da90335a04) from the row whose name is FinBank.

Initiate the connection

Point it at a client you’ve created (see Connect a bank for creating clients).

Initiate

curl -X POST "https://api-sandbox.ledgersyncappv2.com/v3/clients/cli_.../connections" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"institution_id":"ins_3c97c5da90335a04"}'

You get 202 Accepted with an operation_id. Poll it until status is succeeded, then read result.connection.action.widget_url.

Open the widget and sign in

Open widget_url in a browser, pick FinBank, and sign in with the sandbox credentials:

Field	Value
Banking Userid	`demo`
Banking Password	`go`

No MFA, it links right away. (customer1 / go also works and returns known balances, see the table below.)

Watch it go active

The connection flips to active and connection.active fires on your webhook. The payload carries the canonical connection id (con_FINICITY_<bankAccountId>, e.g. con_FINICITY_41294). Store that, the placeholder con_<uuid> you saw during pending only works for the widget step.

Read the data

Accounts, transactions, and statements are already populated. Reads are Client-scoped, so pass client_id every time.

Accounts

curl "https://api-sandbox.ledgersyncappv2.com/v3/accounts?client_id=cli_...&connection_id=con_FINICITY_41294" \
  -H "Authorization: Bearer sk_test_..."

Transaction ids follow the same shape: txn_FINICITY_..., txn_MX_..., or txn_FDE_....

If you saw connection.active, a canonical con_FINICITY_... id, and non-empty accounts, your happy path is wired correctly. Now exercise the edge cases.

Finicity — FinBank credentials

Public sandbox logins published by Mastercard Open Banking. Sign in on the widget URL for ins_3c97c5da90335a04. The username picks the scenario; the password is go unless noted.

Scenario	Username	Password	MFA	Expected result
Happy path (verified)	`customer1`	`go`	none	Checking 1111 ≈ $605.06 / 8 txns + Savings 2222 ≈$ 605.06 / 8 txns (Walmart fixtures).
Happy path (legacy demo)	`demo`	`go`	none	Checking + Savings, small synthetic history.
Wider shape	`customer2`	`go`	none	Checking + Savings + Credit Card — multi-type serialization.
Text MFA	`tfa_text`	`go`	text prompt · answer `go`	Drives `connection.requires_action` → `connection.active`.
OTP text MFA	`customer3`	`go`	OTP challenge · answer `999999`	Meant to test the failure path with a wrong code. As of September 2026 no challenge appears: the login links directly, so the wrong-code path cannot be reproduced.
Image MFA	`tfa_image`	`go`	image challenge · answer `go`	Exercises the image-MFA UI path.
Captcha	`tfa_captcha`	`go`	captcha · answer any non-empty	Any non-empty value passes.
Invalid credentials	`customer1`	`bad`	n/a	The widget rejects the sign-in and keeps the user on the form (as of September 2026 it shows “Technical issue (130)”). No connection is created and no webhook fires.
Locked institution	`locked`	`go`	n/a	Links normally in the current sandbox: the connection goes `active` with no error, so no lock is simulated.

FinBank Profiles A–H — account-shape coverage

For the FinBank Profiles - A / - B institutions, the password picks a profile (use the same value as the OAuth username too). Exercises every serializer path; investment coverage is intentionally thin, link a real brokerage for that.

Password (and OAuth username)	Account shapes returned
`profile_02`	Savings, IRA, 401k, Credit Card
`profile_03`	Checking, Savings, Credit Card
`profile_04`	Checking + Money Market + Mortgage
`profile_05`	Checking, Savings, Credit Card, Auto Loan
`profile_06`	Checking, Savings, Brokerage, Credit Card
`profile_07`	Checking + Student Loan + Line of Credit
`profile_08`	Multiple Checking accounts
`profile_09`	Multiple Credit Cards

Other FinBank variants — edge-case banks

The catalog also surfaces several letter- and label-suffixed FinBank entries. Each one is Mastercard Open Banking’s dedicated sandbox bank for a specific edge case, pick a variant when you want to harden against that case, not for a smoke test. Search for each by name and initiate exactly as above.

Catalog name	Purpose
FinBank Profiles - A	Account-shape coverage. The password picks a profile (`profile_02`…`profile_09`) that returns a specific mix of Checking, Savings, IRA, 401k, Credit Card, Brokerage, Mortgage, Auto Loan, etc.
FinBank Profiles - B	Second profile-driven institution — same `profile_*` password mechanism as Profiles - A, distinct catalog row.
FinBank M	MFA-flavoured variant (the “M” suffix). Use alongside the text / image / OTP MFA usernames to exercise the `connection.requires_action` → resume path.
FinBank O	Alternate-aggregation variant. Use when you need a non-default Finicity routing for parsing or fixture-level regression coverage.
FinBank C	Captcha-flavoured variant. Pair with the `tfa_captcha` username to drive the captcha-MFA path in the widget.
FinBank P	Personal-banking variant. Use it to keep a consumer-shaped connection isolated from your business test connections.
FinBank OAuth	OAuth sign-in flow. The widget redirects to a Finicity-hosted bank sign-in instead of taking credentials inline. The catalog row has `oauth_supported = true`.
FinBank Decertified	Decertified-institution failure path, meant to drive `connection.failed` with a decertification-style `last_error`. As of September 2026 it links normally instead: `demo` / `go` goes `active` and sends `connection.active`.
FinBank Billable	Billable-statements variant. Verify your code handles the statements path end-to-end, including whatever your billing/usage accounting needs to count.

MX sandbox bank (mxbank)

MX is the alternate aggregator, it catches institutions Finicity misses, and v3 routes to it automatically when the catalog says so. Sign in on the widget URL for ins_73df5077e90a1b63. The username is always mxuser; the password is the dial that picks the scenario. Ids come back source-tagged: con_MX_<id> (e.g. con_MX_1224), acc_MX_..., txn_MX_....

Scenario	Username	Password	Result
Happy path (verified)	`mxuser`	`correct`	Checking $495,565.18 / 49 txns, Savings, Credit Card, Loan, Mortgage, Investment.
Any non-keyword password	`mxuser`	`<anything else>`	Connects normally. Use any string other than the keywords below.
Text MFA	`mxuser`	`challenge`	Standard text MFA · answer `correct` (any other answer fails).
Pick-one MFA	`mxuser`	`options`	`OPTIONS` selection challenge · answer `correct`.
Image MFA	`mxuser`	`image`	`IMAGE` selection challenge · answer `correct`.
Bad request	`mxuser`	`BAD_REQUEST`	400 missing fields. `connection_status = FAILED`.
Invalid credentials	`mxuser`	`UNAUTHORIZED`	401 invalid credentials. `connection_status = DENIED`.
Invalid login	`mxuser`	`INVALID`	401 login/password invalid. `connection_status = DENIED`.
Locked user	`mxuser`	`LOCKED`	401 user is locked. `connection_status = LOCKED`.
Disabled user	`mxuser`	`DISABLED`	401 locked-account variant. `connection_status = DENIED`.
Server error	`mxuser`	`SERVER_ERROR`	500 institution-side error. `connection_status = FAILED`. As of September 2026 the widget shows “Unable to connect” and no connection is created.
Service unavailable	`mxuser`	`UNAVAILABLE`	503 service unavailable. `connection_status = FAILED`. As of September 2026 the widget stays on “Loading” and no connection is created.

What v3 reports for each MX connection_status above: DENIED reads requires_action with last_error.code credentials_invalid; LOCKED reads requires_action with account_locked_by_institution and is_user_actionable: false (the user acts at the bank, not in the widget); FAILED maps to failed with institution_unavailable, but neither SERVER_ERROR nor UNAVAILABLE creates a connection in the current sandbox, so that case cannot be seen here. These are the statuses GET /v3/connections/{id} reports. A first link that ends in one of them is announced by a connection.* webhook carrying the canonical con_MX_... id, shortly after the user submits the widget (6 to 20 seconds in September 2026 tests). Before September 23, 2026 only the initiate event under the placeholder id fired, so a first link that did not pass through MFA was not named by a webhook until its status next changed.

Card terms and masks in sandbox

The sandbox banks publish very little credit data, so an empty liabilities on a sandbox card is expected, not a bug:

FinBank credit cards carry no card terms. Use the FinBank line of credit to see a populated object: it carries available_credit, statement_balance, minimum_payment and payment_due_date (no credit_limit). The FinBank auto loan and mortgage carry a minimum_payment only.
The MX Bank credit card carries available_credit (3000) and a fixed payment_due_date of 2021-05-07; it reports no credit_limit or minimum_payment. The MX Bank loan and mortgage carry a fixed 2021-05-12 due date. A due date in the past is the bank’s last published cycle, not an overdue payment.
Checking, savings and investment accounts never carry liabilities, even though MX Bank reports a due date on them.

mask is the last 4 digits of the account number on every source: FinBank reports 7777 for the credit card, 6666 for the line of credit, 1111 for checking and 2222 for savings; MX Bank accounts report the last 4 of their masked account numbers.

MX OAuth constraint: only one OAuth member is allowed per user for mx_bank_oauth / mxcu_oauth. Tear down the previous OAuth connection before re-linking.

FDE — Ledgersync Bank

FDE is LedgerSync’s proprietary, credential-based extraction path, used for banks neither aggregator covers. It connects through a LedgerSync-hosted page (not an aggregator widget). The sandbox Ledgersync Bank (ins_a7397a8d0656e1b7) accepts any username and password:

Initiate an FDE connection

curl -X POST "https://api-sandbox.ledgersyncappv2.com/v3/clients/cli_.../connections" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"institution_id":"ins_a7397a8d0656e1b7"}'

Open the returned widget_url and:

Enter any credentials

Type any username / password → Submit.

Select the account

An account-selection form appears (one account is offered) → Submit to keep it.

Watch it finish

FDE downloads the statements and check images, then fires connection.active. The connection id is con_FDE_... and transactions come back as txn_FDE_....

Because the bank is already fixed by institution_id, there is no bank-search step, and you never handle the credentials yourself.

Check images

Ledgersync Bank is the only sandbox bank that produces check images — the Finicity and MX sandbox banks have none, so it’s the one place to exercise the check routes end-to-end. Once connection.active lands, read them off the account:

List the checks FDE extracted

curl "https://api-sandbox.ledgersyncappv2.com/v3/accounts/acc_FDE_.../checks?client_id=cli_..." \
  -H "Authorization: Bearer sk_test_..."

Extraction is asynchronous — checks appear once the connection reaches active, not at the moment the widget closes. Wait for the webhook rather than polling straight after submitting credentials.

See Check images for the full contract: the three routes, the read:checks scope, and why bank-reported and OCR fields are kept apart.

Which webhook fires when

Every state transition publishes a real Kafka event and fires the matching webhook, HMAC-signed exactly like production.

Event	When it fires	How to trigger it
`connection.requires_action`	As soon as the widget URL is ready — the first event of every new link.	Signals the user must act; the URL is not in this payload. Take it from the initiate operation’s `result.connection.action.widget_url`. (`POST /v3/connections/{connection_id}/reauthorize` is for a connection you already hold a canonical id for, so it is not an option on a first link.)
`connection.active`	User finishes the widget with valid credentials.	Finicity `customer1` / `go` or MX `mxuser` / `correct`. Accounts now visible via `GET /v3/accounts`.
`connection.failed`	The bank or the aggregator failed in a way the user cannot fix: institution-side outage, the bank refusing automated access, or an upstream pipeline error. A locked Finicity account on an existing connection is `failed` too (the sandbox `locked` login does not simulate one). Rejected credentials and an MX-locked account are `requires_action`, not `failed`.	None of the sandbox logins tested in September 2026 produce it: MX `mxuser` / `SERVER_ERROR` and `UNAVAILABLE` end in the widget without creating a connection, and FinBank `locked` and FinBank Decertified link normally. It fires on a real bank or aggregator failure on an existing connection. `last_error` carries a stable code.
`connection.disconnected`	The source stopped aggregating the connection, or you deleted it.	`DELETE /v3/connections/{id}`.

These are the connection-state events you’ll drive in sandbox. The full catalog (connection.capability_changed, account.refresh.completed, account.refresh.failed) and every payload shape is in Webhooks.

Testing your webhook handler

You don’t have to link a bank to prove your endpoint works. Fire a test event:

Test-fire a subscription

curl -X POST "https://api-sandbox.ledgersyncappv2.com/v3/webhooks/subscriptions/sub_.../test" \
  -H "Authorization: Bearer sk_test_..."

The test delivery is signed with your real signing secret and bypasses the event_types filter, so it reaches your handler even for events you didn’t subscribe to. It arrives as a webhook.test event, a safe way to confirm signature verification, your 2xx-within-30s response, and your event_id dedupe logic before real events flow.

Verify the signature the same way in sandbox as in production: constant-time HMAC-SHA256 over the raw body, and reject deliveries whose timestamp is more than 5 minutes old. See Webhooks for the full recipe.

Common-error recipes

Deliberately trigger each failure mode to harden your handler:

Invalid credentials — initiate FinBank, sign in customer1 / bad. The widget rejects the sign-in and keeps the user on the form. No connection is created and no webhook fires, so there is nothing to handle until the user signs in successfully. (FinBank Decertified, once used for a decertification last_error, links normally as of September 2026.)
MFA wrong answer — initiate Finicity, sign in customer3 / go, submit any OTP other than 999999. As of September 2026 no MFA challenge appears for this login, so this path cannot be reproduced.
MX locked user — initiate MX, sign in mxuser / LOCKED. connection_status = LOCKED; the connection is created and reads requires_action with last_error.code = account_locked_by_institution and is_user_actionable: false. A second connection.requires_action follows within seconds, this one under the canonical con_MX_... id and carrying that last_error. Store that id.
Upstream 503 — initiate MX, sign in mxuser / UNAVAILABLE. Meant to simulate an institution-side 503 (institution_unavailable, retryable), but as of September 2026 the MX widget stays on “Loading” and no connection is created.
requires_action that lingers — start a connection and don’t finish the widget. It stays requires_action (no auto timeout-to-failed today) until the user re-opens the still-valid widget_url or you re-initiate.
Refresh round-trip — link customer1 / go, POST /v3/connections/{id}/refresh, re-read GET /v3/accounts/{id}/transactions for the diff.
Disconnect — DELETE /v3/connections/{id}. connection.disconnected fires; further reads return 404.
Error envelopes — call a read with a bogus client_id or a missing key to see the { "error": { "code", "message", "type", "doc_url", "trace_id" } } shape. Branch on code and quote X-LS-Trace-Id. See Errors.

Sandbox keys can’t hit live data and live keys can’t hit sandbox banks — see insufficient_scope if you mix them up. Finicity test customers are auto-pruned after ~30 days of inactivity; MX has no per-credential cooldown.

Connect a bank

The full initiate → widget → active flow, end to end.

Connection lifecycle

Every status a connection moves through and what each means.

Webhooks

Subscribe, verify signatures, dedupe, and handle retries.

Errors

The error envelope, the full code catalog, and how to branch on code.

Get started

Guides

Go live

What sandbox gives you

Sandbox institution IDs

FinBank (Finicity)

MX Bank (MX)

Ledgersync Bank (FDE)

The 60-second smoke test (FinBank)

Finicity — FinBank credentials

FinBank Profiles A–H — account-shape coverage

Other FinBank variants — edge-case banks

MX sandbox bank (mxbank)

Card terms and masks in sandbox

FDE — Ledgersync Bank

Check images

Which webhook fires when

Testing your webhook handler

Common-error recipes

Connect a bank

Connection lifecycle

Webhooks

Errors

​What sandbox gives you

​Sandbox institution IDs

FinBank (Finicity)

MX Bank (MX)

Ledgersync Bank (FDE)

​The 60-second smoke test (FinBank)

​Finicity — FinBank credentials

​FinBank Profiles A–H — account-shape coverage

​Other FinBank variants — edge-case banks

​MX sandbox bank (mxbank)

​Card terms and masks in sandbox

​FDE — Ledgersync Bank

​Check images

​Which webhook fires when

​Testing your webhook handler

​Common-error recipes

Connect a bank

Connection lifecycle

Webhooks

Errors

What sandbox gives you

Sandbox institution IDs

The 60-second smoke test (FinBank)

Finicity — FinBank credentials

FinBank Profiles A–H — account-shape coverage

Other FinBank variants — edge-case banks

MX sandbox bank (mxbank)

Card terms and masks in sandbox

FDE — Ledgersync Bank

Check images

Which webhook fires when

Testing your webhook handler

Common-error recipes