> ## Documentation Index > Fetch the complete documentation index at: https://docs.spritz.finance/llms.txt > Use this file to discover all available pages before exploring further. # Link a deterministic sandbox bank account > Creates a Plaid custom Sandbox item without opening Link, then runs the normal Spritz token exchange, ownership evaluation, bank-account sync, funding-source creation, cache invalidation, and event paths. Query the returned account's fundingSourceId for the resulting ownership eligibility state. ## OpenAPI ````yaml https://platform.spritz.finance/openapi.json post /v1/sandbox/bank-accounts/link openapi: 3.0.3 info: title: Spritz Finance API version: 1.0.0 description: API for the Spritz Finance platform with RFC 9457 error handling servers: - url: https://platform.spritz.finance description: Production - url: https://sandbox.spritz.finance description: Sandbox security: [] tags: - name: Users description: User management endpoints - name: Bank Accounts description: Manage bank accounts for off-ramp destinations - name: Bills description: Manage bill pay accounts - name: Cards description: Spritz-issued debit cards - name: Auto-Ramp Accounts description: Virtual bank accounts that automatically convert fiat deposits to crypto - name: Spritz App description: >- Endpoints used by the Spritz app and internal SDKs. Excluded from the public partner spec. paths: /v1/sandbox/bank-accounts/link: post: tags: - Sandbox summary: Link a deterministic sandbox bank account description: >- Creates a Plaid custom Sandbox item without opening Link, then runs the normal Spritz token exchange, ownership evaluation, bank-account sync, funding-source creation, cache invalidation, and event paths. Query the returned account's fundingSourceId for the resulting ownership eligibility state. operationId: postV1SandboxBank-accountsLink requestBody: required: true content: application/json: schema: type: object properties: simulation: type: object properties: code: default: ownership_pending description: >- Deterministic Plaid sandbox bank-link scenario. `ownership_pending`: linking succeeds and the funding source remains pending for frontend-state testing. `ownership_matched`: linking succeeds and the funding source is active. `ownership_uncertain`: linking succeeds and the funding source requires ownership review. `ownership_mismatch`: linking succeeds and the funding source is ineligible because ownership does not match. `link_failed`: linking fails before Spritz persists a bank account or funding source. `duplicate_identity`: linking returns a non-retryable conflict because the verified identity belongs to another account. `duplicate_bank_account`: linking returns a non-retryable conflict because the bank account belongs to another account. type: string enum: - ownership_pending - ownership_matched - ownership_uncertain - ownership_mismatch - link_failed - duplicate_identity - duplicate_bank_account example: ownership_matched account: description: >- Which deterministic sandbox bank account to link. Defaults to `primary`; use `secondary` to link another distinct account for the same user. type: string enum: - primary - secondary example: secondary required: - code required: - simulation application/x-www-form-urlencoded: schema: type: object properties: simulation: type: object properties: code: default: ownership_pending description: >- Deterministic Plaid sandbox bank-link scenario. `ownership_pending`: linking succeeds and the funding source remains pending for frontend-state testing. `ownership_matched`: linking succeeds and the funding source is active. `ownership_uncertain`: linking succeeds and the funding source requires ownership review. `ownership_mismatch`: linking succeeds and the funding source is ineligible because ownership does not match. `link_failed`: linking fails before Spritz persists a bank account or funding source. `duplicate_identity`: linking returns a non-retryable conflict because the verified identity belongs to another account. `duplicate_bank_account`: linking returns a non-retryable conflict because the bank account belongs to another account. type: string enum: - ownership_pending - ownership_matched - ownership_uncertain - ownership_mismatch - link_failed - duplicate_identity - duplicate_bank_account example: ownership_matched account: description: >- Which deterministic sandbox bank account to link. Defaults to `primary`; use `secondary` to link another distinct account for the same user. type: string enum: - primary - secondary example: secondary required: - code required: - simulation multipart/form-data: schema: type: object properties: simulation: type: object properties: code: default: ownership_pending description: >- Deterministic Plaid sandbox bank-link scenario. `ownership_pending`: linking succeeds and the funding source remains pending for frontend-state testing. `ownership_matched`: linking succeeds and the funding source is active. `ownership_uncertain`: linking succeeds and the funding source requires ownership review. `ownership_mismatch`: linking succeeds and the funding source is ineligible because ownership does not match. `link_failed`: linking fails before Spritz persists a bank account or funding source. `duplicate_identity`: linking returns a non-retryable conflict because the verified identity belongs to another account. `duplicate_bank_account`: linking returns a non-retryable conflict because the bank account belongs to another account. type: string enum: - ownership_pending - ownership_matched - ownership_uncertain - ownership_mismatch - link_failed - duplicate_identity - duplicate_bank_account example: ownership_matched account: description: >- Which deterministic sandbox bank account to link. Defaults to `primary`; use `secondary` to link another distinct account for the same user. type: string enum: - primary - secondary example: secondary required: - code required: - simulation responses: '200': description: Response for status 200 content: application/json: schema: type: object properties: bankAccounts: type: array items: description: >- Bank account details. The `type` field indicates the account variant. anyOf: - description: US bank account response type: object properties: id: description: Unique identifier for the bank account type: string example: ba_abc123 status: type: string enum: - active - inactive description: >- Whether the account can receive payouts. `active` is the only payable state; every other value means the account cannot be paid, and `statusReason` says why. Treat any value that is not `active` as unpayable rather than switching on the full list — new states may be added and will always follow that rule. example: active statusReason: type: string enum: - account_invalid - account_closed - account_blocked - not_supported - null description: >- Why the account cannot receive payouts. Always present when `status` is not `active`, and always `null` when it is. - `account_invalid` — the receiving bank does not recognise the account details. - `account_closed` — the account has been closed at the bank. - `account_blocked` — the bank will not accept credits to this account. - `not_supported` — Spritz cannot pay accounts of this type or region. All four are terminal: the account will not recover, so prompt the user to add a different one. nullable: true example: account_invalid accountHolderName: description: >- Display name recorded on the user's bank account. This is not an ownership-match or eligibility decision. type: string example: John Doe institution: description: Financial institution details type: object properties: name: description: Name of the financial institution type: string example: Chase logo: description: URL to institution logo type: string example: https://example.com/chase-logo.png required: - name supportedRails: description: Payment rails available for this account type: array items: type: string enum: - ach_standard - ach_same_day - rtp - wire - eft - sepa - faster_payments - push_to_card - bill_pay - card_deposit description: >- Fiat delivery rail. - `ach_standard`: ACH bank transfer, next business day. - `ach_same_day`: ACH same-day transfer, delivered same business day. - `rtp`: Real-time payment, seconds, 24/7. - `wire`: Wire transfer, same/next day. - `eft`: Electronic funds transfer, 1-2 business days. - `sepa`: SEPA transfer (EU), 1-2 business days. - `faster_payments`: UK Faster Payments, near-instant. - `push_to_card`: Push to debit card, minutes. - `bill_pay`: Bill payment rail. - `card_deposit`: Deposit to crypto card. example: ach_standard example: - ach_standard - rtp label: description: Friendly name for the account type: string example: Primary Checking createdAt: description: When the account was created format: date-time type: string fundingSourceId: type: string description: >- Associated opaque public funding source identifier, or null when no funding source exists for this bank account. nullable: true type: type: string enum: - us currency: type: string enum: - USD accountNumberLast4: description: Last 4 digits of account number type: string example: '6789' routingNumberLast4: description: Last 4 digits of routing number type: string example: '0021' accountSubtype: type: string enum: - checking - savings description: Type of bank account (checking or savings) example: checking required: - id - status - statusReason - accountHolderName - supportedRails - createdAt - fundingSourceId - type - currency - accountNumberLast4 - routingNumberLast4 - description: Canadian bank account response type: object properties: id: description: Unique identifier for the bank account type: string example: ba_abc123 status: type: string enum: - active - inactive description: >- Whether the account can receive payouts. `active` is the only payable state; every other value means the account cannot be paid, and `statusReason` says why. Treat any value that is not `active` as unpayable rather than switching on the full list — new states may be added and will always follow that rule. example: active statusReason: type: string enum: - account_invalid - account_closed - account_blocked - not_supported - null description: >- Why the account cannot receive payouts. Always present when `status` is not `active`, and always `null` when it is. - `account_invalid` — the receiving bank does not recognise the account details. - `account_closed` — the account has been closed at the bank. - `account_blocked` — the bank will not accept credits to this account. - `not_supported` — Spritz cannot pay accounts of this type or region. All four are terminal: the account will not recover, so prompt the user to add a different one. nullable: true example: account_invalid accountHolderName: description: >- Display name recorded on the user's bank account. This is not an ownership-match or eligibility decision. type: string example: John Doe institution: description: Financial institution details type: object properties: name: description: Name of the financial institution type: string example: Chase logo: description: URL to institution logo type: string example: https://example.com/chase-logo.png required: - name supportedRails: description: Payment rails available for this account type: array items: type: string enum: - ach_standard - ach_same_day - rtp - wire - eft - sepa - faster_payments - push_to_card - bill_pay - card_deposit description: >- Fiat delivery rail. - `ach_standard`: ACH bank transfer, next business day. - `ach_same_day`: ACH same-day transfer, delivered same business day. - `rtp`: Real-time payment, seconds, 24/7. - `wire`: Wire transfer, same/next day. - `eft`: Electronic funds transfer, 1-2 business days. - `sepa`: SEPA transfer (EU), 1-2 business days. - `faster_payments`: UK Faster Payments, near-instant. - `push_to_card`: Push to debit card, minutes. - `bill_pay`: Bill payment rail. - `card_deposit`: Deposit to crypto card. example: ach_standard example: - ach_standard - rtp label: description: Friendly name for the account type: string example: Primary Checking createdAt: description: When the account was created format: date-time type: string fundingSourceId: type: string description: >- Associated opaque public funding source identifier, or null when no funding source exists for this bank account. nullable: true type: type: string enum: - ca currency: type: string enum: - CAD accountNumberLast4: description: Last 4 digits of account number type: string example: '4567' institutionNumber: description: 3-digit institution number type: string example: '001' transitNumberLast3: description: Last 3 digits of transit number type: string example: '345' accountSubtype: type: string enum: - checking - savings description: Type of bank account (checking or savings) example: checking required: - id - status - statusReason - accountHolderName - supportedRails - createdAt - fundingSourceId - type - currency - accountNumberLast4 - institutionNumber - transitNumberLast3 - description: UK bank account response type: object properties: id: description: Unique identifier for the bank account type: string example: ba_abc123 status: type: string enum: - active - inactive description: >- Whether the account can receive payouts. `active` is the only payable state; every other value means the account cannot be paid, and `statusReason` says why. Treat any value that is not `active` as unpayable rather than switching on the full list — new states may be added and will always follow that rule. example: active statusReason: type: string enum: - account_invalid - account_closed - account_blocked - not_supported - null description: >- Why the account cannot receive payouts. Always present when `status` is not `active`, and always `null` when it is. - `account_invalid` — the receiving bank does not recognise the account details. - `account_closed` — the account has been closed at the bank. - `account_blocked` — the bank will not accept credits to this account. - `not_supported` — Spritz cannot pay accounts of this type or region. All four are terminal: the account will not recover, so prompt the user to add a different one. nullable: true example: account_invalid accountHolderName: description: >- Display name recorded on the user's bank account. This is not an ownership-match or eligibility decision. type: string example: John Doe institution: description: Financial institution details type: object properties: name: description: Name of the financial institution type: string example: Chase logo: description: URL to institution logo type: string example: https://example.com/chase-logo.png required: - name supportedRails: description: Payment rails available for this account type: array items: type: string enum: - ach_standard - ach_same_day - rtp - wire - eft - sepa - faster_payments - push_to_card - bill_pay - card_deposit description: >- Fiat delivery rail. - `ach_standard`: ACH bank transfer, next business day. - `ach_same_day`: ACH same-day transfer, delivered same business day. - `rtp`: Real-time payment, seconds, 24/7. - `wire`: Wire transfer, same/next day. - `eft`: Electronic funds transfer, 1-2 business days. - `sepa`: SEPA transfer (EU), 1-2 business days. - `faster_payments`: UK Faster Payments, near-instant. - `push_to_card`: Push to debit card, minutes. - `bill_pay`: Bill payment rail. - `card_deposit`: Deposit to crypto card. example: ach_standard example: - ach_standard - rtp label: description: Friendly name for the account type: string example: Primary Checking createdAt: description: When the account was created format: date-time type: string fundingSourceId: type: string description: >- Associated opaque public funding source identifier, or null when no funding source exists for this bank account. nullable: true type: type: string enum: - uk currency: type: string enum: - GBP accountNumberLast4: description: Last 4 digits of account number type: string example: '2345' sortCode: description: 6-digit sort code (not sensitive) type: string example: '108800' required: - id - status - statusReason - accountHolderName - supportedRails - createdAt - fundingSourceId - type - currency - accountNumberLast4 - sortCode - description: IBAN bank account response type: object properties: id: description: Unique identifier for the bank account type: string example: ba_abc123 status: type: string enum: - active - inactive description: >- Whether the account can receive payouts. `active` is the only payable state; every other value means the account cannot be paid, and `statusReason` says why. Treat any value that is not `active` as unpayable rather than switching on the full list — new states may be added and will always follow that rule. example: active statusReason: type: string enum: - account_invalid - account_closed - account_blocked - not_supported - null description: >- Why the account cannot receive payouts. Always present when `status` is not `active`, and always `null` when it is. - `account_invalid` — the receiving bank does not recognise the account details. - `account_closed` — the account has been closed at the bank. - `account_blocked` — the bank will not accept credits to this account. - `not_supported` — Spritz cannot pay accounts of this type or region. All four are terminal: the account will not recover, so prompt the user to add a different one. nullable: true example: account_invalid accountHolderName: description: >- Display name recorded on the user's bank account. This is not an ownership-match or eligibility decision. type: string example: John Doe institution: description: Financial institution details type: object properties: name: description: Name of the financial institution type: string example: Chase logo: description: URL to institution logo type: string example: https://example.com/chase-logo.png required: - name supportedRails: description: Payment rails available for this account type: array items: type: string enum: - ach_standard - ach_same_day - rtp - wire - eft - sepa - faster_payments - push_to_card - bill_pay - card_deposit description: >- Fiat delivery rail. - `ach_standard`: ACH bank transfer, next business day. - `ach_same_day`: ACH same-day transfer, delivered same business day. - `rtp`: Real-time payment, seconds, 24/7. - `wire`: Wire transfer, same/next day. - `eft`: Electronic funds transfer, 1-2 business days. - `sepa`: SEPA transfer (EU), 1-2 business days. - `faster_payments`: UK Faster Payments, near-instant. - `push_to_card`: Push to debit card, minutes. - `bill_pay`: Bill payment rail. - `card_deposit`: Deposit to crypto card. example: ach_standard example: - ach_standard - rtp label: description: Friendly name for the account type: string example: Primary Checking createdAt: description: When the account was created format: date-time type: string fundingSourceId: type: string description: >- Associated opaque public funding source identifier, or null when no funding source exists for this bank account. nullable: true type: type: string enum: - iban currency: type: string enum: - USD - CAD - EUR - GBP description: Fiat currency code example: USD ibanLast4: description: Last 4 characters of IBAN type: string example: '3000' bic: description: Bank Identifier Code type: string example: COBADEFFXXX required: - id - status - statusReason - accountHolderName - supportedRails - createdAt - fundingSourceId - type - currency - ibanLast4 required: - bankAccounts '401': description: Response for status 401 content: application/problem+json: schema: type: object properties: type: default: about:blank description: A URI reference that identifies the problem type type: string example: urn:problem-type:auth:unauthorized title: description: A short, human-readable summary of the problem type type: string example: Unauthorized status: description: The HTTP status code type: number example: 401 detail: description: A human-readable explanation specific to this occurrence type: string example: Bearer token required instance: description: A URI reference that identifies the specific occurrence type: string realm: description: The authentication realm type: string example: API scope: description: The required scope for this resource type: string example: read:users required: - title - status additionalProperties: false '403': description: Response for status 403 content: application/problem+json: schema: additionalProperties: true type: object properties: type: default: about:blank description: A URI reference that identifies the problem type type: string example: urn:problem-type:auth:unauthorized title: description: A short, human-readable summary of the problem type type: string example: Unauthorized status: description: The HTTP status code type: number example: 400 detail: description: A human-readable explanation specific to this occurrence type: string instance: description: A URI reference that identifies the specific occurrence type: string example: /errors/1234567890 code: description: >- Machine-readable cause, present when exactly one thing failed. Branch on this, never on `detail`, which is human-facing copy and may change. For deposit limits the vocabulary matches the `reason` values the limits API returns pre-flight. type: string example: transaction_limit field: description: The offending request field, present alongside `code`. type: string example: amountUsd retryable: description: >- Whether retrying the same request later may succeed without changing its inputs. type: boolean example: true retryAfter: description: >- Seconds to wait before retrying, present alongside `retryable: true`. Mirrors the `Retry-After` response header and is meant for short backoffs the server chose (load shedding); for a condition that clears on its own schedule, `clearsAt` carries the absolute time instead. type: number example: 5 suggestedAction: type: string enum: - auto_ramp - wait_for_settlement clearsAt: format: date-time type: string description: >- Earliest known time the current temporary condition may clear. nullable: true availableAt: format: date-time type: string description: >- When a temporarily ineligible funding source may become available again. nullable: true permanent: description: >- Whether the current funding-source restriction will not clear automatically. type: boolean required: - title - status '409': description: Response for status 409 content: application/problem+json: schema: additionalProperties: true type: object properties: type: default: about:blank description: A URI reference that identifies the problem type type: string example: urn:problem-type:auth:unauthorized title: description: A short, human-readable summary of the problem type type: string example: Unauthorized status: description: The HTTP status code type: number example: 400 detail: description: A human-readable explanation specific to this occurrence type: string instance: description: A URI reference that identifies the specific occurrence type: string example: /errors/1234567890 code: description: >- Machine-readable cause, present when exactly one thing failed. Branch on this, never on `detail`, which is human-facing copy and may change. For deposit limits the vocabulary matches the `reason` values the limits API returns pre-flight. type: string example: transaction_limit field: description: The offending request field, present alongside `code`. type: string example: amountUsd retryable: description: >- Whether retrying the same request later may succeed without changing its inputs. type: boolean example: true retryAfter: description: >- Seconds to wait before retrying, present alongside `retryable: true`. Mirrors the `Retry-After` response header and is meant for short backoffs the server chose (load shedding); for a condition that clears on its own schedule, `clearsAt` carries the absolute time instead. type: number example: 5 suggestedAction: type: string enum: - auto_ramp - wait_for_settlement clearsAt: format: date-time type: string description: >- Earliest known time the current temporary condition may clear. nullable: true availableAt: format: date-time type: string description: >- When a temporarily ineligible funding source may become available again. nullable: true permanent: description: >- Whether the current funding-source restriction will not clear automatically. type: boolean required: - title - status '500': description: Response for status 500 content: application/problem+json: schema: additionalProperties: true type: object properties: type: default: about:blank description: A URI reference that identifies the problem type type: string example: urn:problem-type:auth:unauthorized title: description: A short, human-readable summary of the problem type type: string example: Unauthorized status: description: The HTTP status code type: number example: 400 detail: description: A human-readable explanation specific to this occurrence type: string instance: description: A URI reference that identifies the specific occurrence type: string example: /errors/1234567890 code: description: >- Machine-readable cause, present when exactly one thing failed. Branch on this, never on `detail`, which is human-facing copy and may change. For deposit limits the vocabulary matches the `reason` values the limits API returns pre-flight. type: string example: transaction_limit field: description: The offending request field, present alongside `code`. type: string example: amountUsd retryable: description: >- Whether retrying the same request later may succeed without changing its inputs. type: boolean example: true retryAfter: description: >- Seconds to wait before retrying, present alongside `retryable: true`. Mirrors the `Retry-After` response header and is meant for short backoffs the server chose (load shedding); for a condition that clears on its own schedule, `clearsAt` carries the absolute time instead. type: number example: 5 suggestedAction: type: string enum: - auto_ramp - wait_for_settlement clearsAt: format: date-time type: string description: >- Earliest known time the current temporary condition may clear. nullable: true availableAt: format: date-time type: string description: >- When a temporarily ineligible funding source may become available again. nullable: true permanent: description: >- Whether the current funding-source restriction will not clear automatically. type: boolean required: - title - status '503': description: Response for status 503 content: application/problem+json: schema: additionalProperties: true type: object properties: type: default: about:blank description: A URI reference that identifies the problem type type: string example: urn:problem-type:auth:unauthorized title: description: A short, human-readable summary of the problem type type: string example: Unauthorized status: description: The HTTP status code type: number example: 400 detail: description: A human-readable explanation specific to this occurrence type: string instance: description: A URI reference that identifies the specific occurrence type: string example: /errors/1234567890 code: description: >- Machine-readable cause, present when exactly one thing failed. Branch on this, never on `detail`, which is human-facing copy and may change. For deposit limits the vocabulary matches the `reason` values the limits API returns pre-flight. type: string example: transaction_limit field: description: The offending request field, present alongside `code`. type: string example: amountUsd retryable: description: >- Whether retrying the same request later may succeed without changing its inputs. type: boolean example: true retryAfter: description: >- Seconds to wait before retrying, present alongside `retryable: true`. Mirrors the `Retry-After` response header and is meant for short backoffs the server chose (load shedding); for a condition that clears on its own schedule, `clearsAt` carries the absolute time instead. type: number example: 5 suggestedAction: type: string enum: - auto_ramp - wait_for_settlement clearsAt: format: date-time type: string description: >- Earliest known time the current temporary condition may clear. nullable: true availableAt: format: date-time type: string description: >- When a temporarily ineligible funding source may become available again. nullable: true permanent: description: >- Whether the current funding-source restriction will not clear automatically. type: boolean required: - title - status security: - bearerAuth: [] - integratorJwt: [] - bearerAuth: [] hmacAuth: [] integratorKey: [] timestamp: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT or ak_ user API key description: >- User bearer credential: either a Cognito JWT or an ak_ user API key. Backend integrators using HMAC must include the user API key alongside the three HMAC headers on user-scoped endpoints. integratorJwt: type: http scheme: bearer bearerFormat: JWT description: >- Integrator JWT token (prefix: spr_) for frontend integrator authentication. Obtained via token exchange endpoint. hmacAuth: type: apiKey in: header name: X-Signature description: >- HMAC signature authentication for backend integrators. **Required Headers:** - X-Integrator-Key: Integrator API key (format: ik_...) - X-Signature: HMAC signature (format: sha256={hex}) - X-Timestamp: Unix timestamp in milliseconds - Authorization: Bearer {user-api-key} **Signature Algorithm:** HMAC-SHA256 **Signature Format:** {timestamp}.{METHOD}.{path}.{bodyHash} - timestamp: Unix timestamp in milliseconds - METHOD: HTTP method in UPPERCASE (GET, POST, etc.) - path: Request path (e.g., /v1/transactions) - bodyHash: SHA256 hex digest of request body (empty string if no body) **Timestamp Tolerance:** ±5 minutes (300 seconds) **Example:** For POST /v1/transactions with body {"amount":100} and timestamp 1234567890000: Payload: 1234567890000.POST./v1/transactions.{sha256(body)} Signature: sha256=abc123... integratorKey: type: apiKey in: header name: X-Integrator-Key description: 'Integrator API key (format: ik_...) used with HMAC authentication' timestamp: type: apiKey in: header name: X-Timestamp description: >- Unix timestamp in milliseconds for request freshness. Must be within 5 minutes of server time. The timestamp alone bounds but does not prevent an exact replay within that window. Use Idempotency-Key on supported mutations. ````