openapi: 3.0.3 info: title: Astrada bank-accounts 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: transactions description: Transaction resource paths: /transactions/{transactionId}: parameters: - $ref: '#/components/parameters/transaction-id' get: tags: - transactions summary: Retrieve transaction description: 'Returns a transaction by its unique identifier, including details about the transaction''s state and relevant transactional data. ' operationId: GetTransactionById security: - main-auth: - transactions:read responses: '200': description: Transaction retrieved successfully content: application/hal+json: schema: $ref: '#/components/schemas/transaction' examples: Example Get Transaction Response: $ref: '#/components/examples/transaction' '400': $ref: '#/components/responses/bad-request' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/not-found' '500': $ref: '#/components/responses/server-error' /transactions: get: tags: - transactions summary: List transactions description: 'Returns a list of all transactions under the account. By default, `GET /transactions` returns transactions ordered by the latest `createdAt`. You can combine the different filters as documented. This endpoint supports [cursor-based pagination](https://docs.astrada.co/reference/pagination). ' operationId: GetTransactions parameters: - $ref: '#/components/parameters/transaction-message-id' - $ref: '#/components/parameters/subaccount-id' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/card-id' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/order' security: - main-auth: - transactions:read responses: '200': description: Transactions retrieved successfully content: application/hal+json: schema: type: object required: - _links - _embedded properties: _links: type: object required: - self properties: self: $ref: '#/components/schemas/link' next: $ref: '#/components/schemas/link' _embedded: type: object required: - transactions properties: transactions: type: array items: $ref: '#/components/schemas/transaction' examples: Example List Transactions Response: value: _links: self: href: /transactions _embedded: transactions: - _links: messages: - href: /transaction-messages/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4 - href: /transaction-messages/934f8701-53e3-4a2b-a000-6bb52195d2ea card: href: /subaccounts/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b6 subaccount: href: /subaccounts/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b5 self: href: /transactions/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4 acceptor: city: LONDON country: GBR mcc: '5734' state: LND cardId: 4d1ff59f-4286-4209-9662-92e174193562 cardholderBillingCurrency: GBP cardholderBillingHoldAmount: 0 cardholderBillingSettledAmount: 0.81 createdAt: '2024-05-01T06:41:43.810Z' descriptor: Uber id: 8697df0c-9011-47ca-a52b-8d2a7a4ad903 network: MASTERCARD status: SETTLED subaccountId: c6d5e036-361e-4773-a514-b9496cf2d2b5 supersededMessageIds: [] transactionCurrency: USD transactionHoldAmount: 0 transactionOccurrenceDate: '2024-05-01' transactionSettledAmount: 1 transactionType: DEBIT_01 updatedAt: '2024-05-02T08:41:43.810Z' '400': $ref: '#/components/responses/bad-request' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/not-found' '500': $ref: '#/components/responses/server-error' components: parameters: subaccount-id: in: query name: subaccountId required: false schema: type: string format: uuid example: 2fd4d402-b759-479c-87a6-58d85e345356 limit: in: query name: limit description: Maximum number of items to return required: false schema: type: integer minimum: 1 maximum: 100 default: 25 example: 25 transaction-message-id: in: query name: transactionMessageId required: false schema: type: string format: uuid example: 9a88aa0e-c1d3-4e70-b5e1-45ab64eb5aac order: in: query name: order required: false schema: type: string enum: - asc - desc default: desc example: desc card-id: in: query name: cardId required: false schema: type: string format: uuid example: 8164683a-8d23-4421-9694-1a81fc9b9c37 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== responses: 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. 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. examples: transaction: description: Example of Transaction resource value: _links: card: href: /cards/4d1ff59f-4286-4209-9662-92e174193562 subaccount: href: /subaccounts/c6d5e036-361e-4773-a514-b9496cf2d2b5 self: href: /transactions/8697df0c-9011-47ca-a52b-8d2a7a4ad903 messages: - href: /transaction-messages/f4b24a0a-6a37-4ce3-8845-ddf0b604a9b4 - href: /transaction-messages/934f8701-53e3-4a2b-a000-6bb52195d2ea acceptor: city: LONDON country: GBR mcc: '5734' state: LND cardId: 4d1ff59f-4286-4209-9662-92e174193562 cardholderBillingCurrency: GBP cardholderBillingHoldAmount: 0 cardholderBillingSettledAmount: 0.81 createdAt: '2024-05-01T06:41:43.810Z' descriptor: Uber id: 8697df0c-9011-47ca-a52b-8d2a7a4ad903 network: MASTERCARD status: SETTLED subaccountId: c6d5e036-361e-4773-a514-b9496cf2d2b5 supersededMessageIds: [] transactionCurrency: USD transactionHoldAmount: 0 transactionOccurrenceDate: '2024-05-01' transactionSettledAmount: 1 updatedAt: '2024-05-02T08:41:43.810Z' 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 transaction: type: object properties: _links: type: object properties: messages: type: array items: $ref: '#/components/schemas/link' card: $ref: '#/components/schemas/link' self: $ref: '#/components/schemas/link' subaccount: $ref: '#/components/schemas/link' required: - messages acceptor: type: object description: The details relating to the acceptor (merchant) from the latest transaction message. properties: city: type: string nullable: true description: The acceptor's registered city. Defined by the acquirer/processor. country: type: string nullable: true description: The acceptor's registered country following ISO 3166 alpha-3. mcc: type: string nullable: true description: The Merchant Category Code provided by the acquirer/processor. Used to classify businesses by the types of goods provided or services rendered. state: type: string nullable: true description: The acceptor's registered state (e.g. Michigan) as assigned by the acquirer/processor. required: - city - country - mcc - state cardId: type: string format: uuid nullable: true description: The unique identifier of the card related to this entity. Null only for bank-sourced transactions on a bank account with no linked cards (the card-less unified feed); the `_links.card` link is omitted in that case. cardholderBillingCurrency: type: string description: The currency of the country of issuance following ISO 4217 alpha-3 format. cardholderBillingHoldAmount: type: number format: double description: This amount models the hold on the cardholder account, in the card's issued currency, that occurs after an authorization and before a financial message. This amount will change as both authorization and financial messages are added to the Transaction in order to reflect the remaining hold amount. cardholderBillingSettledAmount: type: number format: double description: The settled amount models the bottom line impact to the customer's bank statement in the card's issued currency. This amount will change as financial messages are added to the Transaction. descriptor: type: string nullable: true description: Cleansed merchant name. id: type: string format: uuid description: The unique identifier of this transaction entity. network: type: string description: The card network that processed this payment. subaccountId: type: string format: uuid description: The unique identifier of the subaccount related to this entity. supersededMessageIds: type: array items: type: string format: uuid description: Message ids from `_links.messages` whose financial contribution was superseded during aggregation — typically duplicate deliveries of the same clearing across network feeds, or a provisional bank-sourced settlement replaced by the network clearing. Superseded messages stay listed in `_links.messages` for audit but do not count toward the settled amounts, so exclude them when deriving totals from individual messages (or better, use `transactionSettledAmount` / `cardholderBillingSettledAmount` directly). Always a subset of `_links.messages`. Each payload carries the full current set (a snapshot, not a delta). Transactions last updated before this field was introduced report `[]` until their next update. status: type: string description: A semantic understanding of the state of the transaction within the transaction lifecycle. [Learn More](https://docs.astrada.co/docs/transaction) enum: - PENDING - VOIDED - DECLINED - SETTLED transactionCurrency: type: string description: The currency in which the transaction took place following ISO 4217 alpha-3 format. transactionHoldAmount: type: number format: double description: This amount models the hold on the cardholder account, in the currency the transaction was conducted in, that occurs after an authorization and before a financial message. This amount will change as both authorization and financial messages are added to the Transaction in order to reflect the remaining hold amount. transactionOccurrenceDate: type: string format: date nullable: true description: The UTC date when the transaction took place, following ISO 8601 format (YYYY-MM-DD). This is a date-only field with no time component. transactionSettledAmount: type: number format: double description: The settled amount models the bottom line impact to the customer's bank statement in the currency the transaction was conducted in. This amount will change as financial messages are added to the Transaction. createdAt: description: Date and time when this resource was created, in UTC, following ISO 8601 format. type: string format: date-time updatedAt: description: Date and time when this resource was last updated, in UTC, following ISO 8601 format. type: string format: date-time required: - _links - acceptor - cardId - cardholderBillingCurrency - cardholderBillingHoldAmount - cardholderBillingSettledAmount - createdAt - descriptor - id - network - subaccountId - status - transactionCurrency - transactionHoldAmount - transactionOccurrenceDate - transactionSettledAmount - updatedAt 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