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: {}