openapi: 3.0.3
info:
  title: api-onboarding Account Usage Withdrawal Accounts API
  version: v1
  description: Manage withdrawal accounts
servers:
- url: /onboarding
  description: Relative URL
- url: https://api.currencycloud.com/onboarding
  description: Production server (uses live data)
- url: https://devapi.currencycloud.com/onboarding
  description: Dev server (uses test data)
tags:
- name: Withdrawal Accounts
  description: Manage withdrawal accounts
paths:
  /withdrawal_accounts/find:
    get:
      tags:
      - Withdrawal Accounts
      x-api-group: manage
      summary: Find Withdrawal Account
      description: Lists all withdrawal accounts assigned to an account.
      operationId: FindWithdrawlAccount
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: account_id
        in: query
        required: false
        type: string
        description: The UUID of a sub-account you want to see the withdrawal accounts for. If omitted the withdrawal accounts for the house account and all sub-accounts are returned.
        format: uuid
      responses:
        '200':
          description: Success.
          schema:
            type: object
            properties:
              withdrawal_accounts:
                type: array
                items:
                  $ref: '#/definitions/WithdrawalAccount'
              pagination:
                $ref: '#/definitions/Pagination'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: account_id_is_not_valid_uuid
            category: account_id
            message: account_id should be in UUID format
            params: ''
          schema:
            $ref: '#/definitions/GetWithdrawalAccountError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          schema:
            $ref: '#/definitions/UnauthorizedError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '403':
          description: Forbidden.
          x-errors:
          - code: permission_denied
            message: permission_denied
            params: ''
          schema:
            $ref: '#/definitions/ForbiddenError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '404':
          description: Resource not found.
          x-errors:
          - code: account_not_found
            message: Account was not found for this id
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '429':
          description: Too many requests.
          x-errors:
          - code: too_many_requests
            category: base
            message: Too many requests have been made to the api. Please refer to the Developer Center for more information
            params: ''
          schema:
            $ref: '#/definitions/RateLimitError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
  /withdrawal_accounts/{withdrawal_account_id}/pull_funds:
    post:
      tags:
      - Withdrawal Accounts
      x-api-group: manage
      summary: Pull Funds From Withdrawal Account
      description: Submits an ACH pull request from a specific withdrawal account. The funds will be pulled into the account the specified withdrawal account is related to.
      operationId: PullFundsFromWithdrawalAccount
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: withdrawal_account_id
        in: path
        required: true
        type: string
        description: The withdrawal account ID you want to pull the funds from. The funds will be pulled into the account ID related to this withdrawal account.
        format: uuid
      - name: reference
        in: formData
        required: true
        type: string
        description: The reference you want on the statement.
        minLength: 1
        maxLength: 255
      - name: amount
        in: formData
        required: true
        type: number
        description: The amount of funds to pull in USD.
        pattern: ^\d+(\.\d{1,3})?$
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/WithdrawalPullFundsRequestDetails'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: withdrawal_account_not_found
            category: id
            message: No withdrawal account found for this account
            params: ''
          - code: withdrawal_account_id_is_not_valid_uuid
            category: id
            message: withdrawal_account_id should be in UUID format
            params: ''
          - code: reference_is_required
            category: reference
            message: reference is required
            params: ''
          - code: reference_invalid
            category: reference
            message: Only characters, digits, spaces, '_' and '-' allowed
            params: ''
          - code: reference_too_long
            category: reference
            message: Reference cannot be longer than 10 characters
            params: ''
          - code: amount_is_required
            category: amount
            message: amount is required
            params: ''
          - code: amount_is_in_invalid_format
            category: amount
            message: amount should be of numeric type with 2 dp
            params: '{ "type" => "numeric_with_precision", "precision" => 2 }'
          - code: amount_not_positive
            category: amount
            message: Amount should be positive
            params: ''
          - code: amount_not_allowed
            category: amount
            message: Amount should be up to 100000 limit
            params: ''
          schema:
            $ref: '#/definitions/WithdrawalPullFundsRequestError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          schema:
            $ref: '#/definitions/UnauthorizedError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '403':
          description: Forbidden.
          x-errors:
          - code: permission_denied
            message: Permission denied
            params: ''
          schema:
            $ref: '#/definitions/ForbiddenError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '404':
          description: Resource not found.
          x-errors:
          - code: account_not_found
            message: Account was not found for this id
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '429':
          description: Too many requests.
          x-errors:
          - code: too_many_requests
            category: base
            message: Too many requests have been made to the api. Please refer to the Developer Center for more information
            params: ''
          schema:
            $ref: '#/definitions/RateLimitError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
components:
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: X-Auth-Token
definitions:
  RateLimitError:
    type: object
    description: Too many requests.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this validation/error.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
  WithdrawalPullFundsRequestError:
    type: object
    description: 'Client error information for the Post WithdrawalAccount PullFunds endpoint.

      '
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
  UnauthorizedError:
    type: object
    description: Authorization error.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
        enum:
        - auth_failed
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
    example:
      error_code: auth_failed
      error_messages:
        api_key:
        - code: invalid_supplied_credentials
          message: Authentication failed with the supplied credentials
          params: {}
  GetWithdrawalAccountError:
    type: object
    description: 'Client error information for the Get WithdrawalAccount endpoint.

      '
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
  ForbiddenError:
    type: object
    description: Permission error.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
        enum:
        - auth_failed
      error_messages:
        type: object
        description: Detailed error information on what permissions are missing so that the request could not be fulfilled
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents the reasons why the request was not permitted.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
  WithdrawalPullFundsRequestDetails:
    type: object
    description: Details of a Withdrawal Pull Request.
    required:
    - id
    - withdrawal_account_id
    - reference
    - amount
    - created_at
    additionalProperties: false
    properties:
      id:
        type: string
        description: The ID for the Pull Request.
      withdrawal_account_id:
        type: string
        description: The ID of the withdrawal account to pull funds from.
      reference:
        type: string
        description: The reference provided at the time the request was made.
      amount:
        type: string
        description: The amount to be pulled from the withdrawal account.
      created_at:
        type: string
        format: date-time
        description: Date the pull funds request record was created.
    example:
      id: 82214b7e-9192-4d9e-82cf-e2c4b1670f23
      withdrawal_account_id: ffb9fdea-312b-4bc8-beb9-5e44ee2d2a8c
      reference: Reference
      amount: 1000.0
      created_at: '2019-04-18T08:17:22+00:00'
  WithdrawalAccount:
    type: object
    description: Withdrawal account
    required:
    - id
    - account_name
    - account_holder_name
    - account_holder_dob
    - routing_code
    - account_number
    - currency
    - account_id
    additionalProperties: false
    properties:
      id:
        type: string
        description: The UUID of the withdrawal account.
      account_name:
        type: string
        description: The name of the withdrawal account.
      account_holder_name:
        type: string
        description: The name of the withdrawal account holder.
      account_holder_dob:
        type: string
        format: date
        description: The DOB of the withdrawal account holder.
      routing_code:
        type: string
        description: The routing code of the withdrawal account.
      account_number:
        type: string
        description: The account number of the withdrawal account.
      currency:
        type: string
        description: The currency of the withdrawal account.
      account_id:
        type: string
        description: The UUID of the CurrencyCloud account the withdrawal account is linked to.
    example:
      id: ffb9fdea-312b-4bc8-beb9-5e44ee2d2a8c
      account_name: TestAccount
      account_holder_name: John Smith
      account_holder_dob: '1987-05-12'
      routing_code: 987654321
      account_number: 0123456789
      currency: USD
      account_id: 82214b7e-9192-4d9e-82cf-e2c4b1670f23
  Pagination:
    type: object
    description: Pagination.
    properties:
      total_entries:
        type: integer
      total_pages:
        type: integer
      current_page:
        type: integer
      per_page:
        type: integer
        description: Number of results per page.
      previous_page:
        type: integer
      next_page:
        type: integer
      order:
        type: string
        description: The field name by which the results are sorted.
      order_asc_desc:
        type: string
        enum:
        - asc
        - desc
        default: asc
        description: Whether results are sorted in ascending or descending order.
    example:
      total_entries: 1
      total_pages: 1
      current_page: 1
      per_page: 25
      previous_page: -1
      next_page: 2
      order: created_at
      order_asc_desc: asc