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