Astrada transaction-messages API

openapi: 3.2.0
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:
  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'
  responses:
    no-content:
      description: The request has been successfully processed and there is no content to return
    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.
    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.
    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.
    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.
    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.
  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-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
              - 'null'
              description: The identifier of the acquirer/processor used by the acceptor as assigned by the network.
            city:
              type:
              - string
              - 'null'
              description: The acceptor's registered city. Defined by the acquirer/processor.
            country:
              type:
              - string
              - 'null'
              description: The acceptor's registered country following ISO 3166 alpha-3.
            id:
              type:
              - string
              - 'null'
              description: The identifier of the payment acceptor (merchant) as assigned by the acquirer/processor.
            mcc:
              type:
              - string
              - 'null'
              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
              - 'null'
              description: The acceptor (merchant) name.
            state:
              type:
              - string
              - 'null'
              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
          - 'null'
          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
          - 'null'
          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
              - 'null'
              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
                  - 'null'
                  description: Detailed category (e.g. FOOD_AND_DRINK_RESTAURANT).
          required:
          - provider
          - bankTransactionId
        cardId:
          type:
          - string
          - 'null'
          format: uuid
          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
          - 'null'
          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
          - 'null'
          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
    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
  parameters:
    transaction-message-id-2:
      in: path
      name: transactionMessageId
      required: true
      schema:
        type: string
        format: uuid
      example: 9340721f-bdce-4afa-bd9d-26cceb9d2176
  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