Finicity

Finicity Tx Push API

Manage TxPush subscriptions

GitHub OpenAPI
Business capability
Webhook & Event Subscription Management BC-4270.80

Operations 4

POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/txpush Subscribe to TxPush Notifications #
DELETE /aggregation/v1/customers/{customerId}/accounts/{accountId}/txpush Disable TxPush Notifications #
POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/transactions Create TxPush Test Transaction #
DELETE /aggregation/v1/customers/{customerId}/subscriptions/{subscriptionId} Delete TxPush Subscription #

Documentation

📖
Documentation
https://developer.mastercard.com/open-banking-us/documentation/
📖
APIReference
https://developer.mastercard.com/open-banking-us/documentation/api-reference/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/finicity/refs/heads/main/openapi/finicity-txpush-api-openapi.yml

Other Resources

🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/finicity/refs/heads/main/asyncapi/finicity-webhooks.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/finicity-txpush-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

finicity-txpush-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Open Finance Tx Push API
  description: 'OpenAPI specification for Finicity APIs.


    Open Finance (formerly Open Banking) solutions in the US are provided by

    Finicity, a Mastercard company.'
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/open-finance-us/documentation/support/
  version: 1.43.0
servers:
- url: https://api.finicity.com
  description: Production
security:
- FinicityAppKey: []
  FinicityAppToken: []
tags:
- name: TxPush
  description: Manage TxPush subscriptions
paths:
  /aggregation/v1/customers/{customerId}/accounts/{accountId}/txpush:
    post:
      tags:
      - TxPush
      summary: Subscribe to TxPush Notifications
      description: 'Register a client app''s TxPush Listener to receive TxPush notifications related to the given account.


        Each call to this service will return two records, one with class account and one with class transaction. Account events are sent when values change in the account''s fields (such as `balance` or `interestRate`). Transaction events are sent whenever a new transaction is posted for the account. For institutions that do not provide TxPush services, notifications are sent as soon as Finicity finds a new transaction or new account data through regular aggregation processes.


        The listener''s URL must be secure (HTTPS) for any real-world account. In addition, the client''s TxPush Listener will need to be verified. HTTP and HTTPS connections are only allowed on the standard ports 80 (HTTP) and 443 (HTTPS). The use of other ports will result with the call failing.


        For additional details on this process, see TxPush Listener Service.


        _Supported regions_: !🇺🇸'
      operationId: SubscribeToTxPushNotifications
      parameters:
      - $ref: '#/components/parameters/CustomerIdParameter'
      - $ref: '#/components/parameters/AccountIdParameter'
      requestBody:
        $ref: '#/components/requestBodies/SubscribeToTxPushNotificationsRequest'
      responses:
        '201':
          $ref: '#/components/responses/SubscribeToTxPushNotificationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundErrorResponse'
    delete:
      tags:
      - TxPush
      summary: Disable TxPush Notifications
      description: 'Delete all TxPush subscriptions with their notifications for the given account. No more notifications will be sent for account or transaction events.


        For additional details on this process, see TxPush Listener Service.


        _Supported regions_: !🇺🇸'
      operationId: DisableTxPushNotifications
      parameters:
      - $ref: '#/components/parameters/CustomerIdParameter'
      - $ref: '#/components/parameters/AccountIdParameter'
      responses:
        '204':
          $ref: '#/components/responses/DisableTxPushNotificationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundErrorResponse'
  /aggregation/v1/customers/{customerId}/accounts/{accountId}/transactions:
    post:
      tags:
      - TxPush
      summary: Create TxPush Test Transaction
      description: 'Inject a transaction into the transaction list for a testing account. This allows an app to trigger TxPush notifications for the account in order to test the app''s TxPush Listener service. This causes the platform to send one transaction event and one account event (showing that the account balance has changed). This service is only supported for testing accounts.


        For additional details on this process, see TxPush Listener Service.


        _Supported regions_: !🇺🇸'
      operationId: CreateTxPushTestTransaction
      parameters:
      - $ref: '#/components/parameters/CustomerIdParameter'
      - $ref: '#/components/parameters/AccountIdParameter'
      requestBody:
        $ref: '#/components/requestBodies/CreateTxPushTestTransactionRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateTxPushTestTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundErrorResponse'
  /aggregation/v1/customers/{customerId}/subscriptions/{subscriptionId}:
    delete:
      tags:
      - TxPush
      summary: Delete TxPush Subscription
      description: 'Delete a specific subscription to TxPush notifications for the given account. This could be individual deleting the account or transactions events. No more events will be sent for that specific subscription.


        For additional details on this process, see TxPush Listener Service.


        _Supported regions_: !🇺🇸'
      operationId: DeleteTxPushSubscription
      parameters:
      - $ref: '#/components/parameters/CustomerIdParameter'
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      responses:
        '204':
          $ref: '#/components/responses/DeleteTxPushSubscriptionResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundErrorResponse'
components:
  examples:
    MissingFinicityAppKeyExample:
      value:
        code: '10026'
        message: Missing parameter (Finicity-App-Key)
    ResourceNotFoundExample:
      value:
        code: '14001'
        message: Resource not found.
    NoRegisteredApplicationExample:
      value:
        code: '50051'
        message: No registered partner applications found.
    InvalidConsumerSSNExample:
      value:
        code: '10100'
        message: Invalid format for field consumer.ssn.  Required format is 9 digits.
    ResellerInvalidDateRangeGreaterThanEndDateExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - startDate is greaterThan endDate'
    CustomerReportLimitExceedExample:
      value:
        code: '20400'
        message: The max report generation limit was exceeded for this customer.
    BadCredentialsExample:
      value:
        code: '24302'
        message: Bad credentials
    ExpiredTokenExample:
      value:
        code: '10023'
        message: Expired (Finicity-App-Token)
    ResellerInvalidDateRangeGreaterThan31DaysExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - It is more than 31 days'
    InvalidExperienceFieldExample:
      value:
        code: '10010'
        status: '400'
        message: '"experience" must be a valid GUID'
        user_message: One or more of the fields could not be validated. Please ensure you have entered the correct data.
        tags: ''
    NoConsumerForCustomerExample:
      value:
        code: '10100'
        message: Cannot find consumer for customer with id 5011115315."
    MissingFinicityAppTokenExample:
      value:
        code: '10024'
        message: Missing parameter (Finicity-App-Token)
    InvalidFieldExample:
      value:
        code: '10010'
        status: '400'
        message: Customer ID does not exist or does not belong to this partner
        user_message: One or more of the fields could not be validated. Please ensure you have entered the correct data.
        tags: ''
    AccountTypeNotSupportedExample:
      value:
        code: '14020'
        message: Bad request. (Account type not supported).
    InvalidConsumerPhoneExample:
      value:
        code: '10100'
        message: Invalid format for field consumer.phone.
    MissingFieldExample:
      value:
        code: '10005'
        message: Missing parameter (partnerId)
    InvalidConsumerEmailExample:
      value:
        code: '10100'
        message: Invalid format for field consumer.email.
    ResellerInvalidDateRangeLessThanZeroExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - start or end date less than or equal to zero'
    ResellerNoReportForPartnerExample:
      value:
        code: '10100'
        message: Cannot find resellerBilling reports with id 2445581559892.
    BothCraAndFtcPurposeTrueExample:
      value:
        code: '10100'
        status: '400'
        message: forCRAPurpose and forFTCPurpose may not both be TRUE.
    ConsumerNotFoundExample:
      value:
        code: '10100'
        message: Cannot find consumer with id 1234.
    InvalidFinicityAppTokenExample:
      value:
        code: '10022'
        message: Invalid (Finicity-App-Token)
    InvalidValueExample:
      value:
        code: '1618'
        message: Negative or invalid value entered. Please use positive numbers only.
    GenericBadRequestExample:
      value:
        code: '14020'
        message: Bad request.
    PermissiblePurposeCodeExample:
      value:
        code: '10100'
        status: '400'
        message: Permissible Purpose Code is required
    NoAccountForInstitutionLoginIdExample:
      value:
        code: '38007'
        message: Customer does not have any accounts associated with institutionLoginId.
    ResellerInvalidDateRangeExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - start or end date is empty or null'
    ResellerPartnerNotAuthorizedExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Partner is not authorized to access resellerBilling reports for partnerId 2445583947903'
    ResellerNoDataForPartnerExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Reports not found 2445583947903 resellerBilling reports'
    CustomerNotFoundExample:
      value:
        code: '14001'
        message: Customer not found.
    InvalidForesightReportRequestExample:
      value:
        code: '10100'
        message: At least one of customerId or externalCustomerId must be provided; both are also allowed.
    ExpiredFinicityAppTokenExample:
      value:
        code: '10023'
        message: Expired (Finicity-App-Token)
  schemas:
    AssetId:
      type: string
      description: An asset ID. Generated by Data Connect or by using the Store Customer Pay Statement API.
      example: 097545c5-1c2a-4f20-a5ef-77f0820344c9-2018601178
    SubscriptionRecord:
      required:
      - id
      - accountId
      - type
      - callbackUrl
      - signingKey
      type: object
      properties:
        id:
          $ref: '#/components/schemas/SubscriptionId'
        accountId:
          $ref: '#/components/schemas/NumericAccountId'
        type:
          $ref: '#/components/schemas/SubscriptionType'
        callbackUrl:
          $ref: '#/components/schemas/TxPushCallbackUrl'
        signingKey:
          type: string
          description: Signing key for events
          example: zg4U0v1IvTzFEHIXzJMxPHnfUwWZAMVpXrUuNuL9IvZI0QzkDdwp39IAKuNOFxOVqCOgHLMS1Zpe4ZL40NX83aJkqI6v0Ez5B7BLBtvr7Ag11kPH3uG1taTeOV0CTyI4LOg7ohSHn0DqaRu2aBq26KI90nYe0CecTCzzhu4yMXL43JV8YfydAexNdkzfg8tY44MlhBPUh2neHW2EFTT2ja4s4Ul10JgID03un8WBSrIm2adHw3QYJB4jk4k1e
      description: TxPush subscription details
    TransactionId:
      type: integer
      description: A transaction ID
      format: int64
      example: 21284820852
    TxPushSubscriptions:
      required:
      - subscriptions
      type: object
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionRecord'
    TxPushSubscriptionParameters:
      required:
      - callbackUrl
      type: object
      properties:
        callbackUrl:
          $ref: '#/components/schemas/TxPushCallbackUrl'
    CustomerId:
      type: string
      description: A customer ID. See Add Customer API for how to create a customer ID.
      example: '1005061234'
    UnixDate:
      type: integer
      description: 'A date in Unix epoch time (in seconds). See: [Handling Epoch Dates and Times](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/).'
      format: int64
      example: 1607450357
    TestTxPushTransaction:
      description: A fake transaction for TxPush testing
      required:
      - amount
      - description
      - transactionDate
      type: object
      properties:
        amount:
          type: number
          description: The amount of the transaction
          example: -4.25
        description:
          type: string
          description: The description of the transaction
          example: a testing transaction description
        status:
          type: string
          description: '"active" or "pending" (optional)'
          default: active
          example: pending
        postedDate:
          $ref: '#/components/schemas/UnixDate'
        transactionDate:
          $ref: '#/components/schemas/UnixDate'
    SubscriptionType:
      type: string
      description: A TxPush subscription type ("account" or "transaction")
      example: account
    AccountId:
      type: string
      description: An account ID
      example: '5011648377'
    ErrorMessage:
      required:
      - code
      type: object
      properties:
        code:
          type: object
          description: 'An error code (can be returned as a number or a string). Useful links: [Common API Status Codes](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/#common-api-status-codes), [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/#aggregation-status-codes).'
          example: '10001'
        status:
          type: string
          description: A status code
          example: '401'
        title:
          type: string
          description: A title for the error
          example: Connecting accounts error
        level:
          type: string
          description: An error level
          example: error
        message:
          type: string
          description: An error message
          example: Invalid authorization credentials
        user_message:
          type: string
          description: Some more details about the error
          example: The session has expired or is invalid
        assetId:
          $ref: '#/components/schemas/AssetId'
        accountId:
          $ref: '#/components/schemas/AccountId'
        externalTransactionId:
          type: string
          description: A unique identifier for the transaction that assists in linking data back to your systems.
          example: MAC1005061234
          minLength: 1
          maxLength: 100
        tags:
          type: string
          description: Categories that the error belongs to
          example: AGG
    TxPushCallbackUrl:
      type: string
      description: A callback URL to receive TxPush notifications
      example: https://www.example.com/txpush/listener
    NumericAccountId:
      type: integer
      format: int64
      description: An account ID represented as a number
      example: 5011648377
    CreatedTestTxPushTransaction:
      required:
      - id
      - createdDate
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TransactionId'
        createdDate:
          $ref: '#/components/schemas/UnixDate'
      description: Response for TxPush test transaction
    SubscriptionId:
      description: ID of a TxPush subscription
      type: integer
      format: int64
      example: 17554874
  parameters:
    CustomerIdParameter:
      description: A customer ID
      name: customerId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/CustomerId'
      example: '1005061234'
    SubscriptionIdParameter:
      description: The subscription ID
      name: subscriptionId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/SubscriptionId'
      example: 17554874
    AccountIdParameter:
      description: The account ID
      name: accountId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/AccountId'
      example: '5011648377'
  responses:
    CreateTxPushTestTransactionResponse:
      description: The test notification was successfully sent
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreatedTestTxPushTransaction'
    BadRequestErrorResponse:
      description: The request was rejected
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            PermissiblePurposeCodeExample:
              $ref: '#/components/examples/PermissiblePurposeCodeExample'
            InvalidForesightReportRequestExample:
              $ref: '#/components/examples/InvalidForesightReportRequestExample'
            BothCraAndFtcPurposeTrueExample:
              $ref: '#/components/examples/BothCraAndFtcPurposeTrueExample'
            MissingFieldExample:
              $ref: '#/components/examples/MissingFieldExample'
            InvalidFieldExample:
              $ref: '#/components/examples/InvalidFieldExample'
            InvalidExperienceFieldExample:
              $ref: '#/components/examples/InvalidExperienceFieldExample'
            GenericBadRequestExample:
              $ref: '#/components/examples/GenericBadRequestExample'
            AccountTypeNotSupportedExample:
              $ref: '#/components/examples/AccountTypeNotSupportedExample'
            ResellerPartnerNotAuthorizedExample:
              $ref: '#/components/examples/ResellerPartnerNotAuthorizedExample'
            ResellerInvalidDateRangeExample:
              $ref: '#/components/examples/ResellerInvalidDateRangeExample'
            ResellerInvalidDateRangeLessThanZeroExample:
              $ref: '#/components/examples/ResellerInvalidDateRangeLessThanZeroExample'
            ResellerInvalidDateRangeGreaterThanEndDateExample:
              $ref: '#/components/examples/ResellerInvalidDateRangeGreaterThanEndDateExample'
            ResellerInvalidDateRangeGreaterThan31DaysExample:
              $ref: '#/components/examples/ResellerInvalidDateRangeGreaterThan31DaysExample'
            CustomerReportLimitExceedExample:
              $ref: '#/components/examples/CustomerReportLimitExceedExample'
            InvalidConsumerSSNExample:
              $ref: '#/components/examples/InvalidConsumerSSNExample'
            InvalidConsumerPhoneExample:
              $ref: '#/components/examples/InvalidConsumerPhoneExample'
            InvalidConsumerEmailExample:
              $ref: '#/components/examples/InvalidConsumerEmailExample'
            InvalidValue:
              $ref: '#/components/examples/InvalidValueExample'
    ResourceNotFoundErrorResponse:
      description: The resource doesn't exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            ConsumerNotFoundExample:
              $ref: '#/components/examples/ConsumerNotFoundExample'
            NoAccountForInstitutionLoginIdExample:
              $ref: '#/components/examples/NoAccountForInstitutionLoginIdExample'
            CustomerNotFoundExample:
              $ref: '#/components/examples/CustomerNotFoundExample'
            NoConsumerForCustomerExample:
              $ref: '#/components/examples/NoConsumerForCustomerExample'
            ResourceNotFoundExample:
              $ref: '#/components/examples/ResourceNotFoundExample'
            NoRegisteredApplicationExample:
              $ref: '#/components/examples/NoRegisteredApplicationExample'
            ResellerNoDataForPartnerExample:
              $ref: '#/components/examples/ResellerNoDataForPartnerExample'
            ResellerNoReportForPartnerExample:
              $ref: '#/components/examples/ResellerNoReportForPartnerExample'
    DeleteTxPushSubscriptionResponse:
      description: The subscription was successfully deleted
    SubscribeToTxPushNotificationsResponse:
      description: The subscription was successfully created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TxPushSubscriptions'
    DisableTxPushNotificationsResponse:
      description: Subscriptions were successfully deleted for the given account
    UnauthorizedErrorResponse:
      description: The request lacks valid authentication credentials. Check "Finicity-App-Key" or "Finicity-App-Token".
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            ExpiredTokenExample:
              $ref: '#/components/examples/ExpiredTokenExample'
            MissingFinicityAppKeyExample:
              $ref: '#/components/examples/MissingFinicityAppKeyExample'
            MissingFinicityAppTokenExample:
              $ref: '#/components/examples/MissingFinicityAppTokenExample'
            InvalidFinicityAppTokenExample:
              $ref: '#/components/examples/InvalidFinicityAppTokenExample'
            ExpiredFinicityAppTokenExample:
              $ref: '#/components/examples/ExpiredFinicityAppTokenExample'
            BadCredentialsExample:
              $ref: '#/components/examples/BadCredentialsExample'
        text/plain:
          schema:
            type: string
            example: Invalid (Finicity-App-Key)
  requestBodies:
    CreateTxPushTestTransactionRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TestTxPushTransaction'
    SubscribeToTxPushNotificationsRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TxPushSubscriptionParameters'
  securitySchemes:
    FinicityAppKey:
      name: Finicity-App-Key
      type: apiKey
      in: header
      description: The "Finicity-App-Key" from the developer dashboard
    FinicityAppToken:
      name: Finicity-App-Token
      type: apiKey
      in: header
      description: A token returned by the `/authentication` API