openapi: "3.0.1"
info:
  description: Swagger for Event Polling API Specification
  version: 1.0.6
  title: Event Polling API Specification for HK Market
  termsOfService: ''
  license:
    name: open-licence
    url: ''
servers:
  - url: 'https://hsbcdeveloperportalpreprod.digitalapicraft.com:8085/https://sandbox.ob.business.hsbc.com.hk/mock/open-banking/v1.0'
    description: Event Polling Mock endpoints
    variables:
      version:
        default: v1.0
  - url: 'https://secure.sandbox.ob.business.hsbc.com.hk/open-banking/v1.0'
    description: Event Polling endpoints
    variables:
      version:
        default: v1.0      

paths:
  /events:
    post:
      operationId: notificationEvent
      tags:
      - Notification event endpoints
      security:
        - bearerAuthSession: []
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Content-Type'
      - $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/Accept-Language'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationEventRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationEventResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
        '504':
          $ref: '#/components/responses/504'

components:
  schemas:
    errorInfo:
      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
        errors:
          items:
            $ref: '#/components/schemas/HKError1'
          type: array
          minItems: 1
      required:
        - code
        - message
        - errors
      additionalProperties: false

    ApiGatewayErrorResponse:
      description: Error message created by AWS API Gateway
      type: object
      properties:
        message:
          description: Error message
          type: string

    ApiGatewayEmptyResponse:
      description: Error message created by AWS API Gateway
      type: object
      example: ''

    HKError1:
      type: object
      properties:
        code:
          description: 'Low level textual error code, e.g., HK.HKMA.Field.Missing'
          type: string
          x-namespaced-enum:
            - OB.Field.Expected
            - OB.Field.Invalid
            - OB.Field.InvalidDate
            - OB.Field.Missing
            - OB.Field.Unexpected
            - OB.Field.InvalidHeader
            - OB.Field.InvalidDateFormat
            - OB.Field.InvalidDateRange
            - OB.UnexpectedError
            - OB.InternalError
            - OB.InvalidDateRange
            - OB.InvalidDateFormat
            - OB.InvalidRequestParams
            - OB.UnexpectedParamsNo
            - OB.ParamsDuplicated
            - OB.MissingAccountNumber
            - OB.BadRequest
        causes:
          description: |-
            A description of the error that occurred. e.g., 'A mandatory field isn't supplied' or 'RequestedExecutionDateTime must be in future'
            HKMA doesn't standardise this field
          type: string
          minLength: 1
          maxLength: 500
        extendedDetails:
          description: 'Provide details for the error'
          type: object
          properties:
            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
      required:
        - code
        - causes
      additionalProperties: false
      minProperties: 1

    NotificationEventRequest:
      type: object
      required:
        - returnImmediately
        - maxEvents
      properties:
        ack:
          type: array
          description: List of successfully handled “jti”.
          items:
            type: string
        returnImmediately:
          type: boolean
          description: Optional JSON Boolean value that indicates the SET transmitter should return an immediate response even if no results are available (short polling).
        maxEvents:
          type: integer
          description: Size limit for the event collection size in the response, null or zero input for the field indicates the bank returned an empty set of outstanding events.

    NotificationEventResponse:
      type: object
      required:
      - sets
      properties:
        sets:
          type: object
          description: JSON object containing zero or more SETs being returned.  Each member name is the "jti" of a SET to be delivered, and its value is a JSON string representing the corresponding SET.  If there are no outstanding SETs to be transmitted, the JSON object shall be empty.  Note that both SETs being transmitted for the first time and SETs that are being retransmitted after not having been acknowledged are communicated here.
          example:
            4d3559ec67504aaba65d40b0363faad8: 'eyJhbGciOiJub25lIn0.
       eyJqdGkiOiI0ZDM1NTllYzY3NTA0YWFiYTY1ZDQwYjAzNjNmYWFkOCIsImlhdC
       I6MTQ1ODQ5NjQwNCwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwi
       YXVkIjpbImh0dHBzOi8vc2NpbS5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MW
       ZhNWJiYzg3OTU5M2I3NzU0IiwiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tL0Zl
       ZWRzLzVkNzYwNDUxNmIxZDA4NjQxZDc2NzZlZTciXSwiZXZlbnRzIjp7InVybj
       ppZXRmOnBhcmFtczpzY2ltOmV2ZW50OmNyZWF0ZSI6eyJyZWYiOiJodHRwczov
       L3NjaW0uZXhhbXBsZS5jb20vVXNlcnMvNDRmNjE0MmRmOTZiZDZhYjYxZTc1Mj
       FkOSIsImF0dHJpYnV0ZXMiOlsiaWQiLCJuYW1lIiwidXNlck5hbWUiLCJwYXNz
       d29yZCIsImVtYWlscyJdfX19.'
            3d0c3cf797584bd193bd0fb1bd4e7d30: 'eyJqdGkiOiIzZDBjM2NmNzk3NTg0YmQxOTNiZDBmYjFiZDRlN2QzMCIsImlhdC
       I6MTQ1ODQ5NjAyNSwiaXNzIjoiaHR0cHM6Ly9zY2ltLmV4YW1wbGUuY29tIiwi
       YXVkIjpbImh0dHBzOi8vamh1Yi5leGFtcGxlLmNvbS9GZWVkcy85OGQ1MjQ2MW
       ZhNWJiYzg3OTU5M2I3NzU0IiwiaHR0cHM6Ly9qaHViLmV4YW1wbGUuY29tL0Zl
       ZWRzLzVkNzYwNDUxNmIxZDA4NjQxZDc2NzZlZTciXSwic3ViIjoiaHR0cHM6Ly
       9zY2ltLmV4YW1wbGUuY29tL1VzZXJzLzQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIx
       ZDkiLCJldmVudHMiOnsidXJuOmlldGY6cGFyYW1zOnNjaW06ZXZlbnQ6cGFzc3
       dvcmRSZXNldCI6eyJpZCI6IjQ0ZjYxNDJkZjk2YmQ2YWI2MWU3NTIxZDkifSwi
       aHR0cHM6Ly9leGFtcGxlLmNvbS9zY2ltL2V2ZW50L3Bhc3N3b3JkUmVzZXRFeH
       QiOnsicmVzZXRBdHRlbXB0cyI6NX19fQ.'
        moreAvailable:
          type: boolean
          description: Indicates if there are more unacknowledged events from the bank in addition to the current response data list.

  parameters:
    Authorization:
      in: header
      name: Authorization
      description: Standard HTTP header that allows credentials to be provided to the authorisation/resource server. Based on the OAuth 2.0/OIDC framework, this consists of basic or bearer authentication schemes.
      schema:
        type: string
      required: true
    Content-Type:
      in: header
      name: Content-Type
      description: Standard HTTP header indicating the format of the payload provided in the request. Content-type could be set to application/json.
      example: application/json
      schema:
        type: string
      required: true
    Accept-Language:
      in: header
      name: Accept-Language
      description: Standard HTTP header to indicate the natural language set used in the response.
      schema:
        type: string
        enum:
        - en-HK
        - zh-HK
        - zh-CN
    x-fapi-auth-date:
      in: header
      name: x-fapi-auth-date
      description: |-
        Customer last logged-in time with the TSP application.
        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
      example: Sun, 10 Sep 2017 19:43:31 UTC
      schema:
        type: string
    x-fapi-customer-ip-address:
      in: header
      name: x-fapi-customer-ip-address
      description: Customer IP address when making a request with the TSP application.
      schema:
        type: string
      example: 169.254.169.254
    x-fapi-interaction-id:
      in: header
      name: x-fapi-interaction-id
      description: Unique correlation ID to playback response for each request.
      schema:
        type: string

  responses:
    '400':
      description: Bad Request
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    '401':
      description: Unauthorised
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiGatewayEmptyResponse'
    '403':
      description: Forbidden
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiGatewayEmptyResponse'
    '405':
      description: Method Not Allowed
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    '406':
      description: Not Acceptable
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    '415':
      description: Unsupported Media Type
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    '429':
      description: Too Many Requests
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiGatewayErrorResponse'
    '500':
      description: Internal Server Error
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    '503':
      description: Service Unavailable
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiGatewayErrorResponse'
    '504':
      description: Gateway Timeout
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiGatewayErrorResponse'

  headers:
    Content-Type:
      description: Standard HTTP header indicating the format of the payload provided in the request. Content-type could be set to application/json.
      schema:
        type: string
    x-fapi-interaction-id:
      description: Unique correlation ID to playback response for each request.
      schema:
        type: string
    Retry-After:
      description: Header indicating the time (in seconds) that the TSP could wait before retrying an operation. The bank could consider including this header along with responses with the HTTP status code of 429 (Too Many Requests).
      schema:
        type: integer

  securitySchemes:
    apiOAuth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'https://api.hsbc.com/.../...'
          scopes:
            -'': ""
    bearerAuthSession:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        **Sample Value**
        ```
        eyJraWQiOiI1M2Q4NjFjNC1iZTMwLTQzNDItYmU0ZS05N2RlYzQ5YmZhZTIiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI3YjA1NWY4YS01YmJmLTQxZjgtOTYwMC05MTFjNTgyMzJiNjUiLCJpYXQiOjE1MTU3NjE2NzEsInJlc3BvbnNlVHlwZSI6ImNvZGUiLCJpbnRlbnRUeXBlIjoiYWNjb3VudCIsImNsaWVudElkIjoiNTZkZmM2ZTMtMzQ3Yi00ZWY1LTgzY2EtMDcxMDQxZWIwMDMxIiwicmVkaXJlY3RVcmwiOiJodHRwczovLzEyNy4wLjAuMS9yZWRpcmVjdDEiLCJjdXN0b21lcklwIjoiMTI3LjAuMC4xIiwiYnJhbmRJZCI6ImhzYmMiLCJpbnRlbnRJZCI6ImJhM2I0NzY2LTQyNzktNDhjZC05ZGYzLWIyYmQ1NGJhZmNkNiIsImNsYWltSWQiOiI4YjY5ZmM2Yjc2NGU3YTllNTk2YmI2OWMzMzI5NDYxNzIyM2JhMDE3NTAxNTIyN2E5N2M5YzEyZWUzM2JhNWMwIiwic3RhdGUiOiJzb21lLXN0YXRlLTEyMzQ1Njc4Iiwibm9uY2UiOiJuLTBTNl9XekEyTWoifQ.1nqXILi5L1HcMmppIavgd8S6VVhDNBeF-i0XrGwFxVaAs3NW8BuReMRFEbsPC0p56DnXQ3gvYA-BbJ-ahS0vRiMvrxa3VEtTOswJBtjpLBphfOkUvgIAthB2MFv7dVsZvBs9Kqfqis5MINPjafSXaFh9ZelZyu1G_zaQb6LvcxMce5b1fBtFFV3gLGCE9ScdeSMC08mZqPajeW7mP37wBSp_QMSmxeK89KrmZtIMJmte_FuTw-TQ4dwmP6L6nscRAAoTpEaDItxKAWXFyOQPPo2fxZ-79x-Rr12MkTJzoFJbquAwaGEApLgz0JUtp_L20orgrIh8jcY6e7cEt4qglg
        ```
        ---
        **Decoded**
         ```
          Header
          {
            "kid": "53d861c4-be30-4342-be4e-97dec49bfae2",
            "typ": "JWT",
            "alg": "RS256",
            "jku": ""https://private.api.open.banking.hsbc.com/.well-known/jwks.json"
          }
          Payload
          {
             "jti": "7b055f8a-5bbf-41f8-9600-911c58232b65",
             "iat": "1515761671",
             "scope": "openid aisp or pisp or cbpii or AIS:  32",
             "state": "some-state-12345678",
             "nonce": "n-0S6_WzA2Mj",
             "iss": "https://private.api.personal.hsbc.co.uk",
             "aud": "https://channelUI.com",
             "exp": "1 minute from set time",
             "brand": "PERSONAL",
             "country": "UK",
             "standard": "obie",
             "consentId": "ba3b4766-4279-48cd-9df3-b2bd54bafcd6",
             "consentType": "AIS or PIS or CBPII",
             "customerIp": "91.10.21.5",
             "tppId": "PL-TST-734519779079",
             "tppName" : "My Tpp"
          }
         ``