openapi: 3.0.3 info: title: Astrada bank-accounts transaction-messages 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: transaction-messages description: Transaction messages resource paths: /transaction-messages/{transactionMessageId}/raw: parameters: - $ref: '#/components/parameters/transaction-message-id-2' get: tags: - transaction-messages summary: Retrieve the raw transaction message description: Return a raw transaction message by the transaction message unique identifier. operationId: GetRawTransactionMessageById security: - main-auth: - transaction-messages:read responses: '200': description: Raw transaction message retrieved successfully content: application/hal+json: schema: $ref: '#/components/schemas/raw-transaction-message' examples: Example Get Raw Transaction Message Response: $ref: '#/components/examples/raw-transaction-message' '204': $ref: '#/components/responses/no-content' '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' /transaction-messages/{transactionMessageId}: parameters: - $ref: '#/components/parameters/transaction-message-id-2' get: tags: - transaction-messages summary: Retrieve transaction message description: Return a transaction message by its unique identifier, including details about the transaction's type and relevant transactional data. operationId: GetTransactionMessageById security: - main-auth: - transaction-messages:read responses: '200': description: Transaction message retrieved successfully content: application/hal+json: schema: $ref: '#/components/schemas/transaction-message' examples: Example Get Transaction Message Response: $ref: '#/components/examples/transaction-message' '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: 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. no-content: description: The request has been successfully processed and there is no content to return examples: raw-transaction-message: description: Example of Raw Transaction Message resource value: _links: self: href: /transaction-messages/80b08eeb-c4cc-4e5c-8d0b-15bc2e04b4dc/raw message: href: /transaction-messages/80b08eeb-c4cc-4e5c-8d0b-15bc2e04b4dc raw: messageTypeIndicator: '0100' primaryAccountNumber: 444444******0000 processingCode: '000000' transactionAmount: '000000000145' transmissionDateTime: '0425000000' systemsTraceAuditNumber: '537254' localTransactionTime: '133945' localTransactionDate: '0424' merchantType: '5734' acquiringInstitutionIdentificationCode: KWGBYTEI4FL0QQQ retrievalReferenceNumber: IWVQ22_2024-04-24 authorizationIdentificationResponse: '537254' responseCode: '00' cardAcceptorTerminalIdentification: TERMINAL01 cardAcceptorIdentificationCode: KWGBYTEI4FL0QQQ cardAcceptorNameLocation: Uber LONDON LNDGBR transactionCurrencyCode: '840' cardholderBillingAmount: 000000000118 cardholderBillingCurrency: '826' networkManagementInformationCode: MASTERCARD transaction-message: description: Example of Transaction Message resource value: _links: self: href: /transaction-messages/80b08eeb-c4cc-4e5c-8d0b-15bc2e04b4dc raw: href: /transaction-messages/80b08eeb-c4cc-4e5c-8d0b-15bc2e04b4dc/raw acceptor: acquirerId: null city: LONDON country: GBR id: KWGBYTEI4FL0QQQ mcc: '5734' name: Uber state: LND accountId: a49fdf13-62ce-4704-80bf-82f317cc215e approvalCode: '537254' bankData: null cardId: bf4d1e23-0f5a-42a7-81f2-bc66f392a98c cardType: virtual cardholderBillingAmount: 1.18 cardholderBillingCurrency: GBP createdDateTime: '2024-04-26T01:41:22.544Z' dateTime: '2024-04-24T13:39:45Z' id: 80b08eeb-c4cc-4e5c-8d0b-15bc2e04b4dc messageType: FINL_ADVC network: MASTERCARD result: APPROVED subaccountId: cb4d801e-a10a-4f42-b9de-1c51685ffd8a transactionAmount: 1.45 transactionCurrency: USD transactionReference: IWVQ22_2024-04-24 transactionType: DEBIT_01 transmissionDateTime: '2024-04-25T00:00:00.000Z' parameters: transaction-message-id-2: in: path name: transactionMessageId required: true schema: type: string format: uuid example: 9340721f-bdce-4afa-bd9d-26cceb9d2176 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 raw-transaction-message: type: object properties: _links: type: object properties: self: $ref: '#/components/schemas/link' message: $ref: '#/components/schemas/link' required: - message - self raw: type: object description: The raw payload from the network that originated the underlying transaction message (will vary by network and message). required: - _links - raw transaction-message: type: object properties: _links: type: object properties: self: $ref: '#/components/schemas/link' raw: $ref: '#/components/schemas/link' required: - self id: type: string format: uuid description: The unique identifier of this transaction message entity. acceptor: type: object description: The details relating to the acceptor (merchant) that initiated the transaction message. properties: acquirerId: type: string nullable: true description: The identifier of the acquirer/processor used by the acceptor as assigned by the network. 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. id: type: string nullable: true description: The identifier of the payment acceptor (merchant) as assigned by the acquirer/processor. 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. name: type: string nullable: true description: The acceptor (merchant) name. state: type: string nullable: true description: The acceptor's registered state (e.g. Michigan) as assigned by the acquirer/processor. required: - acquirerId - id - city - mcc - name - state approvalCode: type: string nullable: true description: Unique code that authorizes a transaction message, sent by the card issuer/issuer-processor when approving a transaction. Always absent on bank-only messages — no card authorization occurred (its absence, together with the `bank_`-prefixed transactionReference, is the marker of a bank-only message). bankData: type: object nullable: true description: Bank-side provenance, present only on bank-sourced messages (null otherwise). Deliberately slim — the bank's merchant string, dates and amounts map into the canonical fields above; `bankTransactionId` is the stable join key back to the bank feed. It equals `banktransaction.created.id` and `transaction.match.created.matches[].id`, and resolves via `GET /bank-transactions/{id}` for the full bank record. properties: provider: type: string enum: - plaid description: Open banking provider that observed the bank transaction. bankTransactionId: type: string format: uuid description: The bank transaction entity id — the canonical, lifecycle-stable join key across every bank-data surface. personalFinanceCategory: type: object nullable: true description: Provider categorization of the bank transaction — the one bank-only datum with no card-side equivalent. properties: primary: type: string description: Primary category (e.g. FOOD_AND_DRINK). detailed: type: string nullable: true description: Detailed category (e.g. FOOD_AND_DRINK_RESTAURANT). required: - provider - bankTransactionId cardId: type: string format: uuid nullable: true description: The unique identifier of the card related to this entity. Null only for bank-sourced messages from a bank account with no linked cards (the card-less unified feed). cardType: type: string description: The type of card used in the transaction. The only available value is 'virtual' and the field is nullable. cardholderBillingAmount: type: number description: The amount in the currency of the country of issuance. The transactionAmount and cardholderBillingAmount values may differ in case of international transactions. cardholderBillingCurrency: type: string description: The currency of the country of issuance following ISO 4217 alpha-3 format. createdDateTime: type: string format: date-time description: Date and time when this resource was created, in UTC, following ISO 8601 format. dateTime: type: string format: date-time description: 'The timestamp of the transaction message (e.g. authorization, movement of funds, etc) following ISO 8601 format. The timezone depends on the card network: - **Visa/Amex**: UTC (suffixed with `Z`) - **Mastercard**: Local time zone of the merchant/acquirer (no `Z` suffix, timezone offset not included) The presence or absence of the `Z` suffix indicates whether the value is UTC or local time. ' messageType: type: string description: The type of operation this transaction message represents. [Learn More](https://docs.astrada.co/docs/transaction-message) enum: - AUTH_ADVC - AUTH_REQU - FINL_ADVC - CBCK_ADVC - FINL_REQU network: type: string description: The rail that processed this payment. `OPEN_BANKING` marks a bank-sourced message with no card-network involvement (the concrete provider is in `bankData.provider`). enum: - VISA - MASTERCARD - AMEX - OPEN_BANKING subaccountId: type: string description: The unique identifier of the subaccount related to this entity. format: uuid result: type: string description: The issuer's decision on whether the transaction message is authorized. enum: - APPROVED - DECLINED transactionAmount: type: number description: The amount of the transaction message in the currency it was charged in. In the case of international transactions, the transactionAmount and cardholderBillingAmount may differ due to being in different currencies. transactionCurrency: type: string description: The currency in which the transaction took place following ISO 4217 alpha-3 format. transactionReference: type: string description: Identification of the Transaction that has to be unique for a time period. transactionType: type: string nullable: true description: Types provide additional information about the transaction message, describing the effect that it had on the customer account and the type of accounts affected. [Learn More](https://docs.astrada.co/docs/transaction-message) enum: - DEBIT_01 - DEBIT_02 - DEBIT_19 - CREDIT_01 - CREDIT_02 - INQUIRY_01 - TRANSFER_01 - ADMIN_01 - ADMIN_02 transmissionDateTime: type: string nullable: true format: date-time description: The timestamp of when the transaction message was received by the data source (i.e. Mastercard or Visa), in UTC, following ISO 8601 format. required: - _links - acceptor - cardId - cardholderBillingAmount - cardholderBillingCurrency - createdDateTime - dateTime - id - messageType - network - result - subaccountId - transactionAmount - transactionCurrency - transactionReference - transactionType - transmissionDateTime 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