> ## 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. # Create a sandbox direct deposit with a simulated outcome > Runs direct deposit creation through one deterministic sandbox simulation. Provide exactly one of `returnSimulation`, `riskSimulation`, or `lifecycleSimulation`. `Idempotency-Key` is required and must be reused with the same body after a timeout. An ACH return simulation creates the deposit normally and applies the selected return code to its sandbox debit. A blocking risk simulation selects a public decision outcome while keeping private provider inputs and policy rules out of the API. It returns **409** and creates no deposit: - `review_required` → `risk_review_required`; the source remains active; - `rejected` → `risk_rejected`; the source remains active; - `source_temporarily_unavailable` → `risk_rerouted`; the source becomes temporarily ineligible with `statusReason: rerouted` and an `availableAt` time; - `decision_unavailable` → `risk_evaluation_unavailable`; the source remains active. High-priority simulations create a deposit successfully: - `high_priority_available` → the deposit succeeds with its quoted instant portion. - `high_priority_downgraded` → the deposit succeeds at standard timing with no instant portion. Risk simulations force a fresh simulated decision but do not expose or call the production decision provider. Prepare a new authorization before retrying because the preparation is consumed by the create attempt. Lifecycle simulations never call a money-movement provider. `refunded`, `release_failed`, `release_stalled`, and `full_delivery` require a normal-priority preparation and apply the selected state before execution starts. `full_delivery` records a completed deposit and `achDebit.delivered` milestone. `partial_then_full_delivery` requires a high-priority preparation with both instant and settlement portions; it records deterministic `achDebit.deliveryProgress` and `achDebit.delivered` milestones for the same deposit, then returns the completed deposit. ## OpenAPI ````yaml https://platform.spritz.finance/openapi.json post /v1/sandbox/deposits/direct 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/deposits/direct: post: tags: - Sandbox summary: Create a sandbox direct deposit with a simulated outcome description: >- Runs direct deposit creation through one deterministic sandbox simulation. Provide exactly one of `returnSimulation`, `riskSimulation`, or `lifecycleSimulation`. `Idempotency-Key` is required and must be reused with the same body after a timeout. An ACH return simulation creates the deposit normally and applies the selected return code to its sandbox debit. A blocking risk simulation selects a public decision outcome while keeping private provider inputs and policy rules out of the API. It returns **409** and creates no deposit: - `review_required` → `risk_review_required`; the source remains active; - `rejected` → `risk_rejected`; the source remains active; - `source_temporarily_unavailable` → `risk_rerouted`; the source becomes temporarily ineligible with `statusReason: rerouted` and an `availableAt` time; - `decision_unavailable` → `risk_evaluation_unavailable`; the source remains active. High-priority simulations create a deposit successfully: - `high_priority_available` → the deposit succeeds with its quoted instant portion. - `high_priority_downgraded` → the deposit succeeds at standard timing with no instant portion. Risk simulations force a fresh simulated decision but do not expose or call the production decision provider. Prepare a new authorization before retrying because the preparation is consumed by the create attempt. Lifecycle simulations never call a money-movement provider. `refunded`, `release_failed`, `release_stalled`, and `full_delivery` require a normal-priority preparation and apply the selected state before execution starts. `full_delivery` records a completed deposit and `achDebit.delivered` milestone. `partial_then_full_delivery` requires a high-priority preparation with both instant and settlement portions; it records deterministic `achDebit.deliveryProgress` and `achDebit.delivered` milestones for the same deposit, then returns the completed deposit. operationId: postV1SandboxDepositsDirect parameters: - name: idempotency-key in: header required: true schema: minLength: 1 maxLength: 255 description: >- Unique key for this deposit intent. Reuse it verbatim after a timeout to replay the original response. Reusing it with a different request returns an idempotency conflict. type: string example: deposit-order-7f3f4d4d requestBody: required: true content: application/json: schema: type: object properties: preparationId: description: >- Opaque public preparation identifier returned by direct prepare type: string example: prep_01JV7Q8M4Y8K6N2Z5P3R1T9W0X returnSimulation: type: object properties: code: default: R01 description: >- Sandbox-only ACH return code. The deposit proceeds asynchronously and the code determines the later return state and source/user consequences. type: string enum: - R01 - R02 - R03 - R04 - R05 - R06 - R07 - R08 - R09 - R10 - R11 - R12 - R13 - R14 - R15 - R16 - R17 - R18 - R19 - R20 - R21 - R22 - R23 - R24 - R25 - R26 - R27 - R28 - R29 - R30 - R31 - R32 - R33 - R34 - R35 - R36 - R37 - R38 - R39 - R45 - R51 example: R10 required: - code riskSimulation: type: object properties: profile: type: string enum: - review_required - rejected - source_temporarily_unavailable - decision_unavailable - high_priority_available - high_priority_downgraded required: - profile lifecycleSimulation: type: object properties: profile: default: refunded description: >- Deterministic sandbox lifecycle outcome. Refund, release-failure, release-stall, and full-delivery profiles require normal priority; partial_then_full_delivery requires a high-priority preparation with both instant and settlement portions. type: string enum: - refunded - release_failed - release_stalled - full_delivery - partial_then_full_delivery example: release_failed required: - profile required: - preparationId application/x-www-form-urlencoded: schema: type: object properties: preparationId: description: >- Opaque public preparation identifier returned by direct prepare type: string example: prep_01JV7Q8M4Y8K6N2Z5P3R1T9W0X returnSimulation: type: object properties: code: default: R01 description: >- Sandbox-only ACH return code. The deposit proceeds asynchronously and the code determines the later return state and source/user consequences. type: string enum: - R01 - R02 - R03 - R04 - R05 - R06 - R07 - R08 - R09 - R10 - R11 - R12 - R13 - R14 - R15 - R16 - R17 - R18 - R19 - R20 - R21 - R22 - R23 - R24 - R25 - R26 - R27 - R28 - R29 - R30 - R31 - R32 - R33 - R34 - R35 - R36 - R37 - R38 - R39 - R45 - R51 example: R10 required: - code riskSimulation: type: object properties: profile: type: string enum: - review_required - rejected - source_temporarily_unavailable - decision_unavailable - high_priority_available - high_priority_downgraded required: - profile lifecycleSimulation: type: object properties: profile: default: refunded description: >- Deterministic sandbox lifecycle outcome. Refund, release-failure, release-stall, and full-delivery profiles require normal priority; partial_then_full_delivery requires a high-priority preparation with both instant and settlement portions. type: string enum: - refunded - release_failed - release_stalled - full_delivery - partial_then_full_delivery example: release_failed required: - profile required: - preparationId multipart/form-data: schema: type: object properties: preparationId: description: >- Opaque public preparation identifier returned by direct prepare type: string example: prep_01JV7Q8M4Y8K6N2Z5P3R1T9W0X returnSimulation: type: object properties: code: default: R01 description: >- Sandbox-only ACH return code. The deposit proceeds asynchronously and the code determines the later return state and source/user consequences. type: string enum: - R01 - R02 - R03 - R04 - R05 - R06 - R07 - R08 - R09 - R10 - R11 - R12 - R13 - R14 - R15 - R16 - R17 - R18 - R19 - R20 - R21 - R22 - R23 - R24 - R25 - R26 - R27 - R28 - R29 - R30 - R31 - R32 - R33 - R34 - R35 - R36 - R37 - R38 - R39 - R45 - R51 example: R10 required: - code riskSimulation: type: object properties: profile: type: string enum: - review_required - rejected - source_temporarily_unavailable - decision_unavailable - high_priority_available - high_priority_downgraded required: - profile lifecycleSimulation: type: object properties: profile: default: refunded description: >- Deterministic sandbox lifecycle outcome. Refund, release-failure, release-stall, and full-delivery profiles require normal priority; partial_then_full_delivery requires a high-priority preparation with both instant and settlement portions. type: string enum: - refunded - release_failed - release_stalled - full_delivery - partial_then_full_delivery example: release_failed required: - profile required: - preparationId responses: '200': description: >- An ACH debit deposit authorized by the user and processed asynchronously through debit and crypto release lifecycles. content: application/json: schema: description: >- An ACH debit deposit authorized by the user and processed asynchronously through debit and crypto release lifecycles. type: object properties: id: description: Opaque public deposit identifier type: string example: dep_01JV7Q8M4Y8K6N2Z5P3R1T9W0X sourceId: description: Opaque public funding source identifier type: string example: fs_01JV7Q8M4Y8K6N2Z5P3R1T9W0X onRampId: type: string description: >- Identifier of the on-ramp created for this deposit, or null until the on-ramp record exists. nullable: true example: onramp_xyz789 status: type: string enum: - authorized - processing - partially_released - completed - returned - refunded - failed quoteType: type: string enum: - exact_input - exact_output requestedPriority: type: string enum: - normal - high priority: type: string enum: - normal - high feeRateBps: type: number principalAmountUsd: type: string instantPortionUsd: type: string settlementPortionUsd: type: string expectedAssetAmount: type: string grossFeeUsd: type: string publishedFeeUsd: type: string regularPublishedFeeUsd: type: string instantPublishedFeeUsd: type: string feeSubsidyUsd: type: string userFeeUsd: type: string totalDebitAmountUsd: type: string feeSubsidy: type: object properties: percentage: type: number percentageBps: type: number maxAmountUsd: type: string nullable: true appliedAmountUsd: type: string required: - percentage - percentageBps - maxAmountUsd - appliedAmountUsd nullable: true network: type: string enum: - solana - ethereum - polygon - base - avalanche - arbitrum asset: description: Asset sent to the deposit destination type: string example: USDC enum: - USDC assetAddress: type: string address: description: Destination wallet address for the crypto release type: string debitStatus: type: string enum: - authorized - submitting - submitted - settled - returned - failed releaseStatus: type: string enum: - not_started - queued - partial - completed - failed releaseDecisionMode: type: string enum: - after_settlement - early_full - early_partial releasedAmountUsd: type: string confirmedReleasedAmountUsd: type: string authorizedAt: format: date-time type: string createdAt: format: date-time type: string settledAt: format: date-time type: string nullable: true returnedAt: format: date-time type: string nullable: true completedAt: format: date-time type: string nullable: true returnCode: type: string nullable: true returnReason: type: string nullable: true debitFailureCode: type: string nullable: true debitFailureReason: type: string nullable: true releaseFailureCode: type: string nullable: true releaseFailureReason: type: string nullable: true payoutTxHash: type: string nullable: true required: - id - sourceId - onRampId - status - quoteType - requestedPriority - priority - feeRateBps - principalAmountUsd - instantPortionUsd - settlementPortionUsd - expectedAssetAmount - grossFeeUsd - publishedFeeUsd - regularPublishedFeeUsd - instantPublishedFeeUsd - feeSubsidyUsd - userFeeUsd - totalDebitAmountUsd - feeSubsidy - network - asset - assetAddress - address - debitStatus - releaseStatus - releaseDecisionMode - releasedAmountUsd - confirmedReleasedAmountUsd - authorizedAt - createdAt - settledAt - returnedAt - completedAt - returnCode - returnReason - debitFailureCode - debitFailureReason - releaseFailureCode - releaseFailureReason - payoutTxHash '400': description: Response for status 400 content: application/problem+json: schema: type: object allOf: - 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 description: >- Safe next action when the failing product policy can provide one. 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 - type: object properties: errors: description: >- Every cause. A single-cause failure also reports it via top-level `code`/`field`/`detail`; a multi-field failure is described only here. type: array items: type: object properties: field: type: string message: type: string code: type: string required: - field - message '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 '404': description: Response for status 404 content: application/problem+json: schema: type: object properties: type: default: about:blank description: A URI reference that identifies the problem type type: string title: description: A short, human-readable summary of the problem type type: string status: description: The HTTP status code type: number example: 404 detail: description: A human-readable explanation specific to this occurrence type: string instance: description: A URI reference that identifies the specific occurrence type: string resourceType: description: The type of resource that was not found type: string example: user resourceId: description: The identifier of the resource that was not found type: string required: - title - status - resourceType - resourceId additionalProperties: false '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 '422': description: Response for status 422 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 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. ````