swagger: '2.0'

info:
  title: Transactions

  description: >-
    The Transactions API manages banking account transactions for bank customers.


    The Transactions API can view account
    transaction history for accounts held at the current financial instuitution.
    The `/transactions` collection lists all transactions, both pending and completed.
    For accounts with transaction history, the user can view those transactions
    via the `/history` endpoint (the `getHistory` operation.)
    Pending transactions are managed in a separate collection, under `/scheduledTransactions`
    (via the `getScheduledTransactions` operation.)


    Note that the queries to filter transactions do not use
    the actual account numbers:

    ```
       GET /transactions/history?account=0399abed-fd3d-4830-a88b-30f38b8a365c
    ```

    For security, these queries only filter based on
    the opaque account resource ID, which is decoupled from the account number.
    Thus, account numbers do not appear in the request URLs or in web traffic logs.

  version: 0.2.0

  contact:
    name: Apiture
    url: 'https://developer.aptiture.com'
    email: api@apiture.com

  termsOfService: 'TODO: Terms of Service is TBD; need input from Legal team.'

schemes:
  - https

basePath: /transactions

consumes:
  - application/hal+json
  - application/json

produces:
  - application/hal+json
  - application/json

tags:
  - name: API
    description: Endpoints Which Describe This API
  - name: Transactions
    description: Bank Account Transactions
  - name: Scheduled Transactions
    description: Bank Account Scheduled Transactions
  - name: History
    description: Bank Account Past Transactions

paths:
  '/transactions':
    get:
      summary: Return a collection of pending and completed transactions.
      description: >-
        Return a [paginated](http://doc.apiture.com/api/concepts/pagination) [sortable](http://doc.apiture.com/api/concepts/sorting) [filterable](http://doc.apiture.com/api/concepts/filtering) [searchable](http://doc.apiture.com/api/concepts/searchable) collection
        of pending and completed transactions. The [links](http://doc.apiture.com/api/concepts/links)
        in the response include pagination links.


        **Note**: At present, there is no way to add new transactions or
        to update or delete existing transactions.
      operationId: getTransactions
      x-apiture-implemented: true
      tags:
        - Transactions
      parameters:
        - name: start
          in: query
          description: >-
            The zero-based index of the first transaction in this page. The
            default, 0, represents the first page of the collection.
          type: integer
          format: int64
          default: 0
        - name: limit
          in: query
          description: >-
            The maximum number of transaction representations to return in this page.
          type: integer
          format: int32
          default: 100
        - name: sortBy
          in: query
          type: string
          description: >-
            Optional sort criteria. See [sort criteria
            format](http://docs.apiture.com/api/concepts/sorting#criteria), such
            as `?sortBy=field1,-field2`.
        - $ref: '#/parameters/filterQueryParam'
        - $ref: '#/parameters/qQueryParam'
        - $ref: '#/parameters/accountQueryParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/transactions'
        '400':
          $ref: '#/responses/400'
        '422':
          $ref: '#/responses/422'

  '/transactions/{transactionId}':
    get:
      summary: Fetch a representation of this transaction
      description: >-
        Return a [HAL](http://docs.apiture.com/api/concepts/hal) representation of this transaction resource.
      operationId: getTransaction
      x-apiture-implemented: true
      tags:
        - Transactions
      parameters:
        - $ref: '#/parameters/transactionIdPathParam'
        - $ref: '#/parameters/unmaskedQueryParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/transaction'
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be
                provided in an `If-Match` request header for *`PUT`* or
                *`PATCH`* operations which update this resource.
              type: string
        '304':
          $ref: '#/responses/304'
        '404':
          $ref: '#/responses/404Transaction'

  '/scheduledTransactions':
    get:
      summary: Return a collection of scheduled transactions
      description: >-
        Return a [paginated](http://doc.apiture.com/api/concepts/pagination) [sortable](http://doc.apiture.com/api/concepts/sorting) [filterable](http://doc.apiture.com/api/concepts/filtering) [searchable](http://doc.apiture.com/api/concepts/searchable) collection
        of transactions. The [links](http://doc.apiture.com/api/concepts/links)
        in the response include pagination links.


        **Note**: At present, there is no way to add new transactions or
        to update or delete existing scheduled transactions.
      operationId: getScheduledTransactions
      x-apiture-implemented: true
      tags:
        - Scheduled Transactions
      parameters:
        - name: start
          in: query
          description: >-
            The zero-based index of the first transaction in this page. The
            default, 0, represents the first page of the collection.
          type: integer
          format: int64
          default: 0
        - name: limit
          in: query
          description: >-
            The maximum number of transaction representations to return in this page.
          type: integer
          format: int32
          default: 100
        - name: sortBy
          in: query
          type: string
          description: >-
            Optional sort criteria. See [sort criteria
            format](http://docs.apiture.com/api/concepts/sorting#criteria), such
            as `?sortBy=field1,-field2`.
        - $ref: '#/parameters/filterQueryParam'
        - $ref: '#/parameters/qQueryParam'
        - $ref: '#/parameters/accountQueryParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/scheduledTransactions'
        '400':
          $ref: '#/responses/400'
        '422':
          $ref: '#/responses/422'

  /history:
    get:
      summary: Return a collection of past transactions
      description: >-
        Return a [paginated](http://doc.apiture.com/api/concepts/pagination) [sortable](http://doc.apiture.com/api/concepts/sorting) [filterable](http://doc.apiture.com/api/concepts/filtering) [searchable](http://doc.apiture.com/api/concepts/searchable) collection
        of transactions. The [links](http://doc.apiture.com/api/concepts/links)
        in the response include pagination links.

        Transactions in the history are immutable and not deletable.
      operationId: getHistory
      x-apiture-implemented: true
      tags:
        - History
      parameters:
        - name: start
          in: query
          description: >-
            The zero-based index of the first transaction in this page. The
            default, 0, represents the first page of the collection.
          type: integer
          format: int64
          default: 0
        - name: limit
          in: query
          description: >-
            The maximum number of transaction representations to return in this page.
          type: integer
          format: int32
          default: 100
        - name: sortBy
          in: query
          type: string
          description: >-
            Optional sort criteria. See [sort criteria
            format](http://docs.apiture.com/api/concepts/sorting#criteria), such
            as `?sortBy=field1,-field2`.
        - $ref: '#/parameters/filterQueryParam'
        - $ref: '#/parameters/qQueryParam'
        - $ref: '#/parameters/accountQueryParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/pastTransactions'
        '400':
          $ref: '#/responses/400'
        '422':
          $ref: '#/responses/422'

  /:
    get:
      summary: Top-level resources and operations in this API
      description: >-
        Return links to the top-level resources and operations in this API. This
        API returns the following links:
        *`apiture:accounts`* : links to the collection of accounts held at this
        financial institution
      operationId: getApi
      x-apiture-implemented: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/root'
          examples:
            application/hal+json:
              id: accounts
              name: User Bank Accounts
              apiVersion: 0.1.0
              _profile: 'https://api.apiture.com/schemas/apiRoot/v.0.1.0/profile.json'
              _links:
                'apiture:transactions':
                  href: /transactions/transactions
      tags:
        - API
  /apiDoc:
    get:
      summary: Return API definition document
      description: Return the OpenAPI document that describes this API.
      operationId: getApiDoc
      x-apiture-implemented: true
      produces:
        - application/json
        - application/openapi+json;version=2.0
        - application/openapi+yaml;version=2.0
      responses:
        '200':
          description: OK
          schema:
            type: object
      tags:
        - API

parameters:
  transactionIdPathParam:
    name: transactionId
    description: >-
      The unique identifier of this transaction. This is an opaque string.
      This string is not the same as the bank's core transaction ID;
      it is simply the resource ID for referencing the transaction resource
      via the API.
    in: path
    type: string
    required: true

  filterQueryParam:
    name: filter
    in: query
    description: >-
      Optional filter criteria. See
      [filtering](http://docs.apiture.com/api/concepts/filtering#criteria).
    type: string

  qQueryParam:
    name: q
    in: query
    description: >-
      Optional search string. See
      [searching](http://docs.apiture.com/api/concepts/searching).
    type: string

  accountQueryParam:
    name: account
    in: query
    required: false
    type: string
    description: >-
      A list of server-supplied values which identify the account instances, i.e. ?account=acct1|acct2|acct3.

  unmaskedQueryParam:
    name: unmasked
    description: >-
      When requesting a transaction, the full account number is not
      included in the response by default, for security reasons.
      Include this query parameter, with a value of `true`, to
      request that the response body includes the full account
      number. Such requests are auditable.
    type: boolean
    in: query
    required: false
    default: false

responses:
  '304':
    description: >-
      Not Modified. The resource has not been modified since it was last
      fetched.
  '400':
    description: >-
      Bad Request. 
      The request body or one or more of the query parameters was not well
      formed.  The `_error` field in the response will contain details about the
      request error.
    schema:
      $ref: '#/definitions/errorResponse'

  '422':
    description: >-
      Unprocessable Entity. One or more of the query parameters was well formed
      but otherwise invalid. The `_error` field in the response will contain
      details about the request error.
    schema:
      $ref: '#/definitions/errorResponse'

  404Transaction:
    description: >-
      Not Found. There is no such transaction resource at the specified
      `{transactionId}` The `_error` field in the response will contain details
      about the request error.
    schema:
      $ref: '#/definitions/error'
    x-apiture-errors:
      - transactionNotFound

definitions:
  transactionType:
    title: Transaction Type
    description: >-
      *`type`* should indicate the type of the transaction (not what is allowed for the account). i.e.

      *`credit`* - the transaction was a credit posted to the account, such as transfer funds _to_ this account or interested posted to the account

      *`debit`* - the transaction debited funds from the account, such as a check written against an account.

    type: string
    enum:
      - debit
      - credit

  transactionFields:
    title: Transaction Fields
    description: Core fields of the transaction resource.
    allOf:
      - $ref: '#/definitions/abstractResource'
      - type: object
        required:
          - amount
          - state
          - type
          - providerSummary
          - transactionCode
        properties:
          _id:
            description: >-
              The unique identifier for this approval resource. This is an
              immutable opaque string.
            type: string
          amount:
            description: The amount of the transaction.
            allOf:
              - $ref: '#/definitions/money'
          state:
            description: The status of the transaction.
            type: string
            enum:
              - pending
              - completed
              - reversed
          type:
            $ref: '#/definitions/transactionType'
          subtype:
            description: A subtype, more specific transaction type.
            type: string
          providerSummary:
            description: Human readable version of the transaction description.
            type: string
          summary:
            description: A cleansed version of the `providerSummary`.
            type: string
          description:
            description: This field contains additional descriptive information about the transaction.
            type: string
          sourceAccountNumbers:
            description: The account number returned from the core.
            allOf:
              - $ref: '#/definitions/accountNumbers'
          sourceAccountName:
            description: The account name returned from the core.
            type: string
          targetAccountNumbers:
            description: The account number returned from the core.
            allOf:
              - $ref: '#/definitions/targetAccountNumbers'
          targetAccountName:
            description: The account name returned from the core.
            type: string
          transactionCode:
            description: The transaction code returned from the core.
            type: string
          schedule:
            description: Describes when the transaction is scheduled to occur.
            allOf:
              - $ref: '#/definitions/schedule'
          postedOn:
            description: >-
              The date when the transaction was completed.
              This property is set only if the state is completed.
            type: string
            format: date
          reversedOn:
            description: >-
              The date when the transaction was reversed. 
              This property is set only if the state is reversed.
            type: string
            format: date

  transaction:
    title: A transaction
    description: A transaction
    allOf:
      - $ref: '#/definitions/transactionFields'

  transactions:
    title: Transaction Collection
    description: >-
      Collection of transactions. The items in the collection are ordered in the
      `_embedded` object with name `items`. The top-level `_links` object may
      contain pagination links (`self`, `next`, `prev`, `first`, `last`,
      `collection`.)
    allOf:
      - $ref: '#/definitions/collection'
      - type: object
        properties:
          _embedded:
            type: object
            properties:
              items:
                description: An array containing a page of transaction items.
                type: array
                items:
                  $ref: '#/definitions/transaction'
    example:
      _profile: 'http://api.apiture.com/schemas/collection/transaction/v/profile.json'
      start: 10
      limit: 10
      count: 67
      name: transactions
      _links:
        self:
          href: /transactions/transactions?start=10&limit=10
        first:
          href: /transactions/transactions?start=0&limit=10
        next:
          href: /transactions/transactions?start=20&limit=10
        collection:
          href: /transactions/transactions
      _embedded:
        items:
          - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
            _profile: 'http://api.apiture.com/schemas/transaction/v/profile.json'
            _links:
              self:
                href: /transactions/scheduledTransactions/0399abed-fd3d-4830-a88b-30f38b8a365c
              'apiture:account':
                href: /transactions/accounts/86de587e-a5a7-11e8-98d0-529269fb1459
              'apiture:organization':
                href: /transactions/organizations/86de587e-a5a7-11e8-98d0-529269fb1459
            amount:
              value: '35.00'
              currency: 'USD'
            schedule:
              start: '2018-01-01'
            state: 'pending'
            type: 'debit'
            providerSummary: 'gas station'

          - _id: d62c0701-0d74-4836-83f9-ebf3709442ea
            _profile: 'http://api.apiture.com/schemas/transaction/v/profile.json'
            _links:
              self:
                href: /transactions/scheduledTransactions/d62c0701-0d74-4836-83f9-ebf3709442ea
              'apiture:account':
                href: /transactions/accounts/86de587e-a5a7-11e8-98d0-529269fb1459
              'apiture:organization':
                href: /transactions/organizations/86de587e-a5a7-11e8-98d0-529269fb1459
            amount:
              value: '1000.00'
              currency: 'USD'
            schedule:
              start: '2018-01-02'
            state: 'pending'
            type: 'debit'
            providerSummary: 'donation'

  collection:
    title: A collection of resources.
    description: A collection of resources.
    allOf:
      - $ref: '#/definitions/abstractResource'
      - type: object
        properties:
          count:
            description: The total number of items in the collection.
            type: integer
          start:
            description: The start index of this page of items.
            type: integer
          limit:
            description: The maximum number of items per page.
            type: integer
          name:
            description: The name of the collection.
            type: string

  scheduledTransactions:
    title: Scheduled Transaction Collection
    description: >-
      Collection of scheduled transactions. The items in the collection are ordered in the
      `_embedded` object with name `items`. The top-level `_links` object may
      contain pagination links (`self`, `next`, `prev`, `first`, `last`,
      `collection`.)
    allOf:
      - $ref: '#/definitions/collection'
      - type: object
        properties:
          _embedded:
            type: object
            properties:
              items:
                description: An array containing a page of transaction items.
                type: array
                items:
                  $ref: '#/definitions/transaction'
    example:
      _profile: 'http://api.apiture.com/schemas/collection/transaction/v/profile.json'
      start: 10
      limit: 10
      count: 67
      name: transactions
      _links:
        self:
          href: /transactions/scheduledTransactions?start=10&limit=10
        first:
          href: /transactions/scheduledTransactions?start=0&limit=10
        next:
          href: /transactions/scheduledTransactions?start=20&limit=10
        collection:
          href: /transactions/scheduledTransactions
      _embedded:
        items:
          - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
            _profile: 'http://api.apiture.com/schemas/transaction/v/profile.json'
            _links:
              self:
                href: /transactions/scheduledTransactions/0399abed-fd3d-4830-a88b-30f38b8a365c
              'apiture:account':
                href: /transactions/accounts/86de587e-a5a7-11e8-98d0-529269fb1459
              'apiture:organization':
                href: /transactions/organizations/86de587e-a5a7-11e8-98d0-529269fb1459
            amount:
              value: '35.00'
              currency: 'USD'
            schedule:
              start: '2018-01-01'
            state: 'pending'
            type: 'debit'
            providerSummary: 'gas station'

          - _id: d62c0701-0d74-4836-83f9-ebf3709442ea
            _profile: 'http://api.apiture.com/schemas/transaction/v/profile.json'
            _links:
              self:
                href: /transactions/scheduledTransactions/d62c0701-0d74-4836-83f9-ebf3709442ea
              'apiture:account':
                href: /transactions/accounts/86de587e-a5a7-11e8-98d0-529269fb1459
              'apiture:organization':
                href: /transactions/organizations/86de587e-a5a7-11e8-98d0-529269fb1459
            amount:
              value: '1000.00'
              currency: 'USD'
            schedule:
              start: '2018-01-02'
            state: 'pending'
            type: 'debit'
            providerSummary: 'donation'

  pastTransactions:
    title: Past Transaction Collection
    description: >-
      Collection of past transactions. The items in the collection are ordered in the
      `_embedded` object with name `items`. The top-level `_links` object may
      contain pagination links (`self`, `next`, `prev`, `first`, `last`,
      `collection`.)
    allOf:
      - $ref: '#/definitions/collection'
      - type: object
        properties:
          _embedded:
            type: object
            properties:
              items:
                description: An array containing a page of transaction items.
                type: array
                items:
                  $ref: '#/definitions/transaction'
    example:
      _profile: 'http://api.apiture.com/schemas/collection/transaction/v/profile.json'
      start: 10
      limit: 10
      count: 67
      name: transactions
      _links:
        self:
          href: /transactions/pastTransactions?start=10&limit=10
        first:
          href: /transactions/pastTransactions?start=0&limit=10
        next:
          href: /transactions/pastTransactions?start=20&limit=10
        collection:
          href: /transactions/pastTransactions
      _embedded:
        items:
          - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
            _profile: 'http://api.apiture.com/schemas/transaction/v/profile.json'
            _links:
              self:
                href: /transactions/pastTransactions/0399abed-fd3d-4830-a88b-30f38b8a365c
              'apiture:account':
                href: /transactions/accounts/86de587e-a5a7-11e8-98d0-529269fb1459
              'apiture:organization':
                href: /transactions/organizations/86de587e-a5a7-11e8-98d0-529269fb1459
            amount:
              value: '35.00'
              currency: 'USD'
            postedOn: '2018-01-01'
            state: 'completed'
            type: 'debit'
            providerSummary: 'gas station'

          - _id: d62c0701-0d74-4836-83f9-ebf3709442ea
            _profile: 'http://api.apiture.com/schemas/transaction/v/profile.json'
            _links:
              self:
                href: /transactions/pastTransactions/d62c0701-0d74-4836-83f9-ebf3709442ea
              'apiture:account':
                href: /transactions/accounts/86de587e-a5a7-11e8-98d0-529269fb1459
              'apiture:organization':
                href: /transactions/organizations/86de587e-a5a7-11e8-98d0-529269fb1459
            amount:
              value: '1000.00'
              currency: 'USD'
            postedOn: '2018-01-01'
            state: 'completed'
            type: 'debit'
            providerSummary: 'donation'

  abstractResource:
    title: Abstract Resource
    description: >-
      An augmented [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08)
      resource representation. This model contains hypermedia `_links`, and
      either optional domain object data with `_profile` and optional
      `_embedded` objects, or an `_error` object. In responses, if the operation
      was successful, this object will not include the `_error`, but if the
      operation was a 4xx or 5xx error, this object will not include `_embedded`
      or any data fields, only `_error` and optionally `_links`.
    example:
      _profile: 'http://api.apiture.com/schemas/example/v1.0.0/profile.json'
      _links:
        self:
          href: '{uri of current resource}'
    properties:
      _links:
        $ref: '#/definitions/links'
      _embedded:
        description: >-
          An optional map of nested resources, mapping each nested resource name
          to a nested resource representation.
        type: object
      _profile:
        description: >-
          The URI of a [resource
          profile](http://doc.apiture.com/api/concepts/resource-profile) which
          describes the representation.
        type: string
        format: uri
      _error:
        description: >-
          An object which describes an error. This value is omitted if the
          operation succeeded without error.
        type: object
        allOf:
          - $ref: '#/definitions/error'

  root:
    title: API Root
    description: >-
      A HAL response, with hypermedia `_links` for the top-level resources and
      operations in API.
    example:
      id: apiName
      name: API name
      apiVersion: 0.0.1-SNAPSHOT
      _profile: 'https://api.apiture.com/schemas/apiRoot/v1.0.0/profile.json'
      _links: {}
    allOf:
      - $ref: '#/definitions/abstractResource'
      - type: object
        properties:
          _id:
            type: string
            description: This API's unique ID.
          name:
            type: string
            description: This API's name.
          apiVersion:
            type: string
            description: This API's version.

  errorResponse:
    title: Error Response
    description: >-
      Describes an error response, typically returned on 4xx or 5xx
      errors from API operations. The `_error` object contains the error details.
    allOf:
      - $ref: '#/definitions/abstractResource'
    example:
      _profile: 'http://api.apiture.com/schemas/error/v1.0.0/.json'
      _error:
        _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
        _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json'
        message: The value for deposit must be greater than 0.
        statusCode: 422
        type: positiveNumberRequired
        attributes:
          value: -125.50
        remediation: Provide a value which is greater than 0
        occurredAt: 2018-01-25T05:50:52.375Z
        _links:
          describedby:
            href: 'http://doc.apiture.com/errors/positiveNumberRequired'
        _embedded:
          errors: []
  error:
    title: Error
    description: >-
      An error description. Nested source errors are
      contained in the `_embedded` object with the key `"errors"`; this
      is an array of nested error objects. For example, an API which
      validates its request body may find multiple errors in the
      request, which may be detailed here. The `_links` may contain
      a `describedby` link which refers to a web page with details
      about the error.

      The `attributes` field An optional map of name/value pairs which
      provide structured data about the error. For example, if the error
      is a value out of range, the attributes may specify the range
      values `min` and `max`. This allows clients to present error
      messages as they see fit (the API does not assume the
      client/presentation tier).
    required:
      - message

    properties:
      message:
        type: string
        description: A localized message string describing the error condition.
      _id:
        type: string
        description: >-
          A unique identifier for this error instance.
          This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error).
          This is is an opaque string.
      statusCode:
        description: The HTTP status code associate with this error.
        type: integer
        minimum: 100
        maximum: 599
        example: 422
      type:
        type: string
        description: >-
          An error identifier which indicates the category of error and associate it with
          API support documentation or which the UI tier can use to render an appropriate message or hint.
          This provides a finer level of granularity than the `statusCode`.
          For example, instead of just 400 Bad Request, the `type` may be much more specific.
          such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or `stringValueNotInAllowedSet`.
      occurredAt:
        type: string
        format: date-time
        description: An ISO 8601 UTC time stamp indicating when the error occurred.
        example: '2018-02-02T03:37:15.375Z'
      attributes:
        description: Data attribute associated with the error, such as values or constraints.
        allOf:
          - $ref: '#/definitions/attributes'
      remediation:
        type: string
        description: An optional localized string which provides hints for how the user or client can resolve the error.
      _embedded:
        description: Optional embedded array of errors. This field may not exist if the error does not have nested errors.
        type: object
        properties:
          items:
            description: An array of error objects.
            type: array
            items:
              $ref: '#/definitions/errorResponse'

    example:
      _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
      _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json'
      message: The value for deposit must be greater than 0.
      statusCode: 422
      type: positiveNumberRequired
      attributes:
        value: -125.50
      remediation: Provide a value which is greater than 0
      occurredAt: '2018-01-25T05:50:52.375Z'
      _links:
        describedby:
          href: 'http://doc.apiture.com/errors/positiveNumberRequired'
      _embedded:
        errors: []

  attributes:
    title: Attributes
    description: >-
      An optional map of name/value pairs which contains additional dynamic data
      about the resource.
    type: object

  links:
    title: Links
    description: >-
      An optional map of links, mapping each link relation to a link object.
      This model defines the `_links` object of HAL representations.
    type: object
    additionalProperties:
      $ref: '#/definitions/link'

  link:
    title: Link
    description: >-
      Describes a hypermedia link within a `_links` object in HAL
      representations. In Apiture APIs, links are [HAL
      links](https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5), but
      Apiture APIs do not use the `name` or `hreflang` properties of HAL.
      Apiture links _may_ include a `method` property.
    required:
      - href
    properties:
      href:
        type: string
        format: uri
        description: >-
          The URI or URI template for the resource/operation this link refers
          to.
      type:
        type: string
        description: The media type for the resource.
      templated:
        type: boolean
        description: >-
          If true, the link's href is a [URI
          template](https://tools.ietf.org/html/rfc6570).
      title:
        type: string
        description: An optional human-readable localized title for the link.
      deprecation:
        type: string
        format: uri
        description: >-
          If present, the containing link is deprecated and the value is a URI
          which provides human-readable text information about the deprecation.
      profile:
        type: string
        format: uri
        description: >-
          The URI of a profile document, a JSON document which describes the
          target resource/operation.

  money:
    description: An amount of money in a specific currency.
    properties:
      value:
        description: >-
          The net monetary value. A negative amount denotes a debit; a positive
          amount a credit. The numeric value is represented as a string so that
          it can be exact with no loss of precision.
        example: '3456.78'
        type: string
      currency:
        description: >-
          The [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217)
          for this monetary value. This is always upper case ASCII. TODO: ISO
          4217 defines three-character codes. However, ISO 4217 does not account
          for cryptocurrencies. Of note, DASH uses 4 characters.
        type: string
        minLength: 3
        maxLength: 3

  accountNumbers:
    title: Account Numbers
    description: Different representations of an account number.
    properties:
      masked:
        description: >-
          A partial account number that does not contain all the
          digits of the full account number. This masked number appears in
          statements or in user experience presentation. 
          It is sufficient for a user to differentiate this account from other
          accounts they hold, but is not sufficient for
          initiating transfers, etc. The first character is
          the mask character and is repeated; this
          does not indicate that the full account number
          is the same as the mask length.
          This value is derived and immutable.
        type: string
        minLength: 9
        maxLength: 32
        example: '*************3210'
      full:
        description: >-
          The full account number. This value only appears
          when ?unmasked=true is passed on the get request. 
          Not included in the summary representation of the 
          account that is included in account collection responses.
        type: string
        minLength: 9
        maxLength: 32
        example: '9876543210'

  targetAccountNumbers:
    title: Target Account Numbers
    description: The account numbers necessary to link an target account.
    properties:
      masked:
        description: >-
          A partial account number that does not contain all the
          digits of the full account number. This masked number appears in
          statements or in user experience presentation. 
          It is sufficient for a user to differentiate this account from other
          accounts they hold, but is not sufficient for
          initiating transfers, etc. The first character is
          the mask character and is repeated; this
          does not indicate that the full account number
          is the same as the mask length.
          This value is derived and immutable.
        type: string
        minLength: 9
        maxLength: 32
        example: '*************3210'
      full:
        description: >-
          The full account number. This value only appears
          when ?unmasked=true is passed on the get request. 
          Not included in the summary representation of the 
          account that is included in account collection responses.
        type: string
        minLength: 9
        maxLength: 32
        example: '9876543210'

  schedule:
    title: Schedule
    description: >-
      A definition for a one-time or recurring scheduled transfer.
      Some financial institutions may limit scheduled transfers
      such that the transfer must be within 365 days.
    required:
      - start
    properties:
      start:
        description: >
          When the transaction occurs. This
          may be either a date in `yyyy-mm-dd` format, or a date-time in
          `yyyy-mm-ddTHH:MM:SSZ` format. If present, the time portion is a
          _hint_; the FI may not be able to schedule transaction at specific
          times. If `start` is omitted, the transaction will be scheduled for the next
          processing day. If `start` is the current day, the transaction may
          be scheduled for the next processing day if transaction processing has stopped
          for the day.
        type: string
        example: '2018-01-01'

x-apiture-errors:
  transactionNotFound:
    description: No scheduled transactions were found for the specified transactionId
    remediation: Check to make sure that the supplied transactionId corresponds to an apiture scheduled transaction resource

x-apiture-traits:
  - api:
      title: Transactions
      basePath: transactions
      links: [getTransactions, getScheduledTransactions, getHistory, getApi, getApiDoc]
  - resource:
      name: transaction
      description: A transaction against this account
      exlcudeMethods:
        - put
        - patch
        - delete
      simpleModelSchema: true
