Test mode
A test key returns a fixture document instead of reading the file you send. It is free, it does not touch your free pages or your cap, and it can return any error code on demand.
Send a request#
Take an sb_test_ key from the console. Same endpoint, same host, same headers. Send any file the API accepts: it is checked for size and type and then discarded unread.
Scenarios#
Send X-Test-Scenario to choose what comes back. Omit it for bank.
| Scenario | Returns | What it is |
|---|---|---|
bank | 200 | A single current account, reconciled. The default when no header is sent. |
credit_card | 200 | A card statement. Its credits are the repayment and a refund, so it is what to test your income filter against. |
multi_account | 200 | A checking and a savings account on one document, with a transfer printed on both sides. |
unreconciled | 200 | A document whose figures did not reconcile. Exercises your manual review path. |
suspicious | 200 | An unreconciled document with authenticity.risk high: edited in a PDF editor, modified after creation, balances that do not follow. Exercises your fraud review path. |
not_a_bank_statement | 422 | The file was readable and is not a statement. |
password_required | 422 | The PDF is password-protected and no password was sent. |
incorrect_password | 422 | The password sent does not open the PDF. |
parse_failed | 500 | Our error. Retry it. |
free_pages_exhausted | 402 | The free pages are spent and no payment method is on file. |
not_enough_free_pages | 402 | Some free pages are left, fewer than the file has, and no payment method is on file. |
monthly_cap_reached | 402 | The file would pass the monthly page cap. |
canceled | 402 | Billing for the account was cancelled. |
too_many_concurrent_requests | 429 | Too many documents in flight. Exercises your backoff. |
file_too_large | 413 | Over the size limit, without uploading 50MB to find out. |
An unknown value returns 400 unknown_test_scenario and the message lists every valid one. The parsing MCP server takes the same names in its test_scenario argument.
Telling a fixture apart#
Every document carries livemode. It is false on a fixture and true on a real read. Store it with whatever you read the document for.
{ "id": "doc_test_9c41f0a2b8e37c94d0a1b2c3", "object": "document", "status": "succeeded", "livemode": false, "currency": "GBP", "issuer": { "name": "Monzo", "domain": "monzo.com" }, "accounts": [ ... ], "verification": { "reconciled": true, "issues": [] }, "authenticity": { "risk": "low", "signals": [], ... }, "usage": { "pages": 3, "billablePages": 0 } }
A fixture's id starts doc_test_. Everything else about a scenario except created is the same on every call, so it is safe to assert on in a snapshot test.
What is the same#
- Authentication, including
401for a missing or revoked key. - The size and type checks on your upload. A file the API does not read still returns
415. async=true: a202withstatus: "processing", thensucceededa couple of seconds later.- Webhooks, sent to your test endpoints only. See Webhooks.
- Stored documents: list, fetch and delete them like live ones. A test key sees only test documents.
- Collections: a test collection's hosted page works, and every upload returns the
bankfixture. Idempotency-Key, including replays,Idempotent-Replayed: trueand the409after 24 hours.- The response envelope, the error codes and every header.
- Logs in your console, so a test call shows up like any other.
What is different#
- The file you send is never read. The response is a fixture.
- Nothing is billed.
X-Billable-Pagesandusage.billablePagesare always0. - Your free pages and monthly cap are untouched.
- Test keys keep working when billing is cancelled.
- Concurrency is not limited. Up to 120 test requests per minute instead.
Idempotency keys#
An idempotency key is scoped to the mode that used it. The same string can be used once in test and once for real, and neither replays the other.
Going live#
- Swap
sb_test_forsb_live_in your secret store. - Remove
X-Test-Scenario. A live key sends it back as400 test_scenario_on_live_key, and nothing is read or charged. - Add a live webhook endpoint with its own secret. A test endpoint never receives live events.
- Check that whatever you store records
livemode. - Work through the rest of Going live.