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](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/#setting-up-the-txpush-listener-service).


        _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)'
      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](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/#setting-up-the-txpush-listener-service).


        _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)'
      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](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/#setting-up-the-txpush-listener-service).


        _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)'
      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](https://developer.mastercard.com/open-finance-us/documentation/products/manage/tx-push/#setting-up-the-txpush-listener-service).


        _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)'
      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)
    InvalidForesightReportRequestExample:
      value:
        code: '10100'
        message: At least one of customerId or externalCustomerId must be provided; both are also allowed.
    ResellerInvalidDateRangeGreaterThan31DaysExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - It is more than 31 days'
    ResellerInvalidDateRangeGreaterThanEndDateExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - startDate is greaterThan endDate'
    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.
    ResellerPartnerNotAuthorizedExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Partner is not authorized to access resellerBilling reports for partnerId 2445583947903'
    InvalidConsumerPhoneExample:
      value:
        code: '10100'
        message: Invalid format for field consumer.phone.
    MissingFieldExample:
      value:
        code: '10005'
        message: Missing parameter (partnerId)
    NoRegisteredApplicationExample:
      value:
        code: '50051'
        message: No registered partner applications found.
    ExpiredFinicityAppTokenExample:
      value:
        code: '10023'
        message: Expired (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: ''
    InvalidValueExample:
      value:
        code: '1618'
        message: Negative or invalid value entered. Please use positive numbers only.
    InvalidConsumerSSNExample:
      value:
        code: '10100'
        message: Invalid format for field consumer.ssn.  Required format is 9 digits.
    InvalidFinicityAppTokenExample:
      value:
        code: '10022'
        message: Invalid (Finicity-App-Token)
    ResellerInvalidDateRangeLessThanZeroExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - start or end date less than or equal to zero'
    CustomerReportLimitExceedExample:
      value:
        code: '20400'
        message: The max report generation limit was exceeded for this customer.
    NoAccountForInstitutionLoginIdExample:
      value:
        code: '38007'
        message: Customer does not have any accounts associated with institutionLoginId.
    CustomerNotFoundExample:
      value:
        code: '14001'
        message: Customer not found.
    ResellerNoDataForPartnerExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Reports not found 2445583947903 resellerBilling reports'
    InvalidConsumerEmailExample:
      value:
        code: '10100'
        message: Invalid format for field consumer.email.
    ResellerInvalidDateRangeExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - start or end date is empty or null'
    ExpiredTokenExample:
      value:
        code: '10023'
        message: Expired (Finicity-App-Token)
    AccountTypeNotSupportedExample:
      value:
        code: '14020'
        message: Bad request. (Account type not supported).
    PermissiblePurposeCodeExample:
      value:
        code: '10100'
        status: '400'
        message: Permissible Purpose Code is required
    ResourceNotFoundExample:
      value:
        code: '14001'
        message: Resource not found.
    ConsumerNotFoundExample:
      value:
        code: '10100'
        message: Cannot find consumer with id 1234.
    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: ''
    GenericBadRequestExample:
      value:
        code: '14020'
        message: Bad request.
    BadCredentialsExample:
      value:
        code: '24302'
        message: Bad credentials
    NoConsumerForCustomerExample:
      value:
        code: '10100'
        message: Cannot find consumer for customer with id 5011115315."
    MissingFinicityAppTokenExample:
      value:
        code: '10024'
        message: Missing parameter (Finicity-App-Token)
  responses:
    CreateTxPushTestTransactionResponse:
      description: The test notification was successfully sent
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreatedTestTxPushTransaction'
    SubscribeToTxPushNotificationsResponse:
      description: The subscription was successfully created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TxPushSubscriptions'
    DeleteTxPushSubscriptionResponse:
      description: The subscription was successfully deleted
    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'
    DisableTxPushNotificationsResponse:
      description: Subscriptions were successfully deleted for the given account
    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'
    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)
  schemas:
    CreatedTestTxPushTransaction:
      required:
      - id
      - createdDate
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TransactionId'
        createdDate:
          $ref: '#/components/schemas/UnixDate'
      description: Response for TxPush test transaction
    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
    AccountId:
      type: string
      description: An account ID
      example: '5011648377'
    SubscriptionType:
      type: string
      description: A TxPush subscription type ("account" or "transaction")
      example: account
    TxPushSubscriptions:
      required:
      - subscriptions
      type: object
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionRecord'
    TransactionId:
      type: integer
      description: A transaction ID
      format: int64
      example: 21284820852
    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
    TxPushSubscriptionParameters:
      required:
      - callbackUrl
      type: object
      properties:
        callbackUrl:
          $ref: '#/components/schemas/TxPushCallbackUrl'
    TxPushCallbackUrl:
      type: string
      description: A callback URL to receive TxPush notifications
      example: https://www.example.com/txpush/listener
    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'
    SubscriptionId:
      description: ID of a TxPush subscription
      type: integer
      format: int64
      example: 17554874
    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
    CustomerId:
      type: string
      description: A customer ID. See Add Customer API for how to create a customer ID.
      example: '1005061234'
    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
    NumericAccountId:
      type: integer
      format: int64
      description: An account ID represented as a number
      example: 5011648377
  parameters:
    CustomerIdParameter:
      description: A customer ID
      name: customerId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/CustomerId'
      example: '1005061234'
    AccountIdParameter:
      description: The account ID
      name: accountId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/AccountId'
      example: '5011648377'
    SubscriptionIdParameter:
      description: The subscription ID
      name: subscriptionId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/SubscriptionId'
      example: 17554874
  requestBodies:
    SubscribeToTxPushNotificationsRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TxPushSubscriptionParameters'
    CreateTxPushTestTransactionRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TestTxPushTransaction'
  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