Sandbox-only endpoint that advances the state of test transfers and other resources so developers can simulate ACH processing, clearing, and failure scenarios on demand rather than waiting for real bank timing. Essential for end-to-end testing of money-movement flows before going live.
openapi: 3.1.0
info:
title: Dwolla API - Sandbox Simulations
description: Dwolla API Documentation
contact:
name: Dwolla Developer Relations Team
url: https://developers.dwolla.com
email: api@dwolla.com
version: '2.0'
termsOfService: https://www.dwolla.com/legal/tos/
license:
name: MIT
url: https://github.com/Dwolla/dwolla-openapi/blob/master/LICENSE
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base
servers:
- url: https://api.dwolla.com
description: Production server
- url: https://api-sandbox.dwolla.com
description: Sandbox server
security:
- clientCredentials: []
tags:
- name: sandbox simulations
description: Sandbox-only operations for simulating processing of bank transfers
paths:
/sandbox-simulations:
post:
tags:
- sandbox simulations
summary: Sandbox simulations (bank transfers, VAN transfers, or customer verification directives)
description: 'Sandbox-only endpoint with three modes:
**Simulate bank transfer processing** — Omit the body or send an empty JSON object. Processes
or fails
the last 500 bank transfers on the authorized application or Sandbox account (and initiated micro-deposits).
If webhooks are configured, events are delivered. If a bank-to-bank transaction involves two users,
call this twice to process debit and credit sides. Returns **200** with a HAL document including
`total`.
**Simulate VAN (virtual) transfers** — Send a JSON body with `type` set to `virtual` and a `transfers`
array (up to 10 items). External transfers are created and processed immediately. Returns **202
Accepted**.
**Simulate verification directives** — For a business Verified Customer in **`retry`** or **`document`**
status, send `type`: `customer-verification`, `_links.customer.href` pointing at that customer,
and
`errorCode` set to one of: `PersonalIDRequired`, `POBoxNotAllowed`, `AddressNotAssociatedWithBusiness`,
`EINDocumentRequired`. Returns **200** with HAL `_links.self` and `errorCode`. Then **GET** the
Customer;
the same code appears in `_embedded.errors` for end-to-end testing.
'
operationId: simulateBankTransferProcessing
x-speakeasy-name-override: simulate
x-codeSamples:
- lang: bash
source: 'POST https://api-sandbox.dwolla.com/sandbox-simulations
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/vnd.dwolla.v1.hal+json
Authorization: Bearer {Your access token}
'
parameters:
- $ref: '#/components/parameters/Accept'
requestBody:
required: false
description: 'Optional. For bank transfer processing, omit the body or send `{}`. For VAN simulation,
send `type`: `virtual` and a `transfers` array. For verification
directives, send `type`: `customer-verification`, `_links.customer`, and `errorCode` (see schema).
'
content:
application/vnd.dwolla.v1.hal+json:
schema:
$ref: '#/components/schemas/SandboxSimulationRequest'
responses:
'200':
description: 'Success. **Bank transfer processing** returns HAL with `total`. **Customer verification
directives**
return HAL `_links.self` and `errorCode` (retrieve the Customer for `_embedded.errors`).
'
content:
application/vnd.dwolla.v1.hal+json:
schema:
oneOf:
- $ref: '#/components/schemas/SandboxSimulationBankProcessingResponse'
- $ref: '#/components/schemas/SandboxSimulationCustomerVerificationResponse'
examples:
bankTransferProcessing:
summary: Bank transfer processing
value:
_links:
self:
href: https://api-sandbox.dwolla.com/sandbox-simulations
type: application/vnd.dwolla.v1.hal+json
resource-type: sandbox-simulation
total: 8
customerVerificationDirective:
summary: Customer verification directive simulation
value:
_links:
self:
href: https://api-sandbox.dwolla.com/sandbox-simulations
type: application/vnd.dwolla.v1.hal+json
resource-type: sandbox-simulation
errorCode: AddressNotAssociatedWithBusiness
'202':
description: 'Accepted. Virtual (VAN) transfer simulation: requested transfers were accepted
for immediate
processing in Sandbox.
'
'400':
description: 'Bad Request.
'
content:
application/vnd.dwolla.v1.hal+json:
schema:
$ref: '#/components/schemas/BadRequestError'
'401':
description: unauthorized
content:
application/vnd.dwolla.v1.hal+json:
schema:
type: object
properties:
code:
type: string
example: InvalidAccessToken
message:
type: string
example: Invalid access token.
'403':
description: forbidden
content:
application/vnd.dwolla.v1.hal+json:
schema:
type: object
properties:
code:
type: string
example: forbidden
message:
type: string
example: Not authorized to simulate transfer processing.
components:
schemas:
SandboxSimulationCustomerVerificationResponse:
title: SandboxSimulationCustomerVerificationResponse
description: 'Response when simulating customer verification directives (200 OK). Echoes the simulated
`errorCode`;
retrieve the Customer resource to inspect `_embedded.errors`.
'
type: object
required:
- _links
- errorCode
properties:
_links:
type: object
required:
- self
properties:
self:
$ref: '#/components/schemas/HalLink'
errorCode:
type: string
description: Verification directive that was simulated.
enum:
- PersonalIDRequired
- POBoxNotAllowed
- AddressNotAssociatedWithBusiness
- EINDocumentRequired
example: AddressNotAssociatedWithBusiness
SandboxSimulationCustomerVerificationRequest:
title: SandboxSimulationCustomerVerificationRequest
description: 'Simulate a verification directive for a business Verified Customer in Sandbox. The
customer must be in
`retry` or `document` status. After a successful call, retrieve the Customer resource; the given
`errorCode`
appears under `_embedded.errors`. See Dwolla documentation for verification directive meanings.
'
type: object
required:
- type
- _links
- errorCode
properties:
type:
type: string
const: customer-verification
description: Must be set to customer-verification for verification directive simulation.
_links:
type: object
required:
- customer
properties:
customer:
type: object
required:
- href
properties:
href:
type: string
format: uri
description: URL of the Sandbox customer to attach the simulated directive to.
example: https://api-sandbox.dwolla.com/customers/00000000-0000-0000-0000-000000000000
errorCode:
type: string
description: Verification directive to simulate for the linked customer.
enum:
- PersonalIDRequired
- POBoxNotAllowed
- AddressNotAssociatedWithBusiness
- EINDocumentRequired
example: AddressNotAssociatedWithBusiness
TransferAmount:
title: TransferAmount
type: object
required:
- value
- currency
properties:
value:
type: string
example: '5.00'
currency:
type: string
example: USD
SandboxSimulationBankProcessingRequest:
title: SandboxSimulationBankProcessingRequest
description: 'Omit the request body or send an empty JSON object (`{}`). Triggers processing (or
failure) for the last
500 bank transfers on the authorized application or Sandbox account, and initiated micro-deposits.
Successful response is 200 with a HAL body including total.
'
type: object
additionalProperties: false
SandboxSimulationBankProcessingResponse:
title: SandboxSimulationBankProcessingResponse
description: Response when simulating bank transfer processing (200 OK).
type: object
required:
- _links
- total
properties:
total:
type: integer
format: int32
example: 8
description: Count of bank transfers (and related items) affected by the simulation run.
_links:
type: object
required:
- self
properties:
self:
$ref: '#/components/schemas/HalLink'
BadRequestError:
title: BadRequestError
description: Error response schema for 400 Bad Request
type: object
required:
- code
- message
properties:
code:
type: string
example: BadRequest
message:
type: string
example: The request body contains bad syntax or is incomplete.
SandboxSimulationRequest:
title: SandboxSimulationRequest
description: 'Bank transfer processing (omit body or `{}`), VAN transfer simulation (`type` virtual
+ transfers), or
verification directive simulation (`type` customer-verification, customer link, and errorCode).
Typed bodies
are mutually exclusive; use only an omitted body or `{}` for bank processing.
'
oneOf:
- $ref: '#/components/schemas/SandboxSimulationVirtualAccountTransfersRequest'
- $ref: '#/components/schemas/SandboxSimulationCustomerVerificationRequest'
- $ref: '#/components/schemas/SandboxSimulationBankProcessingRequest'
HalLink:
title: HalLink
type: object
properties:
href:
type: string
example: https://api.dwolla.com
type:
type: string
example: application/vnd.dwolla.v1.hal+json
resource-type:
type: string
example: resource-type
SandboxSimulationVirtualTransferItem:
title: SandboxSimulationVirtualTransferItem
description: One simulated external (VAN) transfer in a sandbox-simulations request.
type: object
required:
- _link
- amount
properties:
_link:
type: object
description: Link wrapper for the destination funding source (Dwolla HAL-style single link).
required:
- destination
properties:
destination:
type: object
required:
- href
properties:
href:
type: string
format: uri
example: https://api-sandbox.dwolla.com/funding-sources/5880e310-675a-4ce3-87d9-a475cc565e09
amount:
$ref: '#/components/schemas/TransferAmount'
SandboxSimulationVirtualAccountTransfersRequest:
title: SandboxSimulationVirtualAccountTransfersRequest
description: 'Simulate Virtual Account Number (VAN) / external transfers in Sandbox. Up to 10 transfers
per request;
transfers are created and processed immediately. Successful response is 202 Accepted.
'
type: object
required:
- type
- transfers
properties:
type:
type: string
const: virtual
description: Must be set to virtual for VAN transfer simulation.
transfers:
type: array
description: Transfers to simulate (max 10 per request).
minItems: 1
maxItems: 10
items:
$ref: '#/components/schemas/SandboxSimulationVirtualTransferItem'
parameters:
Accept:
name: Accept
in: header
required: true
description: The media type of the response. Must be application/vnd.dwolla.v1.hal+json
schema:
type: string
enum:
- application/vnd.dwolla.v1.hal+json
default: application/vnd.dwolla.v1.hal+json
securitySchemes:
clientCredentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: /token
x-speakeasy-token-endpoint-authentication: client_secret_basic
scopes: {}