Payments Canada application level heartbeat API

openapi: 3.2.0
info:
  title: Inbound Exchange Heartbeat application level heartbeat API
  description: Payments Related Endpoints for RTR Exchange, including Credit Transfer, and associated Enquiries.
  version: 1.1.0
servers:
- url: https://api.payments.ca/rtr-sandbox
  description: Sandbox Environment
tags:
- name: application level heartbeat
paths:
  /inbound-heartbeat:
    parameters:
    - $ref: '#/components/parameters/TraceabilityId'
    - $ref: '#/components/parameters/Signature'
    - $ref: '#/components/parameters/RequestId'
    post:
      summary: Receive Heartbeat Request
      description: This service is used to receive heartbeat requests from participating systems (e.g. Exchange) using ISO 20022 admi.004 message format.
      tags:
      - application level heartbeat
      security:
      - oAuth:
        - client_credentials
      requestBody:
        content:
          application/vnd.api.v1+json:
            schema:
              $ref: '#/components/schemas/ReceiveHeartbeat'
      responses:
        '400':
          $ref: '#/components/responses/400-bad-request'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '403':
          $ref: '#/components/responses/403-forbidden'
        '404':
          $ref: '#/components/responses/404-not-found'
        '429':
          $ref: '#/components/responses/429-too-many-requests'
        '500':
          $ref: '#/components/responses/500-internal-server-error'
        '503':
          $ref: '#/components/responses/503-service-unavailable'
        '200':
          description: Heartbeat Response Sent by Exchange
          headers:
            x-jws-signature:
              $ref: '#/components/headers/x-jws-signature'
            traceability-id:
              $ref: '#/components/parameters/TraceabilityId'
          content:
            application/vnd.api.v1+json:
              schema:
                $ref: '#/components/schemas/AdmiResponse'
      operationId: postInboundHeartbeat
      x-operation-id-source: derived
components:
  responses:
    404-not-found:
      description: Resources Not Found
    403-forbidden:
      description: Forbidden
      content:
        application/vnd.api.v1+json:
          schema:
            $ref: types.yaml#/ErrorModel
    500-internal-server-error:
      description: Internal Server Error
      headers:
        traceability-id:
          $ref: '#/components/parameters/TraceabilityId'
      content:
        application/vnd.api.v1+json:
          schema:
            $ref: types.yaml#/ErrorModel
    401-unauthorized:
      description: Unauthorized
      headers:
        traceability-id:
          $ref: '#/components/parameters/TraceabilityId'
    400-bad-request:
      description: Bad Request - Validation Errors
      headers:
        traceability-id:
          $ref: '#/components/parameters/TraceabilityId'
      content:
        application/vnd.api.v1+json:
          schema:
            $ref: types.yaml#/ErrorModel
    503-service-unavailable:
      description: Service Unavailable - The server cannot handle the request for a service due to temporary maintenance.
    429-too-many-requests:
      description: Too many requests; blocked due to rate limiting.
  parameters:
    Signature:
      in: header
      name: x-jws-signature
      description: The JWS signature of request payload.
      schema:
        type: string
        minLength: 1
      required: true
      example: eyJjcml0IjpbImlhdCJdLCJpYXQiOjE2MzcyNzIxMzUyNTIsImFsZyI6IlJTMjU2Iiwia2lkIjoic2lnbi1rZXktY2EwMDAwMDEtMDAxIn0.V7skMzl3rUZK7N5pYVlicNt3TWXNBZyX-rtNV7n5rOc.hBDcIL9ptXWfOsg2pRSTy5dzFsowqjvE0G8dglODTSFpRM-iL1khjomuaYx_LnZV_lTnwkfMHknLdJuG5ucM7gpTZ98a1egjTcQisWHRO0fCr-sxqZXusGIB-hgAnB16Fn9UtdNdzsl447C0c3sSmytYn6eeMu5c6RWVrq-xB5KD9_JGexpyTw3IBvXavpd7h7QgnNzmcdWjV0yVXh74x4gmD8hTSbRkv54MYzap2BSFXLgxCwOrS7Jw0tQzCcP8a7gcOunO9Zr3ArgH-4Ur0VRWxIH4GaDksCBKdx1JdXFUToqG5Ben-FNyAzxkVxtuuwYMCbT1I3-8mCoj7nTtYw
    TraceabilityId:
      description: A unique identifier per RTR Exchange API call for purpose of tracing a request through all systems. For example, traceability-id must be UUID. All the messages sent to other systems will have the same traceability-id as the message that originated them.
      in: header
      name: traceability-id
      schema:
        type: string
        format: uuid
      required: true
      example: e23d32eb-c7f2-4836-a314-557efe95a525
    RequestId:
      in: header
      name: x-uetr
      description: "This is the UETR, a unique ID generated for each Credit Transfer (pacs.008) used for message tracking purposes. This header is required for the following ISO specs:\n  - pacs.008\n  - pacs.004 (post-R1 scope)\n  - pacs.028\n  - camt.029 (post-R1 scope)\n  - camt.056 (post-R1 scope)\n  - camt.006\nNote that this header may be required in new ISO messages that are not listed above in future releases, the list will be updated per release."
      schema:
        type: string
        minLength: 1
        maxLength: 36
      required: false
      example: eb6305c9-1f7f-49de-aed0-16487c27b42d
  schemas:
    HeartbeatResponse:
      description: admi.011 message wrapper
      type: object
      required:
      - system_event_acknowledgement
      properties:
        system_event_acknowledgement:
          $ref: SystemEventAcknowledgementV01.yaml#/definitions/system_event_acknowledgement
    IsoHeader:
      type: object
      required:
      - business_application_header
      properties:
        business_application_header:
          $ref: BusinessApplicationHeaderV02.yaml#/definitions/business_application_header
    ReceiveHeartbeat:
      description: admi.004 message wrapper
      allOf:
      - $ref: '#/components/schemas/IsoHeader'
      - type: object
        required:
        - system_event_notification
        properties:
          system_event_notification:
            $ref: SystemEventNotificationV02.yaml#/definitions/system_event_notification
    SyntaxError:
      description: admi.002 message wrapper for syntax errors in API request payload.
      type: object
      required:
      - message_reject
      properties:
        message_reject:
          $ref: MessageRejectV01.yaml#/definitions/message_reject
    AdmiResponse:
      allOf:
      - $ref: '#/components/schemas/IsoHeader'
      - oneOf:
        - $ref: '#/components/schemas/SyntaxError'
        - $ref: '#/components/schemas/HeartbeatResponse'
  headers:
    x-jws-signature:
      description: The JWS signature of response payload.
      schema:
        type: string
        minLength: 1
      required: true
      example: eyJjcml0IjpbImlhdCJdLCJpYXQiOjE2MzcyNzIxMzUyNTIsImFsZyI6IlJTMjU2Iiwia2lkIjoic2lnbi1rZXktY2EwMDAwMDEtMDAxIn0.V7skMzl3rUZK7N5pYVlicNt3TWXNBZyX-rtNV7n5rOc.hBDcIL9ptXWfOsg2pRSTy5dzFsowqjvE0G8dglODTSFpRM-iL1khjomuaYx_LnZV_lTnwkfMHknLdJuG5ucM7gpTZ98a1egjTcQisWHRO0fCr-sxqZXusGIB-hgAnB16Fn9UtdNdzsl447C0c3sSmytYn6eeMu5c6RWVrq-xB5KD9_JGexpyTw3IBvXavpd7h7QgnNzmcdWjV0yVXh74x4gmD8hTSbRkv54MYzap2BSFXLgxCwOrS7Jw0tQzCcP8a7gcOunO9Zr3ArgH-4Ur0VRWxIH4GaDksCBKdx1JdXFUToqG5Ben-FNyAzxkVxtuuwYMCbT1I3-8mCoj7nTtYw
  securitySchemes:
    oAuth:
      type: oauth2
      description: This API uses OAuth 2 with the implicit grant flow. (The access token expires in 5 minutes)
      flows:
        clientCredentials:
          tokenUrl: https://api.payments.ca/accesstoken
          scopes:
            client_credentials: Required to get credentials for the API call