DotsDocs
Apps

Simulate an App Deposit (Sandbox)

Sandbox only. Credits the App as if a deposit reached its ACH deposit details, through the same refill path a real deposit takes. Creates Sandbox deposit details first if the App has none. Requires organization credentials.

POST
/v2/apps/{app_id}/simulate/deposit

Sandbox only. Credits the App as if a deposit reached its ACH deposit details, through the same refill path a real deposit takes. Creates Sandbox deposit details first if the App has none.

Requires organization credentials.

Authorization

api_key
headerAuthorizationBasic <token>

Path Parameters

app_id*string

Id of the App

Formatuuid

Request Body

application/json
  1. body
amount*integer

Amount in cents, up to $1,000,000.

Range1 <= value <= 100000000
rail?string

How the deposit arrives. Deposit details generated in the Dashboard accept ach and rtp. Details set up by Dots for wire funding accept ach and wire.

Default"ach"
Value in"ach""wire""rtp"
returned?boolean

Return the deposit after it credits the App. The refill fails and the credit is taken back out of the App's wallet.

Defaultfalse

Response Body

The refill, completed or, when returned is set, failed.

application/json
  1. response
id?string
Formatuuid
created?string
Formatdate-time
user_id?string
Formatuuid
status?string
Value in"created""pending""failed""completed""reversed""canceled""flagged"
error?string

Why this transfer failed, as a stable Dots code. These codes are ours, not the payout provider's, so they stay the same no matter how a payout is routed. Branch on this rather than on error_message.

  • account_closed - the receiving account is closed
  • account_not_found - the receiving account could not be found
  • invalid_account_details - the receiving account details are invalid; collect them again
  • name_mismatch - the recipient's name does not match the name on the receiving account
  • account_blocked - the receiving account cannot accept this transfer
  • transfer_refused - the receiving bank refused the transfer
  • insufficient_funds - the account had insufficient funds
  • limit_exceeded - the transfer exceeds a limit on the receiving account
  • amount_too_small - the amount is below the minimum for this destination
  • amount_too_large - the amount is above the maximum for this destination
  • destination_not_supported - this payout destination is not supported; the recipient needs a different payout method
  • recipient_info_required - more recipient information is required before this transfer can be sent
  • recipient_action_required - the recipient must sign in to their payout account and choose how to receive this transfer
  • recipient_account_incomplete - the recipient must finish setting up or verifying their external payout account, outside of Dots, before they can receive this transfer
  • declined_for_risk - the transfer was declined
  • card_unusable - the receiving card cannot accept this transfer
  • temporarily_unavailable - the transfer could not be completed; retrying may succeed
  • unknown - the transfer could not be completed, and we have no more specific code for it New codes may be added over time, so treat an unrecognized code the way you treat unknown. Omitted entirely when the transfer has no error, and always present when error_message is.
Value in"account_closed""account_not_found""invalid_account_details""name_mismatch""account_blocked""transfer_refused""insufficient_funds""limit_exceeded""amount_too_small""amount_too_large""destination_not_supported""recipient_info_required""recipient_action_required""recipient_account_incomplete""declined_for_risk""card_unusable""temporarily_unavailable""unknown"
error_message?string

Why this transfer failed, as a sanitized message safe to show to the recipient. The wording is not part of the API contract and may change at any time, so do not parse it or compare against it. Branch on error instead. Omitted entirely when the transfer has no error.

sender_details?|

Who sent the money for a refill that arrived from an outside bank account by ACH, RTP, FedNow or wire, as reported by the sending bank. Only present on refill transfers. null when no sender details were reported, such as for a wire Dots credited manually or a refill you created through the API. Any field may be null when the sending bank did not report it.

type?string

The type of this transfer.

  • refill - refill of an API App or Organization's Dots Wallet
  • payout - payout to a User
  • balance - balance transfer between Dots Wallets, such as from an API App to a User's Dots Wallet
  • payment - payment from a User to an API App
  • verification_debit - $1 debit from a User's bank account that verifies it during onboarding
  • settlement - legacy, currently unused
  • payable - payable for Accounts Payable
Value in"refill""payout""balance""payment""verification_debit""settlement""payable"
amount?string

Transfer amount in cents.

external_data?
transactions?array<>
payout_link_id?string

ID of the payout-link that the transfer belongs to.

Formatuuid
metadata?||

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Example Request
curl -X POST 'https://api.dots.dev/api/v2/apps/497f6eca-6276-4993-bfeb-53cbbbba6f08/simulate/deposit' \  -H 'Content-Type: application/json' \  -d '{  "amount": 1}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "created": "2019-08-24T14:15:22Z",  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",  "status": "created",  "error": "account_closed",  "error_message": "string",  "sender_details": {    "name": "string",    "bank_name": "string",    "routing_number": "string",    "account_number_last4": "string",    "company_identification": "string",    "trace_number": "string",    "reference": "string",    "memo": "string"  },  "type": "refill",  "amount": "string",  "external_data": {    "account_id": "string",    "external_id": "string",    "platform": "ach"  },  "transactions": [    {      "id": 0,      "amount": "string",      "created": "2019-08-24T14:15:22Z",      "source_name": "string",      "destination_name": "string",      "type": "balance",      "metadata": "string",      "transfer_id": "d4a2d8dd-7def-4545-a062-761683b9aa05",      "transfer": {}    }  ],  "payout_link_id": "50673cb3-bf8b-4fdc-9f5f-114b168da4ab",  "metadata": "string"}