Skip to main content
POST
Create a sandbox deposit

Overview

This sandbox-only endpoint creates a mock deposit for an existing customer or merchant funding account. Set funding_account_scope to tell Daya which kind of funding account the ID belongs to. Daya uses only the selected account store; it does not search customer and merchant funding accounts for a match.
  • CUSTOMER (default): Runs the simulated deposit through the customer funding-account settlement and webhook flow.
  • MERCHANT: Creates a merchant funding deposit. Include currency: NGN and amount to credit a specific amount to withdrawal_balance_ngn. Include currency: USD and an optional amount to credit withdrawal_balance_usd. Omitting both preserves the legacy 10 USD simulation.
For customer funding accounts, Daya runs the simulated deposit through the same processing pipeline as a real deposit:
  • Deposit creation
  • Settlement to internal balance, onchain payout, or NGN payout
  • Webhook dispatch
You can also pass scenario to trigger a specific sandbox lifecycle outcome. Use scenarios when you need to confirm your app handles specific deposit states without waiting for the sandbox processor to produce them naturally. For a customer funding account, create the receive instruction with /v1/funding-accounts, then pass its id. For merchant funding, call GET /v1/merchant/funding, pass data.id, and set funding_account_scope to MERCHANT.
This endpoint is available only in sandbox. Calls outside sandbox return 403.
For end-to-end guidance (recommended flow, what to validate, and common flagging scenarios), see Sandbox testing.

Authentication

string
required
Your merchant API key
string
Required when funding_account_scope is MERCHANT. Use a unique value for each simulated deposit and reuse the same value when retrying that request. Retries with the same value resume the original deposit instead of crediting the merchant balance again.

Request Body

string
required
Funding account ID to simulate a deposit for. For customer funding, use the id returned by /v1/funding-accounts. For merchant funding, use data.id from GET /v1/merchant/funding.Example: 6b0e8400-e29b-41d4-a716-446655440000
string
default:"CUSTOMER"
Selects the funding account kind. Allowed values are CUSTOMER and MERCHANT. Omit this field for existing customer funding-account simulations.
string
Merchant funding simulations only. Allowed values are NGN and USD. NGN credits withdrawal_balance_ngn; USD credits withdrawal_balance_usd. Omit this field to preserve the legacy USD simulation.
string
Merchant funding simulations only. A positive decimal amount in the selected currency. Required when currency is NGN; optional for USD, which defaults to 10 when omitted. NGN supports at most two decimal places and USD supports at most six.
string
Optional sandbox lifecycle outcome to trigger.Allowed values:
  • DEFAULT
  • PROCESSING
  • COMPLETED
  • REQUIRES_REVIEW
  • FAILED
Omit this field to use the default sandbox processing flow.
string
Optional linked payout outcome for customer funding accounts. Allowed values are DEFAULT, PROCESSING, SETTLED, and FAILED. This field is not supported when funding_account_scope is MERCHANT.

Request Examples

Response

Returns a confirmation message and the simulated deposit status. For customer funding accounts, use /v1/deposits and webhook events to track the deposit.
  • message: Human-readable status message
  • deposit_id: Created deposit ID
  • status: Current deposit status
  • scenario: Scenario that was applied, if provided

Customer funding lifecycle outcomes

Use scenario to test the state machine in your integration:
Scenario outcomes are for testing a specific lifecycle state in sandbox. PROCESSING and COMPLETED still use the funding account’s active settlement destination, so the funding account must include any required rate_id, destination wallet, or destination bank details. To test the production-like settlement processor and any natural intermediate states, omit scenario.

Merchant funding outcomes

Merchant funding simulations do not use the customer settlement destination or payout_scenario. An NGN simulation directly credits the merchant’s NGN withdrawal balance and requires an active sandbox NGN merchant funding account.

Error Responses

This endpoint may return:
  • 400: Invalid request
  • 401: Unauthorized
  • 403: Not available outside sandbox
  • 404: Funding account not found
  • 500: Internal server error

Next Steps

Get merchant funding

Get the merchant funding account ID and Base address

Webhooks Overview

Verify your webhook handling with sandbox events

Sandbox testing

Recommended end-to-end sandbox flow + common flagging scenarios