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 institution. 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 `/pendingTransactions` (via the
`getPendingTransactions` 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.
# Error Types
Error responses in this API may have one of the `type` values described below.
See [Errors](https://developer.apiture.com/docs/concepts/errors) for more information
on error responses and error types.
## transactionNotFound
**Description**: No transactions were found for the specified transactionId.
**Remediation**: Check to make sure that the supplied transactionId corresponds to an apiture transaction resource.
version: 0.11.6
contact:
name: Apiture
url: 'https://developer.apiture.com'
email: api@apiture.com
termsOfService: 'https://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf'
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: Pending Transactions
description: Bank Account Pending Transactions
- name: History
description: Bank Account Past Transactions
paths:
/transactions:
get:
summary: Return a collection of pending and completed transactions.
description: >-
Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting)
[filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searchable)
collection of pending and completed transactions. The [links](https://developer.apiture.com/docs/concepts/links) in the response include
pagination links.
The default will show transactions for all accounts that the user has access to.
operationId: getTransactions
security:
- apiKey: []
accessToken:
- banking/read
x-apiture-implemented: true
tags:
- Transactions
x-apiture-traits:
sortBy:
- checkNumber
- description
- type
- postedOn
- reversedOn
itemSchema: Transaction
filters:
checkNumber:
filter:
- in
- le
- ge
state:
filter:
- eq
- contains
type:
filter:
- eq
- contains
description:
filter:
- eq
- contains
network:
filter:
- eq
amount.value:
filter:
- eq
- contains
balance.current:
filter:
- eq
- contains
postedOn:
filter:
- eq
- gt
- ge
- lt
- le
parameters:
- $ref: '#/parameters/checkNumberQueryParam'
- $ref: '#/parameters/holdStateQueryParam'
- 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](https://developer.apiture.com/docs/concepts/sorting), 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](https://developer.apiture.com/docs/concepts/hal) representation of this transaction resource.'
operationId: getTransaction
security:
- apiKey: []
accessToken:
- banking/read
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'
/pendingTransactions:
get:
summary: Return a collection of pending transactions
description: >-
Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting)
[filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searchable)
collection of pending transactions. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links.
The default will show pending transactions for all accounts that the user has access to.
operationId: getPendingTransactions
security:
- apiKey: []
accessToken:
- banking/read
x-apiture-implemented: true
tags:
- Pending Transactions
parameters:
- $ref: '#/parameters/checkNumberQueryParam'
- $ref: '#/parameters/holdStateQueryParam'
- 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](https://developer.apiture.com/docs/concepts/sorting), 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'
/history:
get:
summary: Return a collection of past transactions
description: >-
Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting)
[filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searchable)
collection of transactions. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links.
Transactions in the history are immutable and not deletable.
The default will show transactions for all accounts that the user has access to.
operationId: getHistory
security:
- apiKey: []
accessToken:
- banking/read
x-apiture-implemented: true
tags:
- History
parameters:
- $ref: '#/parameters/checkNumberQueryParam'
- $ref: '#/parameters/holdStateQueryParam'
- 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](https://developer.apiture.com/docs/concepts/sorting), 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'
/:
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
security:
- apiKey: []
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/common/root/v2.0.0/profile.json'
_links:
'apiture:transactions':
href: /transactions/transactions
tags:
- API
parameters: []
/apiDoc:
get:
summary: Return API definition document
description: Return the OpenAPI document that describes this API.
operationId: getApiDoc
security:
- apiKey: []
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: []
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
checkNumberQueryParam:
name: checkNumber
in: query
description: >-
Specify one or more check numbers or check number ranges. This is a comma-separated or `|` separated list of number or ranges. Ranges have the
form `number-number`. For example, the value `201,202,210-213` matches the transactions where the check number is 201, 202, 210, 211, 212, or
213; this may also be expressed as `201|202|210-213`.
type: string
holdStateQueryParam:
name: holdState
in: query
description: >-
Subset the transactions collection to those whose `holdState` matches this value. Use `|` to separate multiple values. For example,
`?holdState=active` will match only items whose `holdState` is `active`; `?holdState=active|expired` will match items whose `holdState` is
`active` or `expired`. This is combined with an implicit `and` with other filters if they are used. See
[filtering](https://developer.apiture.com/docs/concepts/filtering).
type: string
required: false
default: none
filterQueryParam:
name: filter
in: query
description: 'Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).'
type: string
qQueryParam:
name: q
in: query
description: 'Optional search string. See [searching](https://developer.apiture.com/docs/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
securityDefinitions:
apiKey:
type: apiKey
name: API-Key
in: header
description: >-
API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the
`API-Key: {api-key}` request header.
accessToken:
type: oauth2
flow: accessCode
description: >-
OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private
`clientId` (and optional `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then passes
the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also returns
a refresh token which the client should use to renew the access token before it expires.
authorizationUrl: /auth/oauth2/authorize
tokenUrl: /auth/oauth2/token
scopes:
banking/read: Read access to accounts and account-related resources such as transfers and transactions.
banking/write: Write (update) access to accounts and account-related resources such as transfers and transactions.
banking/delete: Delete access to deletable accounts and account-related resources such as transfers.
banking/readBalance: >-
Read access to account balances. This must be granted in addition to the `banking/read` scope in order to view balances, but is included in
the `banking/full` scope.
banking/full: Full access to accounts and account-related resources such as transfers and transactions.
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.
This error response may have one of the following `type` values:
* [`transactionNotFound`](#err-transactionNotFound)
schema:
$ref: '#/definitions/errorResponse'
x-apiture-errors:
- transactionNotFound
definitions:
transactionType:
title: Transaction Type (v1.0.0)
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 the transfer of 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
x-apiture-version: 1.0.0
x-apiture-flattened: true
transactionState:
title: Transaction State (v1.0.0)
description: '*`state`* indicates the current state of the transaction'
type: string
enum:
- pending
- completed
- reversed
x-apiture-version: 1.0.0
x-apiture-flattened: true
holdState:
title: Hold State (v1.0.0)
description: >-
Indicates the hold state of the transaction. the `holdState` will be `none` if no hold is associated to the transaction; otherwise, the
`holdState` will indicate if the hold is currently `active` or has `expired`.
type: string
readOnly: true
enum:
- active
- expired
- none
x-apiture-version: 1.0.0
x-apiture-flattened: true
transaction:
title: A transaction (v1.0.0)
description: >
An financial transaction, such as a deposit, a check payment, interest, fees, transaction reversals, etc.
Links
Response and request bodies using this transaction
schema may contain
the following links:
Rel | Summary | Method |
apiture:account |
Account | GET |
apiture:sourceAccount |
Source Account | GET |
apiture:targetAccount |
Target Account | GET |
apiture:checkFrontImage |
Check Front Image | GET |
apiture:checkFrontFile |
Check Front Image | GET |
apiture:checkBackImage |
Check Back Image | GET |
apiture:checkBackFile |
Check Back Image | GET |
apiture:reversedBy | Fetch a representation of this
transaction | GET |
apiture:reverses | Fetch a representation of this
transaction | GET |
x-apiture-links:
- rel: 'apiture:account'
title: Account
verb: get
description: The URL of the local account the transaction applies to.
- rel: 'apiture:sourceAccount'
title: Source Account
verb: get
description: 'For account to account transfer transactions, this is the account where the funds were debited (withdrawn from), if available.'
- rel: 'apiture:targetAccount'
title: Target Account
verb: get
description: 'For account to account transfer transactions, this is the account where the funds were credited (deposited to) if available.'
- rel: 'apiture:checkFrontImage'
title: Check Front Image
verb: get
description: The URL of the image of the front of a processed check written from the account.
- rel: 'apiture:checkFrontFile'
title: Check Front Image
verb: get
description: >-
If the image has an associated resource, this link is URL of a file resource in Vault; this contains information about the front of a
processed check.
- rel: 'apiture:checkBackImage'
title: Check Back Image
verb: get
description: The URL of the image of the back of a processed check written from the account.
- rel: 'apiture:checkBackFile'
title: Check Back Image
verb: get
description: >-
If the image has an associated resource, this link is URL of a file resource in Vault; this contains information about the back of a
processed check.
- rel: 'apiture:reversedBy'
operationId: getTransaction
- rel: 'apiture:reverses'
operationId: getTransaction
example:
_id: 969d61b1-2b49-4eb6-9b7d-356f242ca0aa
amount:
value: '327.50'
currency: USD
balance:
current: '2180.27'
currency: USD
state: completed
type: debit
providerSummary: check 1856 | Don't Bug Me Pest Control
summary: check 1856 | Don't Bug Me Pest Control
description: 'check 1856, processed May 10, 2019'
checkNumber: 1856
sourceAccountNumbers:
masked: '*************3210'
full: '9876543210'
sourceAccountName: My Personal Checking
transactionCode: D480
postedOn: {}
network: check
_links:
self:
href: /transactions/transactions/969d61b1-2b49-4eb6-9b7d-356f242ca0aa
'apiture:account':
href: /accounts/accounts/7e6acb45-71c0-4aa8-9fe4-a5f3b4298be7
'apiture:checkFrontImage':
href: /vault/files/14361265-7837-4eab-8b74-3232c9716385/content
'apiture:checkFrontFile':
href: /vault/files/14361265-7837-4eab-8b74-3232c9716385
'apiture:checkBackImage':
href: /vault/files/41c9daba-c4c6-412d-9faf-eb82bc76e2e1/content
'apiture:checkBackFile':
href: /vault/files/41c9daba-c4c6-412d-9faf-eb82bc76e2e1
'apiture:sourceAccount':
href: /accounts/accounts/85efad52-14f6-494f-a52b-5b5960000766
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/abstractResource'
- properties:
- _id
- amount
- balance
- state
- type
- subtype
- providerSummary
- summary
- description
- checkNumber
- sourceAccountNumbers
- sourceAccountName
- targetAccountNumbers
- targetAccountName
- transactionCode
- postedOn
- reversedOn
- network
- holdState
- holdAmount
- holdExpiresAt
- eft
- ach
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
$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](https://developer.apiture.com/docs/concepts/profiles/) 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'
_id:
description: The unique identifier for this transaction resource. This is an immutable opaque string.
readOnly: true
type: string
amount:
description: The amount of the transaction.
allOf:
- $ref: '#/definitions/money'
balance:
description: The account's running balance as of this transaction. This property is optional and is omitted if not computable.
allOf:
- $ref: '#/definitions/balance'
state:
$ref: '#/definitions/transactionState'
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
checkNumber:
description: 'If this transaction represents a check drafted against this account, this is the check number.'
type: integer
minimum: 0
maximum: 4294967295
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
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
network:
description: |-
The name of the settlement network that is the transaction source, one of:
* `check` - the transaction was a check
* `eft` - debit card transaction or other electronic funds transfer
* `ach` - transfers and other Automated Clearing House transactions
* `core` - transactions sourced within the bank core
type: string
holdState:
$ref: '#/definitions/holdState'
holdAmount:
description: The amount of funds on hold.
allOf:
- $ref: '#/definitions/money'
holdExpiresAt:
description: >-
The date-time when the hold will expire. This is an [RFC 3369](https://tools.ietf.org/html/rfc3339) formatted date-time string,
`YYYY-MM-DDThh:mm:ss.sssZ`.
type: string
format: date-time
eft:
description: The electronic funds transfer. This property exists only if `network` is `eft`.
allOf:
- $ref: '#/definitions/electronicFundsTransfer'
ach:
description: The automated clearing house transfer. This property exists only if `network` is `ach`.
allOf:
- $ref: '#/definitions/ach'
type: object
x-apiture-flattened: true
transactions:
title: Transaction Collection (v1.0.0)
description: >-
Collection of transactions. The items in the collection are ordered in the `_embedded` object with array `items`. The top-level `_links` object
may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`).
When this response is used for the `getPendingTransactions` operation, the pagination links will reference `/transactions/pendingTransactions`;
when this response is used for the `getTransactions` operation, the pagination links will reference `/transactions/transactions`; when this
response is used for the `getHistory` operation, the pagination links will reference `/transactions/history`. The example shows the response for
`getTransactions`.
example:
_profile: 'https://api.apiture.com/schemas/transactions/transactions/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: 'https://api.apiture.com/schemas/transaction/v/profile.json'
_links:
self:
href: /transactions/transactions/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
state: pending
type: debit
providerSummary: gas station
- _id: d62c0701-0d74-4836-83f9-ebf3709442ea
_profile: 'https://api.apiture.com/schemas/transaction/v/profile.json'
_links:
self:
href: /transactions/transactions/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
state: pending
type: debit
providerSummary: donation
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/collection'
- properties:
- _embedded
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
$ref: '#/definitions/links'
_embedded:
type: object
description: Embedded objects.
properties:
items:
description: An array containing a page of transaction items.
type: array
items:
$ref: '#/definitions/transaction'
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) 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'
count:
description: >-
The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter
is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the
filter.
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
type: object
x-apiture-flattened: true
attributes:
x-apiture-version: 2.0.0
title: Attributes
description: An optional map of name/value pairs which contains additional dynamic data about the resource.
type: object
x-apiture-key: attributeName
additionalProperties:
$ref: '#/definitions/attributeValue'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json'
x-apiture-namespace: common
properties: {}
x-apiture-flattened: true
balance:
title: Account Balance (v1.0.0)
description: >-
The balance of the account. This is derived data and not mutable through the API. Balances may be negative, indicating a deficit or loan
balance.
properties:
current:
description: >-
The string representation of the current account balance. This is an exact decimal representation of the numeric balance value. The current
balance does not include pending transactions.
type: string
readOnly: true
example: '3450.30'
value:
description: >-
The current balance. **Note**: This property is deprecated. Use `balance.current` instead. This property will be removed in the next release
of this service.
type: string
readOnly: true
example: '3450.30'
available:
description: >-
The string representation of the exact decimal available balance. For deposit accounts, this reflects the amount that may be used for
withdrawals or transfers. This field does not apply to debit accounts such as loans.
type: string
readOnly: true
example: '3450.30'
currency:
description: 'The [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) for this balance.'
type: string
readOnly: true
example:
current: '3450.30'
available: '3450.30'
currency: USD
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
money:
title: Money (v1.0.0)
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. Note: 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
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
electronicFundsTransfer:
title: Electronic Funds Transfer (v1.0.0)
description: Representation of an electronic funds transfer.
properties:
cashBackAmount:
description: The amount in which the buyer receives cash at the time of purchase.
allOf:
- $ref: '#/definitions/money'
fee:
description: Fees (if applicable).
type: string
merchantAddress:
description: Merchant's full address.
allOf:
- $ref: '#/definitions/address'
panEntryMode:
description: >
Indicates how the primary account number (PAN) was entered into the system. This value encodes [ISO 8583 point of service PAN entry
modes](https://en.wikipedia.org/wiki/ISO_8583#Point_of_service_entry_modes).
panEntryMode
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values
(described by the named panEntryMode)
Value | Description |
unknown | Unknown |
manual | Manual |
magneticStripe | Magnetic stripe |
barCode | Bar code |
ocr | OCR |
iccCvv | Integrated circuit card (ICC). CVV can be checked. |
contactlessEmv | Auto entry via contactless EMV. |
fallbackFromIcc | Fallback from integrated circuit card (ICC) to magnetic stripe |
magneticStripeTrackTwo | Magnetic stripe as read from track 2. CVV can be checked. |
contactlessMagneticStripe | Auto entry via contactless magnetic stripe |
iccNoCvv | Integrated circuit card (ICC). CVV may not be checked. |
sameAsOriginalTransaction | Same as original transaction. |
type: string
enum:
- unknown
- manual
- magneticStripe
- barCode
- ocr
- iccCvv
- contactlessEmv
- fallbackFromIcc
- magneticStripeTrackTwo
- contactlessMagneticStripe
- iccNoCvv
- sameAsOriginalTransaction
x-apiture-enum: panEntryMode
example:
cashBackAmount:
amount: '123.45'
currency: USD
fee: '6.78'
merchantAddress:
addressLine1: 100 Front St.
city: Wilmington
regionCode: NC
postalCode: '28401'
countryCode: US
panEntryMode: manual
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
ach:
title: Automated Clearing House Transfer (v1.0.0)
description: Representation of an automated clearing house transfer.
properties:
traceId:
description: ACH Trace ID (threadId).
type: string
example:
traceId: '1234567890'
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
address:
title: Address (v1.0.0)
description: A postal address.
type: object
properties:
addressLine1:
description: 'The first street address line of the address, normally a house number and street name.'
type: string
addressLine2:
description: The optional second street address line of the address.
type: string
city:
description: The name of the city or municipality.
type: string
regionCode:
description: 'The mailing address region code, such as state in the US, or a province in Canada.'
type: string
example: NC
postalCode:
description: 'The mailing address postal code, such as a US Zip or Zip+4 code, or a Canadian postal code.'
type: string
example: 28401-5405
countryCode:
description: The ISO 3166-1 country code.
type: string
minLength: 2
maxLength: 2
example:
type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
x-apiture-version: 1.0.0
x-apiture-flattened: true
targetAccountNumbers:
title: Target Account Numbers (v1.0.0)
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'
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
root:
x-apiture-version: 2.0.0
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: 1.0.0
_profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json'
_links: {}
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/definitions/abstractResource'
- properties:
- _id
- name
- apiVersion
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
$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](https://developer.apiture.com/docs/concepts/profiles/) 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'
_id:
description: This API's unique ID.
readOnly: true
type: string
name:
type: string
description: This API's name.
apiVersion:
type: string
description: This API's version.
type: object
x-apiture-flattened: true
errorResponse:
x-apiture-version: 2.0.0
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.'
example:
_profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json'
_error:
_id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
message: The value for deposit must be greater than 0.
statusCode: 422
type: positiveNumberRequired
attributes:
value: -125.5
remediation: Provide a value which is greater than 0
occurredAt: '2018-01-25T05:50:52.375Z'
_links:
describedby:
href: 'https://api.apiture.com/errors/positiveNumberRequired'
_embedded:
errors: []
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/definitions/abstractResource'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
$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](https://developer.apiture.com/docs/concepts/profiles/) 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'
type: object
x-apiture-flattened: true
abstractResource:
x-apiture-version: 2.0.0
title: Abstract Resource
description: >-
An abstract schema used to define other schemas for request and response bodies. This is a
[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: '{uri of resource profile.json}'
_links:
self:
href: '{uri of current resource}'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/definitions/abstractRequest'
- properties:
- _error
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
$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](https://developer.apiture.com/docs/concepts/profiles/) 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'
type: object
x-apiture-flattened: true
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: 8
maxLength: 32
readOnly: true
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. This value is derived and immutable.
type: string
minLength: 4
maxLength: 17
example: '9876543210'
readOnly: true
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/accountNumbers/v1.0.0/model.json'
x-apiture-namespace: common
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
collection:
x-apiture-version: 2.0.0
title: Collection
description: A collection of resources. This is an abstract model schema which is extended to define specific resource collections.
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/definitions/abstractResource'
- properties:
- count
- start
- limit
- name
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
$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](https://developer.apiture.com/docs/concepts/profiles/) 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'
count:
description: >-
The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter
is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the
filter.
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
type: object
x-apiture-flattened: true
abstractRequest:
x-apiture-version: 2.0.0
title: Abstract Request
description: >-
An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource
representation, minus the `_error` defined in `abstractResource`.
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
$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](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
example:
_profile: '{uri of resource profile.json}'
_links:
self:
href: '{uri of current resource}'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
error:
x-apiture-version: 2.0.0
title: Error
description: Describes an error in an API request or in a service called via the API.
required:
- message
properties:
message:
type: string
description: A localized message string describing the error condition.
_id:
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.
readOnly: true
type: 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 [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.'
example: '2018-02-02T03:37:15.375Z'
attributes:
description: >-
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the
`minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the
client/presentation tier). The set of attributes varies by error `type`.
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.
errors:
description: An optional array of nested error objects. This property is not always present.
type: array
items:
$ref: '#/definitions/error'
_links:
$ref: '#/definitions/links'
example:
_id: 2eae46e1575c0a7b0115a4b3
message: Descriptive error message...
statusCode: 422
type: errorType1
remediation: Remediation string...
occurredAt: '2018-01-25T05:50:52.375Z'
errors:
- _id: ccdbe2c5c938a230667b3827
message: An optional embedded error
- _id: dbe9088dcfe2460f229338a3
message: Another optional embedded error
_links:
describedby:
href: 'https://developer.apiture.com/errors/errorType1'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
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
x-apiture-key: linkRelationName
additionalProperties:
$ref: '#/definitions/link'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json'
x-apiture-namespace: common
x-apiture-version: 1.0.0
properties: {}
x-apiture-flattened: true
link:
x-apiture-version: 1.0.0
title: Link
description: >-
Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL
links](https://developer.apiture.com/docs/concepts/links), 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.'
example:
href: /contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f
title: Applicant
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
attributeValue:
x-apiture-version: 2.0.0
title: Attribute Value
description: The data associated with this attribute.
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json'
x-apiture-namespace: common
type: object
properties: {}
x-apiture-flattened: true
x-apiture-errors:
transactionNotFound:
description: No transactions were found for the specified transactionId
remediation: Check to make sure that the supplied transactionId corresponds to an apiture transaction resource
x-apiture-traits:
- api:
title: Transactions
basePath: transactions
links:
- getTransactions
- getPendingTransactions
- getHistory
- getApi
- getApiDoc
applied: true
- resource:
name: transaction
description: A transaction against this account
excludeMethods:
- put
- patch
- delete
simpleModelSchema: true
applied: true
- security:
baseScope: banking
x-apiture-annotated-at: '2020-05-28T16:36:51.655Z'
host: api.devbank.apiture.com