--- title: "Simulate a deposit (sandbox only)" method: POST path: "/v1/test/customers/{customerId}/deposits/simulate" tags: ["Sandbox"] --- # Simulate a deposit (sandbox only) `POST /v1/test/customers/{customerId}/deposits/simulate` ## Request - Base URL: `https://api.sandbox.alfredpay.io` - URL: `https://api.sandbox.alfredpay.io/v1/test/customers/{customerId}/deposits/simulate` - Auth: one of: - HTTP bearer - API key in header `api-key` and API key in header `api-secret` The only way to originate a pay-in from the client side. It runs the real pipeline: detection, attribution, events, screening, conversion and crediting. Exists on the sandbox host only. On production the path returns `404 not_found`. `Idempotency-Key` is required, exactly as on any other POST. Fires the full event sequence for a pay-in. See [Webhooks and events](/docs/webhooks-and-events). ## Headers - `Idempotency-Key` string, uuid, required ## Request body - object - `virtualAccountId` string - `depositAddressId` string - `amount` Money, required - `value` string, required - `currency` 'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT', required: Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require `chain`. - `reference` string: Simulates the payer quoting a reference. - `sender` Sender - `name` string - `bank_name` string - `account_last4` string - `rail` 'ACH' | 'WIRE' | 'SPEI' | 'PIX' | 'COELSA' | 'FPS' | 'CHATS' | 'WALLET': The scheme family a payment moves on. Never a country, provider or account identifier. `ACH` is any domestic batch bank transfer (US ACH, and the local clearing houses of COL, CHL, PER, BOL, PRY, DOM, CHN); `WIRE` is RTGS/SWIFT/Fedwire; `SPEI`, `PIX`, `COELSA`, `FPS` and `CHATS` are named instant schemes with their own semantics (COELSA is Argentina's instant transfer, deliberately not folded into ACH); `WALLET` is a stablecoin destination. Cash pickup is not in this release and has no rail value yet. Which rails a destination supports is derived by Alfred and returned as `supportedRails[]`; which `(country, currency, rail)` combinations are live is published by `GET /v1/countries/{country}`. - `rail_reference` string ## Response `202` Accepted - Deposit: Present on every money object. The four machines move independently. - `transaction_id` string, required - `transaction_type` 'PAY_IN' | 'PAY_OUT' | 'CONVERSION', required - `pay_in_subtype` 'COLLECTION' | 'ON_RAMP' | 'USD_STABLE_DEPOSIT' | 'null', nullable - `pay_out_subtype` 'OFF_RAMP' | 'FIAT_WITHDRAWAL' | 'CRYPTO_WITHDRAWAL' | 'CROSS_BORDER_PAYOUT' | 'null', nullable - `conversion_subtype` 'OTC_TRADE' | 'BALANCE_CONVERSION' | 'null', nullable - `transaction_status` 'CREATED' | 'PENDING_VALIDATION' | 'PENDING_FUNDS' | 'PENDING_COMPLIANCE' | 'PENDING_RFI' | 'APPROVED_FOR_EXECUTION' | 'PROCESSING' | 'COMPLETE' | 'FAILED' | 'CANCELLED' | 'BLOCKED', required: Business lifecycle, customer-facing. Terminal values are COMPLETE, FAILED, CANCELLED, BLOCKED. - `compliance_status` 'NOT_REQUIRED' | 'PENDING_SCREENING' | 'PENDING_KYT' | 'CLEARED' | 'ALERTED' | 'RFI_REQUESTED' | 'PAUSED' | 'ESCALATED' | 'RELEASED' | 'BLOCKED', required - `settlement_status` 'NOT_STARTED' | 'FUNDS_EXPECTED' | 'FUNDS_RECEIVED' | 'FUNDS_HELD' | 'FUNDS_RELEASED' | 'SETTLED' | 'PARTIALLY_SETTLED' | 'FAILED' | 'RETURNED', required: Leg-level and financial. "Delayed settlement" is a settlement value with the parent still PROCESSING, never a business status. - `reconciliation_summary` 'ALL_MATCHED' | 'PARTIAL_MATCH' | 'HAS_BREAK', required: Derived, visibility only. Never blocks transaction_status. - `payment_flow_id` string, nullable: Relates independent transactions in one flow. One completing never completes another. - `resource_version` integer: Monotonic per resource. Apply events in this order. - `created_at` string, date-time - `updated_at` string, date-time - `id` string - `customerId` string - `type` 'fiat' | 'crypto' - `transaction_subtype` string - `rail` string: The rail the deposit arrived on, such as spei, cbu, breb or pix. - `reference` string, nullable - `settled_at` string, date-time, nullable - `instrument` object - `type` 'virtual_account' | 'deposit_address' - `id` string - `ingestion_mode` 'announced' | 'unannounced' - `match` MatchRecord: Persisted at decision time. Attribution is never recomputed. - `depositIntentId` string, nullable - `match_method` 'REFERENCE' | 'EXACT_AMOUNT' | 'CLOSEST_AMOUNT' | 'FIFO_TIEBREAK' | 'ID_TIEBREAK' | 'UNANNOUNCED' | 'PENDING_ALLOCATION' - `amount_outcome` 'EXACT' | 'UNDER' | 'OVER' | 'null', nullable - `candidate_count` integer - `deviation_pct` string, nullable - `tie_breaker_used` boolean - `policy_version` string - `evaluated_at` string, date-time - `reason_code` 'reference_conflict' | 'reference_stale' | 'consequences_differ' | 'no_eligible_balance' | 'null', nullable - `unexpectedDeposit` boolean - `amount` Money - `value` string, required - `currency` 'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT', required: Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require `chain`. - `amounts` object: Gross, fees, rounding and net, recorded separately and never as one net figure. - `gross` Money - `value` string, required - `currency` 'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT', required: Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require `chain`. - `fees` Fee[] - `type` 'provider' | 'network' | 'alfred' | 'conversion' | 'payout' - `amount` string - `currency` string - `rounding_residual` string - `net_credited` Money - `value` string, required - `currency` 'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT', required: Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require `chain`. - `sender` Sender - `name` string - `bank_name` string - `account_last4` string - `rail` 'ACH' | 'WIRE' | 'SPEI' | 'PIX' | 'COELSA' | 'FPS' | 'CHATS' | 'WALLET': The scheme family a payment moves on. Never a country, provider or account identifier. `ACH` is any domestic batch bank transfer (US ACH, and the local clearing houses of COL, CHL, PER, BOL, PRY, DOM, CHN); `WIRE` is RTGS/SWIFT/Fedwire; `SPEI`, `PIX`, `COELSA`, `FPS` and `CHATS` are named instant schemes with their own semantics (COELSA is Argentina's instant transfer, deliberately not folded into ACH); `WALLET` is a stablecoin destination. Cash pickup is not in this release and has no rail value yet. Which rails a destination supports is derived by Alfred and returned as `supportedRails[]`; which `(country, currency, rail)` combinations are live is published by `GET /v1/countries/{country}`. - `rail_reference` string - `converted` object, nullable: The settled rate and fee. The only place the collection rate is disclosed. - `asset` string - `chain` 'SOL' | 'ETH' | 'MATIC' | 'BASE' | 'ARB' | 'OP' | 'AVAX' | 'BNB' | 'TRX' | 'XLM' | 'CELO' - `amount` string - `quotedRate` string - `executionRate` string - `rateVariance` string - `marginBps` integer - `developerFee` Money - `value` string, required - `currency` 'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT', required: Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require `chain`. - `provider_reference` string, nullable - `chain_tx_hash` string, nullable ## Other responses - `404`: Not on this host. Simulators exist only on the sandbox. - `409`: `idempotency_conflict`, or the resource is in a state that forbids this call. ## Changes - **2026-11-03** `20fef4fd2ab3`: 1 info - endpoint added [Operation history](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/changes/v1/test/customers/:customerId/deposits/simulate/post.md) --- [API](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation.md) - [All operations](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/revisions/20fef4fd2ab3?raw)