openapi: 3.1.0
info:
  version: '1.0'
  title: D1 Transit Notification Inbound API
servers:
  - url: 'https://THALES-PROD/d1/transit/notification/api/v1'
    description: Prod URL
  - url: 'https://THALES-STG/d1/transit/notification/api/v1'
    description: Staging URL
paths:
  '/issuers/{issuerId}/wallets/{walletIndicator}/events/{eventType}/handleEvent':
    post:
      summary: Handle Event
      description: |
        API used by Transit Issuer to trigger events:
        <li>notify transactions (purchase, rides...)
        <li>balance updates
        <li>count updates
        <li>fare products updates
        <li>update and retrieve bundle data
        <li>notify messages (alerts, promotions...)
      operationId: handleEvent
      parameters:
        - $ref: '#/components/parameters/eventType'
        - $ref: '#/components/parameters/issuerId'
        - $ref: '#/components/parameters/walletIndicator'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HandleEventReq'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleEventRes'
        '500':
          $ref: '#/components/responses/error500'
        '503':
          $ref: '#/components/responses/error503'
      servers:
        - url: 'https://THALES-PROD/d1/transit/notification/api/v1'
          description: Prod URL
        - url: 'https://THALES-STG/d1/transit/notification/api/v1'
          description: Staging URL
components:
  parameters:
    eventType:
      name: eventType
      in: path
      description: |-
        Indicates the type of event to be handled.<br/>Value can be:
        |Value|Description|
        |---|---|
        |transaction|Used to notify a transaction.|
        |message|Used to notify a message.| 
        |update_balance|Used to notify balance update.|            
        |update_count|Used to notify count update of a count based fare product.|
        |update_fare_products|Used to update fare products (e.g. purchase of a new product, removal or renewal).|
        |update_bundle_data|Used to notify that a digital card bundle shall be updated.|
        |retrieve_bundle_data|Used to notify that digital card bundle data shall be retrieved.|              
      required: true
      schema:
        type: string
    issuerId:
      name: issuerId
      in: path
      description: Issuer unique identifier. Assigned by Thales during onboarding.
      required: true
      schema:
        type: string
        maxLength: 10
    walletIndicator:
      name: walletIndicator
      in: path
      description: |-
        Indicates which digital wallet is involved in the use case.
        |Value|Description|
        |---|---|
        |1|Apple|
        |2|Google|
        |3|Samsung|        
      required: true
      schema:
        type: number
  responses:
    error500:
      description: |
        An unexpected error occurred while processing the request.<br/>
        The request cannot be retried.<br/>
        Only used in cases where it's not be possible to provide more information about what went wrong with the request (i.e. return <b>HTTP 200</b> with '<b>responseContext</b>').
    error503:
      description: |
        Indicates that the system is unavailable.<br/>
        The request can be retried.
  schemas:
    HandleEventReq:
      type: object
      properties:
        requestContext:
          $ref: '#/components/schemas/requestContext'
        digitalCardId:
          $ref: '#/components/schemas/digitalCardId'
        cardAccountId:
          $ref: '#/components/schemas/cardAccountId'
        eventTime:
          type: string
          description: The event time
          format: date-time
      required:
        - requestContext
        - cardAccountId
        - eventTime
    requestContext:
      type: object
      properties:
        requestId:
          type: string
          description: Request unique identifier. Should be different for every retry.
          maxLength: 64
          examples:
            - 493f7686-93a0-494a-a44f-867fcd10ce22
        correlationId:
          type: string
          description: |-
            Random identifier which can be used to correlate the different API calls done as part of a usecase.
            There is no strong guarantee of the uniqueness of this identifier, so it should not be used for purposes other than logging and troubleshooting.
          maxLength: 64
          examples:
            - bfd8450f-a605-4427-9714-1d620f14dda1
      required:
        - requestId
        - correlationId
    digitalCardId:
      type: string
      description: Digital card unique identifier
      maxLength: 64
      examples:
        - DGGLSW8D8AC610566D4EF09C22186B2A5ED756
    cardAccountId:
      type: string
      description: Card account unique identifier
      maxLength: 64
      examples:
        - FAPLSW8D8AC610566D4EF09C22186B2A5ED793
    HandleEventRes:
      type: object
      properties:
        responseContext:
          $ref: '#/components/schemas/responseContext'
      required:
        - responseContext
    responseContext:
      type: object
      description: |
        Should be used for most of responses, even if the request processing was not successful.
        If there was an issue encountered during request processing, the statusCode and statusMessage are used to give more details about what has gone wrong.
      properties:
        requestId:
          type: string
          description: requestId value from the corresponding request.
          maxLength: 64
          examples:
            - a762c0a1-2ae7-42b1-a4d8-8d8ba09bdf30
        statusCode:
          type: number
          examples:
            - 0
        statusMessage:
          type: string
          examples:
            - OK
      required:
        - requestId
        - statusCode
