---
swagger: "2.0"
info:
  x-ibm-name: aggregated-event-polling-api-hfx
  title: Aggregated Event Polling API (HFX)
  description: Aggregated Event Polling API
  version: v3.1.10
basePath: /hfx/open-banking/v3.1
schemes:
- https
consumes:
- application/json; charset=utf-8
- application/jose+jwe
produces:
- application/json; charset=utf-8
- application/jose+jwe
paths:
  /events:
    post:
      tags:
      - Events
      summary: Create Events
      operationId: CreateEvents
      parameters:
      - $ref: '#/parameters/OBEventPolling1Param'
      - $ref: '#/parameters/x-fapi-auth-date'
      - $ref: '#/parameters/x-fapi-customer-ip-address'
      - $ref: '#/parameters/x-fapi-interaction-id'
      - $ref: '#/parameters/Authorization'
      responses:
        201:
          $ref: '#/responses/201EventsCreated'
        400:
          $ref: '#/responses/400Error'
        401:
          $ref: '#/responses/401Error'
        403:
          $ref: '#/responses/403Error'
        404:
          $ref: '#/responses/404Error'
        405:
          $ref: '#/responses/405Error'
        406:
          $ref: '#/responses/406Error'
        415:
          $ref: '#/responses/415Error'
        429:
          $ref: '#/responses/429Error'
        500:
          $ref: '#/responses/500Error'
      security:
      - TPPOAuth2Security:
        - eventpolling
      - TPPOAuth2Security:
        - payments
      - TPPOAuth2Security:
        - accounts
      - TPPOAuth2Security:
        - fundsconfirmations
parameters:
  OBEventPolling1Param:
    name: OBEventPolling1Param
    in: body
    description: Default
    required: true
    schema:
      $ref: '#/definitions/OBEventPolling1'
  Authorization:
    in: header
    name: Authorization
    type: string
    required: true
    description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750
  x-jws-signature:
    in: header
    name: x-jws-signature
    type: string
    required: true
    description: A detached JWS signature of the body of the payload.
  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.
    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. \nAll dates in
      the HTTP headers are represented as RFC 7231 Full Dates. An example is below:
      \nSun, 10 Sep 2017 19:43:31 UTC"
    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.
    type: string
responses:
  201EventsCreated:
    description: Events Created
    headers:
      x-fapi-interaction-id:
        type: string
        description: An RFC4122 UID used as a correlation id.
      x-jws-signature:
        type: string
        description: Header containig a detached JWS signature of the body of the
          payload.
    schema:
      $ref: '#/definitions/OBEventPollingResponse1'
  400Error:
    description: Bad request
    headers:
      x-fapi-interaction-id:
        type: string
        description: An RFC4122 UID used as a correlation id.
    schema:
      $ref: '#/definitions/OBErrorResponse1'
  401Error:
    description: Unauthorized
    headers:
      x-fapi-interaction-id:
        type: string
        description: An RFC4122 UID used as a correlation id.
  403Error:
    description: Forbidden
    headers:
      x-fapi-interaction-id:
        type: string
        description: An RFC4122 UID used as a correlation id.
    schema:
      $ref: '#/definitions/OBErrorResponse1'
  404Error:
    description: Not found
    headers:
      x-fapi-interaction-id:
        type: string
        description: An RFC4122 UID used as a correlation id.
  405Error:
    description: Method Not Allowed
    headers:
      x-fapi-interaction-id:
        type: string
        description: An RFC4122 UID used as a correlation id.
  406Error:
    description: Not Acceptable
    headers:
      x-fapi-interaction-id:
        type: string
        description: An RFC4122 UID used as a correlation id.
  415Error:
    description: Unsupported Media Type
    headers:
      x-fapi-interaction-id:
        type: string
        description: An RFC4122 UID used as a correlation id.
  429Error:
    description: Too Many Requests
    headers:
      Retry-After:
        description: Number in seconds to wait
        type: integer
      x-fapi-interaction-id:
        type: string
        description: An RFC4122 UID used as a correlation id.
  500Error:
    description: Internal Server Error
    headers:
      x-fapi-interaction-id:
        type: string
        description: An RFC4122 UID used as a correlation id.
    schema:
      $ref: '#/definitions/OBErrorResponse1'
securityDefinitions:
  TPPOAuth2Security:
    type: oauth2
    flow: application
    tokenUrl: https://authorise-api.halifax-online.co.uk/prod01/lbg/hfx/oidc-api/v1.1/token
    scopes:
      payments: Generic payments scope
      accounts: Generic Account scope
      fundsconfirmations: Scope for COF
      eventpolling: Ability to poll for, acknowledge and receive Security Event Tokens
    description: TPP client credential authorisation flow with the ASPSP
definitions:
  OBError1:
    type: object
    properties:
      ErrorCode:
        description: Low level textual error code, e.g., UK.OBIE.Field.Missing
        type: string
        x-namespaced-enum:
        - UK.OBIE.Field.Expected
        - UK.OBIE.Field.Invalid
        - UK.OBIE.Field.InvalidDate
        - UK.OBIE.Field.Missing
        - UK.OBIE.Field.Unexpected
        - UK.OBIE.Header.Invalid
        - UK.OBIE.Header.Missing
        - UK.OBIE.Reauthenticate
        - UK.OBIE.Resource.ConsentMismatch
        - UK.OBIE.Resource.InvalidConsentStatus
        - UK.OBIE.Resource.InvalidFormat
        - UK.OBIE.Resource.NotFound
        - UK.OBIE.Rules.AfterCutOffDateTime
        - UK.OBIE.Rules.DuplicateReference
        - UK.OBIE.Signature.Invalid
        - UK.OBIE.Signature.InvalidClaim
        - UK.OBIE.Signature.Malformed
        - UK.OBIE.Signature.Missing
        - UK.OBIE.Signature.MissingClaim
        - UK.OBIE.Signature.Unexpected
        - UK.OBIE.UnexpectedError
        - UK.OBIE.Unsupported.AccountIdentifier
        - UK.OBIE.Unsupported.AccountSecondaryIdentifier
        - UK.OBIE.Unsupported.Currency
        - UK.OBIE.Unsupported.Frequency
        - UK.OBIE.Unsupported.LocalInstrument
        - UK.OBIE.Unsupported.Scheme
      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
    - Message
    additionalProperties: false
    minProperties: 1
  OBErrorResponse1:
    description: An array of detail error codes, and messages, and URLs to documentation
      to help remediation.
    type: object
    properties:
      Code:
        description: High level textual error code, to help categorize the errors.
        type: string
        minLength: 1
        maxLength: 40
      Id:
        description: A unique reference for the error instance, for audit purposes,
          in case of unknown/unclassified errors.
        type: string
        minLength: 1
        maxLength: 40
      Message:
        description: Brief Error message, e.g., 'There is something wrong with the
          request parameters provided'
        type: string
        minLength: 1
        maxLength: 500
      Errors:
        items:
          $ref: '#/definitions/OBError1'
        type: array
        minItems: 1
    required:
    - Code
    - Message
    - Errors
    additionalProperties: false
  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: 50
      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
  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.
            The payload of the event should be defined in the OBEventNotification2 format.
          type: string
    additionalProperties: false
x-ibm-configuration:
  enforced: true
  testable: true
  phase: realized
x-ibm-endpoints:
- endpointUrl: https://secure-api.lloydsbank.com/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api-eidas.halifax.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api-eidas.bankofscotland.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api.mbna.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api.halifax.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api.bankofscotland.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api-eidas.mbna.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api-eidas.lloydsbank.com/prod01/lbg
  type:
  - production
...