events-openapi.yaml

openapi: 3.0.0
info:
  title: Events API Specification - ASPSP Endpoints
  description: >-
    OpenAPI for Events (Subscription & Aggregated Polling) API Specification -
    ASPSP Endpoints
  termsOfService: https://www.openbanking.org.uk/terms
  contact:
    name: Service Desk
    email: ServiceDesk@openbanking.org.uk
  license:
    name: open-licence
    url: https://www.openbanking.org.uk/open-licence
  version: 4.0.0
paths:
  /event-subscriptions:
    post:
      tags:
        - Event Subscriptions
      summary: Create Event Subscription
      operationId: CreateEventSubscriptions
      parameters:
        - $ref: '#/components/parameters/x-fapi-auth-date'
        - $ref: '#/components/parameters/x-fapi-customer-ip-address'
        - $ref: '#/components/parameters/x-fapi-interaction-id'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/x-jws-signature'
        - $ref: '#/components/parameters/x-customer-user-agent'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/OBEventSubscription1'
          application/jose+jwe:
            schema:
              $ref: '#/components/schemas/OBEventSubscription1'
        description: Default
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201EventSubscriptionsCreated'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '405':
          $ref: '#/components/responses/405Error'
        '406':
          $ref: '#/components/responses/406Error'
        '409':
          $ref: '#/components/responses/409Error'
        '415':
          $ref: '#/components/responses/415Error'
        '429':
          $ref: '#/components/responses/429Error'
        '500':
          $ref: '#/components/responses/500Error'
      security:
        - TPPOAuth2Security:
            - accounts
            - payments
            - fundsconfirmations
    get:
      tags:
        - Event Subscriptions
      summary: Get Event Subscription
      operationId: GetEventSubscriptions
      parameters:
        - $ref: '#/components/parameters/x-fapi-auth-date'
        - $ref: '#/components/parameters/x-fapi-customer-ip-address'
        - $ref: '#/components/parameters/x-fapi-interaction-id'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/x-customer-user-agent'
      responses:
        '200':
          $ref: '#/components/responses/200EventSubscriptionsRead'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '405':
          $ref: '#/components/responses/405Error'
        '406':
          $ref: '#/components/responses/406Error'
        '429':
          $ref: '#/components/responses/429Error'
        '500':
          $ref: '#/components/responses/500Error'
      security:
        - TPPOAuth2Security:
            - accounts
            - payments
            - fundsconfirmations
  /event-subscriptions/{EventSubscriptionId}:
    put:
      tags:
        - Event Subscriptions
      summary: Change Event Subscription
      operationId: ChangeEventSubscriptionsEventSubscriptionId
      parameters:
        - $ref: '#/components/parameters/EventSubscriptionId'
        - $ref: '#/components/parameters/x-fapi-auth-date'
        - $ref: '#/components/parameters/x-fapi-customer-ip-address'
        - $ref: '#/components/parameters/x-fapi-interaction-id'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/x-jws-signature'
        - $ref: '#/components/parameters/x-customer-user-agent'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/OBEventSubscriptionResponse1'
          application/jose+jwe:
            schema:
              $ref: '#/components/schemas/OBEventSubscriptionResponse1'
        description: Default
        required: true
      responses:
        '200':
          $ref: >-
            #/components/responses/200EventSubscriptionsEventSubscriptionIdChanged
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '405':
          $ref: '#/components/responses/405Error'
        '406':
          $ref: '#/components/responses/406Error'
        '415':
          $ref: '#/components/responses/415Error'
        '429':
          $ref: '#/components/responses/429Error'
        '500':
          $ref: '#/components/responses/500Error'
      security:
        - TPPOAuth2Security:
            - accounts
            - payments
            - fundsconfirmations
    delete:
      tags:
        - Event Subscriptions
      summary: Delete Event Subscription
      operationId: DeleteEventSubscriptionsEventSubscriptionId
      parameters:
        - $ref: '#/components/parameters/EventSubscriptionId'
        - $ref: '#/components/parameters/x-fapi-auth-date'
        - $ref: '#/components/parameters/x-fapi-customer-ip-address'
        - $ref: '#/components/parameters/x-fapi-interaction-id'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/x-customer-user-agent'
      responses:
        '204':
          $ref: >-
            #/components/responses/204EventSubscriptionsEventSubscriptionIdDeleted
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '405':
          $ref: '#/components/responses/405Error'
        '406':
          $ref: '#/components/responses/406Error'
        '429':
          $ref: '#/components/responses/429Error'
        '500':
          $ref: '#/components/responses/500Error'
      security:
        - TPPOAuth2Security:
            - accounts
            - payments
            - fundsconfirmations
  /events:
    post:
      tags:
        - Events
      summary: Create Events
      operationId: CreateEvents
      parameters:
        - $ref: '#/components/parameters/x-fapi-auth-date'
        - $ref: '#/components/parameters/x-fapi-customer-ip-address'
        - $ref: '#/components/parameters/x-fapi-interaction-id'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/x-customer-user-agent'
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/OBEventPolling1'
          application/jose+jwe:
            schema:
              $ref: '#/components/schemas/OBEventPolling1'
        description: Default
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200EventsRead'
        '201':
          $ref: '#/components/responses/201EventsCreated'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '405':
          $ref: '#/components/responses/405Error'
        '406':
          $ref: '#/components/responses/406Error'
        '415':
          $ref: '#/components/responses/415Error'
        '429':
          $ref: '#/components/responses/429Error'
        '500':
          $ref: '#/components/responses/500Error'
      security:
        - TPPOAuth2Security:
            - accounts
            - payments
            - fundsconfirmations
servers:
  - url: /open-banking/v4.0
components:
  parameters:
    EventSubscriptionId:
      name: EventSubscriptionId
      in: path
      description: EventSubscriptionId
      required: true
      schema:
        type: string
    Authorization:
      in: header
      name: Authorization
      required: true
      description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750
      schema:
        type: string
    x-customer-user-agent:
      in: header
      name: x-customer-user-agent
      description: Indicates the user-agent that the PSU is using.
      required: false
      schema:
        type: string
    x-fapi-customer-ip-address:
      in: header
      name: x-fapi-customer-ip-address
      required: false
      description: The PSU's IP address if the PSU is currently logged in with the TPP.
      schema:
        type: string
    x-fapi-auth-date:
      in: header
      name: x-fapi-auth-date
      required: false
      description: >-
        The time when the PSU last logged in with the TPP. 

        All dates in the HTTP headers are represented as RFC 7231 Full Dates. An
        example is below: 

        Sun, 10 Sep 2017 19:43:31 UTC
      schema:
        type: string
        pattern: >-
          ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2}
          (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4}
          \d{2}:\d{2}:\d{2} (GMT|UTC)$
    x-fapi-interaction-id:
      in: header
      name: x-fapi-interaction-id
      required: false
      description: An RFC4122 UID used as a correlation id.
      schema:
        type: string
    x-idempotency-key:
      name: x-idempotency-key
      in: header
      description: |
        Every request will be processed only once per x-idempotency-key.  The
        Idempotency Key will be valid for 24 hours.
      required: true
      schema:
        type: string
        maxLength: 40
        pattern: ^(?!\s)(.*)(\S)$
    x-jws-signature:
      in: header
      name: x-jws-signature
      required: true
      description: A detached JWS signature of the body of the payload.
      schema:
        type: string
  responses:
    201EventSubscriptionsCreated:
      description: Event Subscription Created
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
        x-jws-signature:
          description: >
            Header containing a detached JWS signature of the body of the
            payload.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBEventSubscriptionResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBEventSubscriptionResponse1'
    200EventSubscriptionsRead:
      description: Event Subscription Read
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
        x-jws-signature:
          description: >
            Header containing a detached JWS signature of the body of the
            payload.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBEventSubscriptionsResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBEventSubscriptionsResponse1'
    200EventSubscriptionsEventSubscriptionIdChanged:
      description: Event Subscription Changed
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
        x-jws-signature:
          description: >
            Header containing a detached JWS signature of the body of the
            payload.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBEventSubscriptionResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBEventSubscriptionResponse1'
    204EventSubscriptionsEventSubscriptionIdDeleted:
      description: Event Subscription Deleted
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    201EventsCreated:
      description: Events Created
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBEventPollingResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBEventPollingResponse1'
    200EventsRead:
      description: Read awaiting events
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBEventPollingResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBEventPollingResponse1'
    400Error:
      description: Bad request
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
    401Error:
      description: Unauthorized
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    403Error:
      description: Forbidden
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
    404Error:
      description: Not found
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    405Error:
      description: Method Not Allowed
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    406Error:
      description: Not Acceptable
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    409Error:
      description: Conflict
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    415Error:
      description: Unsupported Media Type
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    429Error:
      description: Too Many Requests
      headers:
        Retry-After:
          description: Number in seconds to wait
          schema:
            type: integer
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
    500Error:
      description: Internal Server Error
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
        application/jose+jwe:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
  securitySchemes:
    TPPOAuth2Security:
      type: oauth2
      description: TPP client credential authorisation flow with the ASPSP
      flows:
        clientCredentials:
          tokenUrl: https://authserver.example/token
          scopes:
            accounts: Ability to receive events associated with Accounts information
            fundsconfirmations: Ability to receive events associated with confirmation of funds
            payments: Ability to receive events associated with payments
  schemas:
    ISODateTime:
      description: >-
        All dates in the JSON payloads are represented in ISO 8601 date-time
        format. 

        All date-time fields in responses must include the timezone. An example
        is below:

        2017-04-05T10:43:07+00:00
      type: string
      format: date-time
    Links:
      type: object
      description: Links relevant to the payload
      properties:
        Self:
          type: string
          format: uri
        First:
          type: string
          format: uri
        Prev:
          type: string
          format: uri
        Next:
          type: string
          format: uri
        Last:
          type: string
          format: uri
      additionalProperties: false
      required:
        - Self
    Meta:
      title: MetaData
      type: object
      description: Meta Data relevant to the payload
      properties:
        TotalPages:
          type: integer
          format: int32
        FirstAvailableDateTime:
          $ref: '#/components/schemas/ISODateTime'
        LastAvailableDateTime:
          $ref: '#/components/schemas/ISODateTime'
      additionalProperties: false
    OBError1:
      type: object
      properties:
        ErrorCode:
          $ref: '#/components/schemas/OBExternalStatusReason1Code'
        Message:
          description: >-
            A description of the error that occurred. e.g., 'A mandatory field
            isn't supplied' or 'RequestedExecutionDateTime must be in future'

            OBIE doesn't standardise this field
          type: string
          minLength: 1
          maxLength: 500
        Path:
          description: >-
            Recommended but optional reference to the JSON Path of the field
            with error, e.g., Data.Initiation.InstructedAmount.Currency
          type: string
          minLength: 1
          maxLength: 500
        Url:
          description: >-
            URL to help remediate the problem, or provide more information, or
            to API Reference, or help etc
          type: string
      required:
        - ErrorCode
      additionalProperties: false
      minProperties: 1
    OBErrorResponse1:
      description: >-
        An array of detail error codes, and messages, and URLs to documentation
        to help remediation.
      type: object
      properties:
        Id:
          description: >-
            A unique reference for the error instance, for audit purposes, in
            case of unknown/unclassified errors.
          type: string
          minLength: 1
          maxLength: 40
        Code:
          description: >-
            Deprecated <br>High level textual error code, to help categorise the
            errors.
          type: string
          minLength: 1
          example: 400 BadRequest
          maxLength: 40
        Message:
          description: Deprecated <br>Brief Error message
          type: string
          minLength: 1
          example: There is something wrong with the request parameters provided
          maxLength: 500
        Errors:
          items:
            $ref: '#/components/schemas/OBError1'
          type: array
          minItems: 1
      required:
        - Errors
      additionalProperties: false
    OBEventSubscription1:
      type: object
      required:
        - Data
      properties:
        Data:
          type: object
          required:
            - Version
          properties:
            CallbackUrl:
              description: >-
                Callback URL for a TPP hosted service. Will be used by ASPSPs,
                in conjunction with the resource name, to construct a URL to
                send event notifications to.
              type: string
              format: uri
            Version:
              $ref: '#/components/schemas/Version'
            EventTypes:
              type: array
              items:
                description: Array of event types the subscription applies to.
                type: string
      additionalProperties: false
    OBEventSubscriptionResponse1:
      type: object
      required:
        - Data
      properties:
        Data:
          type: object
          required:
            - EventSubscriptionId
            - Version
          properties:
            EventSubscriptionId:
              description: >-
                Unique identification as assigned by the ASPSP to uniquely
                identify the callback URL resource.
              type: string
              minLength: 1
              maxLength: 40
            CallbackUrl:
              description: >-
                Callback URL for a TPP hosted service. Will be used by ASPSPs,
                in conjunction with the resource name, to construct a URL to
                send event notifications to.
              type: string
              format: uri
            Version:
              $ref: '#/components/schemas/Version'
            EventTypes:
              type: array
              items:
                description: Array of event types the subscription applies to.
                type: string
        Links:
          $ref: '#/components/schemas/Links'
        Meta:
          $ref: '#/components/schemas/Meta'
      additionalProperties: false
    OBEventSubscriptionsResponse1:
      type: object
      required:
        - Data
      properties:
        Data:
          type: object
          properties:
            EventSubscription:
              type: array
              items:
                type: object
                required:
                  - EventSubscriptionId
                  - Version
                properties:
                  EventSubscriptionId:
                    description: >-
                      Unique identification as assigned by the ASPSP to uniquely
                      identify the callback url resource.
                    type: string
                    minLength: 1
                    maxLength: 40
                  CallbackUrl:
                    description: >-
                      Callback URL for a TPP hosted service. Will be used by
                      ASPSPs, in conjunction with the resource name, to
                      construct a URL to send event notifications to.
                    type: string
                    format: uri
                  Version:
                    $ref: '#/components/schemas/Version'
                  EventTypes:
                    type: array
                    items:
                      description: Array of event types the subscription applies to.
                      type: string
        Links:
          $ref: '#/components/schemas/Links'
        Meta:
          $ref: '#/components/schemas/Meta'
      additionalProperties: false
    Version:
      description: Version for the event notification.
      type: string
      minLength: 1
      maxLength: 10
    OBEventPolling1:
      type: object
      properties:
        maxEvents:
          description: >-
            Maximum number of events to be returned. A value of zero indicates
            the ASPSP should not return events even if available
          type: integer
        returnImmediately:
          description: >-
            Indicates whether an ASPSP should return a response immediately or
            provide a long poll
          type: boolean
        ack:
          type: array
          items:
            description: "An array of jti\_values indicating event notifications positively acknowledged by the TPP"
            type: string
            minLength: 1
            maxLength: 128
        setErrs:
          type: object
          description: >-
            An object that encapsulates all negative acknowledgements
            transmitted by the TPP
          properties: {}
          additionalProperties:
            type: object
            required:
              - err
              - description
            properties:
              err:
                description: >-
                  A value from the IANA "Security Event Token Delivery Error
                  Codes" registry that identifies the error as defined here 

                  https://tools.ietf.org/id/draft-ietf-secevent-http-push-03.html#error_codes
                type: string
                minLength: 1
                maxLength: 40
              description:
                description: >-
                  A human-readable string that provides additional diagnostic
                  information
                type: string
                minLength: 1
                maxLength: 256
      additionalProperties: false
    OBEventPollingResponse1:
      type: object
      required:
        - moreAvailable
        - sets
      properties:
        moreAvailable:
          description: >-
            A JSON boolean value that indicates if more unacknowledged event
            notifications are available to be returned.
          type: boolean
        sets:
          type: object
          description: >-
            A JSON object that contains zero or more nested JSON attributes. If
            there are no outstanding event notifications to be transmitted, the
            JSON object SHALL be empty.
          properties: {}
          additionalProperties:
            description: "An object named with the jti\_of the\_event notification to be delivered. The value is the event notification, expressed as a\_string.\nThe payload of the event should be defined in the OBEventNotification2\_format."
            type: string
      additionalProperties: false
    OBExternalStatusReason1Code:
      description: >-
        Low level textual error code, for all enum values see
        `ExternalReturnReason1Code` here -
        https://github.com/OpenBankingUK/External_Interal_CodeSets/
      type: string
      minLength: 4
      maxLength: 4
      example: AC17