Astrada bank-transactions API
Access bank transactions synced from connected accounts. Transactions are ingested via Plaid and can be matched against card transactions.
OpenAPI Specification
openapi: 3.0.3
info:
title: Astrada bank-accounts bank-transactions API
version: '2024-02-28'
contact:
email: developer@astrada.co
description: 'Welcome to our API Reference. 👋
'
servers:
- url: https://api.astrada.co
security: null
tags:
- name: bank-transactions
description: Access bank transactions synced from connected accounts. Transactions are ingested via Plaid and can be matched against card transactions.
paths:
/bank-transactions/{subaccountId}/{transactionId}:
parameters:
- $ref: '#/components/parameters/subaccount-id-2'
- $ref: '#/components/parameters/transaction-id'
get:
tags:
- bank-transactions
summary: Retrieve bank transaction
description: Returns detailed information about a specific bank transaction by its identifier, including match status and transaction metadata.
operationId: GetBankTransaction
security:
- main-auth:
- banking:read
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/bank-transaction'
examples:
Example Get Bank Transaction Response:
$ref: '#/components/examples/bank-transaction'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'500':
$ref: '#/components/responses/server-error'
/bank-transactions/{subaccountId}:
parameters:
- $ref: '#/components/parameters/subaccount-id-2'
get:
tags:
- bank-transactions
summary: List bank transactions
description: 'Returns a list of bank transactions for a subaccount. Bank transactions are synced from connected financial institutions. A movement may briefly appear as its pending posting until the posted transaction replaces it (the pending row is then removed from the feed).
By default, `GET /bank-transactions/{subaccountId}` returns transactions ordered by the latest `date`.
This endpoint supports cursor-based pagination and various filters including date range, amount range, and match status.
'
operationId: ListBankTransactions
parameters:
- $ref: '#/components/parameters/bank-account-id-2'
- $ref: '#/components/parameters/card-id-2'
- $ref: '#/components/parameters/start-date'
- $ref: '#/components/parameters/end-date'
- $ref: '#/components/parameters/min-amount'
- $ref: '#/components/parameters/max-amount'
- $ref: '#/components/parameters/transaction-type'
- $ref: '#/components/parameters/matched'
- in: query
name: source
description: Filter transactions by source.
required: false
schema:
type: string
enum:
- PLAID
- UPLOAD
- in: query
name: statementId
description: Filter transactions by the statement they were imported from.
required: false
schema:
type: string
format: uuid
- $ref: '#/components/parameters/banking-limit'
- $ref: '#/components/parameters/cursor'
security:
- main-auth:
- banking:read
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
required:
- items
- pagination
properties:
items:
type: array
items:
$ref: '#/components/schemas/bank-transaction'
pagination:
type: object
required:
- hasMore
properties:
cursor:
type: string
description: Cursor to use for the next page of results.
hasMore:
type: boolean
description: Whether there are more results available.
examples:
Example List Bank Transactions Response:
value:
items:
- _links:
self:
href: /bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
bankAccount:
href: /bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
card:
href: /cards/5dec2c49-0aa5-4683-a317-427eb5d115f3
match:
href: /transaction-matches/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
id: 7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
accountId: 8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
subaccountId: 1fcb895e-9217-4a6f-9d10-5a7dcef86c11
bankAccountId: 3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
cardId: 5dec2c49-0aa5-4683-a317-427eb5d115f3
matchId: b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
date: '2025-10-15'
amount: 42.5
currency: USD
description: UBER TRIP
merchantName: Uber
category:
- Travel
transactionType: debit
source: PLAID
statementId: null
status: matched
settlement: null
createdAt: '2025-10-15T14:30:00.000Z'
- _links:
self:
href: /bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/2e5f8a1b-4c7d-3e9f-b0a2-8d6c4f1e7b3a
bankAccount:
href: /bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
card:
href: /cards/5dec2c49-0aa5-4683-a317-427eb5d115f3
id: 2e5f8a1b-4c7d-3e9f-b0a2-8d6c4f1e7b3a
accountId: 8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
subaccountId: 1fcb895e-9217-4a6f-9d10-5a7dcef86c11
bankAccountId: 3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
cardId: 5dec2c49-0aa5-4683-a317-427eb5d115f3
matchId: null
date: '2025-10-14'
amount: 156.23
currency: USD
description: AMAZON MARKETPLACE
merchantName: Amazon
category:
- Shopping
transactionType: debit
source: PLAID
statementId: null
status: posted
settlement: null
createdAt: '2025-10-14T09:15:00.000Z'
pagination:
cursor: ZXhhbXBsZQ==
hasMore: true
links:
GetFirstBankTransaction:
operationId: GetBankTransaction
parameters:
transactionId: $response.body#/items/0/id
description: Retrieve the first bank transaction from the list.
'400':
$ref: '#/components/responses/bad-request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/server-error'
/bank-transactions/{subaccountId}/webhooks:
parameters:
- $ref: '#/components/parameters/subaccount-id-2'
post:
tags:
- bank-transactions
summary: Trigger bank transaction webhooks
description: 'Manually triggers webhook delivery for specified bank transactions. This can be used to re-emit webhooks that may have been missed or to force re-matching of transactions.
You can specify which webhook event types to emit: `banktransaction.created` for transaction data or `transaction.match.created` for match results.
'
operationId: TriggerBankTransactionWebhooks
security:
- main-auth:
- banking:admin
requestBody:
description: Webhook trigger request
required: true
content:
application/json:
schema:
type: object
required:
- ids
properties:
ids:
description: List of bank transaction identifiers to emit webhooks for. Must contain at least one ID.
type: array
minItems: 1
items:
type: string
format: uuid
webhooks:
description: The types of webhook events to emit.
type: array
items:
type: string
enum:
- banktransaction.created
- transaction.match.created
forceRematch:
description: 'Set to `true` to re-run the matching algorithm for the named transactions before emitting webhooks. Transactions that already have a match are genuinely re-scored: the existing match id is preserved when the pairing survives, updated when a better pairing exists, and removed when the movement no longer matches.'
type: boolean
default: false
dispatchUnmatched:
description: 'After the re-match, emit the standalone bank-only feed entry for each named transaction the matcher left unmatched (idempotent per transaction — already-emitted standalones are skipped). Requires `forceRematch: true` and `webhooks` to include `transaction.match.created`; the request is rejected with `400` otherwise, because only a same-run re-match can distinguish a genuinely unmatched movement from a duplicate of an already-settled purchase.'
type: boolean
default: false
examples:
TriggerWebhooksExample:
value:
ids:
- 7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
webhooks:
- banktransaction.created
- transaction.match.created
forceRematch: false
RematchAndDispatchExample:
value:
ids:
- 7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
webhooks:
- transaction.match.created
forceRematch: true
dispatchUnmatched: true
responses:
'200':
description: Webhooks triggered
content:
application/json:
schema:
type: object
required:
- message
- emitted
- resent
- matched
- skipped
- failed
properties:
message:
type: string
description: Human-readable summary of the operation.
emitted:
type: integer
description: Number of webhook events emitted.
resent:
type: integer
description: Number of webhooks resent.
matched:
type: integer
description: Number of transactions that were matched.
skipped:
type: integer
description: Number of transactions that were skipped.
failed:
type: array
description: Transactions that failed to process.
items:
type: object
properties:
id:
type: string
description: The transaction identifier that failed.
error:
type: string
description: The error message describing why processing failed.
dispatched:
type: integer
description: Number of standalone bank-only emissions dispatched for still-unmatched transactions. Only present when `dispatchUnmatched` was requested (and on service versions that support the flag).
dispatchError:
type: string
description: Present when the standalone dispatch step failed after a successful re-match; the matching results above still stand.
examples:
Example Trigger Webhooks Response:
value:
message: Processed 1 transactions
emitted: 2
resent: 0
matched: 1
skipped: 0
failed: []
'400':
$ref: '#/components/responses/bad-request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/server-error'
components:
examples:
bank-transaction:
description: Example of a Bank Transaction resource
value:
_links:
self:
href: /bank-transactions/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
bankAccount:
href: /bank-accounts/3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
card:
href: /cards/5dec2c49-0aa5-4683-a317-427eb5d115f3
match:
href: /transaction-matches/1fcb895e-9217-4a6f-9d10-5a7dcef86c11/b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
id: 7f2a9c4e-3b1d-4e8f-a5c7-6d0e2f9b8a3c
accountId: 8f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
subaccountId: 1fcb895e-9217-4a6f-9d10-5a7dcef86c11
bankAccountId: 3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
cardId: 5dec2c49-0aa5-4683-a317-427eb5d115f3
matchId: b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
date: '2025-10-15'
amount: 42.5
currency: USD
description: UBER TRIP
merchantName: Uber
category:
- Travel
transactionType: debit
source: PLAID
statementId: null
status: early_cleared
settlement:
state: early_cleared
emissionType: early_clearing
emittedAt: '2025-10-15T15:00:00.000Z'
supersededAt: null
createdAt: '2025-10-15T14:30:00.000Z'
parameters:
transaction-type:
in: query
name: transactionType
description: Filter bank transactions by transaction type
required: false
schema:
type: string
enum:
- debit
- credit
example: debit
min-amount:
in: query
name: minAmount
description: Filter transactions with an amount greater than or equal to this value
required: false
schema:
type: number
example: 10
matched:
in: query
name: matched
description: Filter bank transactions by match status. Set to `true` to return only matched transactions, or `false` for unmatched.
required: false
schema:
type: string
enum:
- 'true'
- 'false'
example: 'true'
end-date:
in: query
name: endDate
description: Filter results up to this date (inclusive), in YYYY-MM-DD format
required: false
schema:
type: string
format: date
example: '2025-10-31'
bank-account-id-2:
in: query
name: bankAccountId
description: Filter by bank account identifier
required: false
schema:
type: string
format: uuid
example: 3a8f2c1d-5e7b-4d9a-b6c8-9f0e1d2a3b4c
banking-limit:
in: query
name: limit
description: Maximum number of items to return
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 250
example: 250
transaction-id:
in: path
name: transactionId
required: true
schema:
type: string
format: uuid
example: 9340721f-bdce-4afa-bd9d-26cceb9d2176
cursor:
in: query
name: cursor
required: false
description: The cursor to use for pagination. Identifies your place on the list
schema:
type: string
format: byte
example: ZXhhbXBsZQ==
subaccount-id-2:
in: path
name: subaccountId
required: true
schema:
type: string
format: uuid
example: 24c4f90d-ab3b-4f6e-8a1d-d251a4fcf34c
start-date:
in: query
name: startDate
description: Filter results from this date (inclusive), in YYYY-MM-DD format
required: false
schema:
type: string
format: date
example: '2025-10-01'
card-id-2:
in: path
name: cardId
required: true
schema:
type: string
format: uuid
example: 6d18f5bb-b9d6-4237-97c2-44b1bdb71d6b
max-amount:
in: query
name: maxAmount
description: Filter transactions with an amount less than or equal to this value
required: false
schema:
type: number
example: 500
responses:
server-error:
description: The server encountered an unexpected condition that prevented it from fulfilling the request
content:
application/problem+json:
schema:
type: object
properties:
detail:
type: string
title:
type: string
enum:
- Internal Server Error
required:
- detail
- title
example:
title: Internal Server Error
detail: The server encountered an unexpected condition that prevented it from fulfilling the request.
bad-request:
description: The server cannot or will not process the request due to something that is perceived to be a client error
content:
application/problem+json:
schema:
type: object
properties:
detail:
type: string
title:
type: string
enum:
- Bad Request
errors:
type: array
items:
type: object
properties:
title:
type: string
detail:
type: string
required:
- title
- detail
required:
- detail
- title
examples:
Example Generic Bad Request Payload Response:
value:
title: Bad Request
detail: Request object failed validation.
Example Generic Bad Request Parameters Response:
value:
title: Bad Request
detail: Request parameters are invalid.
not-found:
description: The requested resource was not found on the server
content:
application/problem+json:
schema:
type: object
properties:
type:
type: string
instance:
type: string
detail:
type: string
title:
type: string
enum:
- Not Found
required:
- detail
- title
example:
title: Not Found
detail: The requested resource was not found on the server.
unauthorized:
description: Authentication credentials were either missing or incorrect
content:
application/problem+json:
schema:
type: object
properties:
detail:
type: string
title:
type: string
enum:
- Unauthorized
required:
- detail
- title
example:
title: Unauthorized
detail: Authentication credentials were either missing or incorrect.
forbidden:
description: Authentication credentials used do not have have permissions to perform the request
content:
application/problem+json:
schema:
type: object
properties:
detail:
type: string
title:
type: string
enum:
- Forbidden
required:
- detail
- title
example:
title: Forbidden
detail: You do not have permission to access the requested resource.
schemas:
link:
type: object
properties:
href:
type: string
templated:
type: boolean
type:
type: string
deprecation:
type: string
name:
type: string
profile:
type: string
title:
type: string
hreflang:
type: string
required:
- href
bank-transaction:
type: object
required:
- _links
- id
- accountId
- subaccountId
- bankAccountId
- cardId
- matchId
- date
- amount
- currency
- description
- merchantName
- category
- transactionType
- source
- status
- settlement
- createdAt
properties:
_links:
type: object
description: HAL-style links to related resources.
required:
- self
- bankAccount
properties:
self:
$ref: '#/components/schemas/link'
bankAccount:
$ref: '#/components/schemas/link'
card:
$ref: '#/components/schemas/link'
match:
$ref: '#/components/schemas/link'
id:
type: string
format: uuid
description: The unique identifier of the bank transaction.
accountId:
type: string
format: uuid
description: The unique identifier of the account that owns this transaction.
subaccountId:
type: string
format: uuid
description: The unique identifier of the subaccount associated with this transaction.
bankAccountId:
type: string
format: uuid
description: The unique identifier of the bank account this transaction belongs to.
cardId:
type: string
format: uuid
nullable: true
description: The identifier of the card linked to the bank account, used for transaction matching.
matchId:
type: string
format: uuid
nullable: true
description: The identifier of the transaction match, if this bank transaction has been matched to a card transaction.
date:
type: string
format: date
description: The date the transaction was posted, in YYYY-MM-DD format.
amount:
type: number
description: The transaction amount.
currency:
type: string
description: The currency of the transaction following ISO 4217 format.
minLength: 3
maxLength: 3
description:
type: string
nullable: true
description: The transaction description provided by the financial institution.
merchantName:
type: string
nullable: true
description: The name of the merchant.
category:
type: array
nullable: true
description: The transaction categories assigned by the provider.
items:
type: string
transactionType:
type: string
description: 'The type of transaction.
- `debit`: Money sent (outflow).
- `credit`: Money received (inflow).
'
enum:
- debit
- credit
source:
type: string
description: 'The source of this transaction.
- `PLAID`: Synced from a connected financial institution via Plaid.
- `UPLOAD`: Imported from a manually uploaded bank statement.
'
enum:
- PLAID
- UPLOAD
statementId:
type: string
format: uuid
nullable: true
description: The identifier of the bank statement this transaction was imported from, if applicable.
status:
type: string
description: 'The lifecycle stage of the bank movement, derived from its match pointer and settlement state.
- `posted`: Synced, not yet matched.
- `matched`: Paired to a card transaction without an early settlement of its own (e.g. connector off, or a below-HIGH match) — the movement is represented by the card transaction''s network settlement, and any standalone it previously emitted is netted to zero.
- `settled`: A bank-only movement settled standalone on the unified feed.
- `early_cleared`: A matched movement settled its card transaction early.
- `superseded`: A previously bank-only movement was retracted or corrected.
'
enum:
- posted
- matched
- settled
- early_cleared
- superseded
settlement:
type: object
nullable: true
description: Settlement outcome on the unified transaction feed. Present when the movement has settled live; null otherwise (unmatched, connector off, or shadow-only).
required:
- state
- emissionType
- emittedAt
- supersededAt
properties:
state:
type: string
enum:
- settled
- early_cleared
- superseded
emissionType:
type: string
enum:
- early_clearing
- bank_only
emittedAt:
type: string
format: date-time
nullable: true
description: When the settlement was emitted to the feed.
supersededAt:
type: string
format: date-time
nullable: true
description: When the settlement was superseded or corrected, if applicable.
createdAt:
description: Date and time when this resource was created, in UTC, following ISO 8601 format.
type: string
format: date-time
securitySchemes:
main-auth:
type: oauth2
flows:
implicit:
authorizationUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
refreshUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
scopes:
accounts:write: Accounts write resource
accounts:read: Accounts read resource
subaccounts:write: Subaccounts write resource
subaccounts:read: Subaccounts read resource
card-connector-data-links:write: card-connector-data-link resource
card-connector-consents:read: Card Consent read resource
card-connector-consents:write: Card Consent write resource
webhooks:read: Read Webhook resources
webhooks:write: Write Webhook resources
card-subscriptions:write: Create card subscription
card-subscriptions:read: Read card subscription
card-verifications:write: Create card verification
card-verifications:read: Read Card verification
cards:read: Read Card resources
cardholder:read: Read Cardholder resources
cardholder:write: Write Cardholder resources
transactions:read: Read Transaction resources
transaction-messages:read: Read Transaction Message resources
network-bulk-feeds:read: Read network bulk feed
network-bulk-feeds:write: Write network bulk feed
network-links:write: Write network link
enrollment-methods:write: Write enrollment methods
simulation:write: Write sandbox simulations
banking:read: Read banking resources
banking:write: Write banking resources
banking:admin: Admin banking operations
appstore:enrollment:write: Enroll cards via the appstore B2C flow
appstore:cards:read: View enrolled cards in the appstore
appstore:transactions:read: View synced transactions in the appstore
appstore:transactions:sync: Trigger transaction sync in the appstore
appstore:sessions:read: Read appstore session state
appstore:sessions:write: Write or delete appstore session state
appstore:tokens:read: Read appstore stored tokens and connections
appstore:tokens:write: Write appstore stored tokens and connections
externalDocs:
description: Find out more about Astrada API.
url: https://docs.astrada.co/reference