DotsDocs
Apps

Deposit Funds into App Wallet

Deposit funds into an App wallet by ACH. The transfer may remain pending until the ACH deposit settles. Funds from a pending deposit are not available in the wallet.

POST
/v2/apps/{app_id}/deposit

Deposit funds into an App wallet by ACH. The transfer may remain pending until the ACH deposit settles. Funds from a pending deposit are not available in the wallet.

Authorization

api_key
headerAuthorizationBasic <token>

Path Parameters

app_id*string

The ID of the App.

Request Body

application/json
  1. body
amount*integer

The amount to deposit in cents.

idempotency_key?string

Idempotency key in UUID format.

Formatuuid
metadata?unknown

Optional metadata attached to the transfer.

Response Body

Created

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
  • 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""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/string/deposit' \  -H 'Content-Type: application/json' \  -d '{  "amount": 0}'
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"}