---
# Generated-By: OA3 Linker Tool
# Input-File: R1-Inbound/R1-Inbound-Participant-PaymentAPI.yml
# Options: --encoding=utf-8; --log-level=DEBUG; --oa3fix; --overwrite
# -----
openapi: 3.0.3
info:
  title: Inbound Participant Payment API
  description: |
    Payments Related Endpoints for RTR Exchange, including Credit Transfer, and associated Enquiries.

    # Pre-requisites:
    1. Create an app with the `rtr-sandbox-product` on the [Developer Portal](https://developer.payments.ca/)
    2. Mark down the `Consumer Key` and `Consumer Secret`

    # Calling this API on this page
    1. Click the Authorize button.
    2. Fill in the username with your Consumer Key and fill in the password with your Consumer Secret.
    3. Click Authorize.
    4. Expand the appropraite API and click "Try it out".
    5. Fill in the appropriate details in the body.
    6. Click "Execute"
    7. The server response will be found under the curl call.
  version: 1.1.0
servers:
  - url: "https://api.payments.ca/rtr-sandbox" #Review
    description: Sandbox Environment #Review

paths:
  /payments: #pacs.008 - pacs.002
    parameters:
      - $ref: "#/components/parameters/TraceabilityId"
      - $ref: "#/components/parameters/Signature"
      - $ref: "#/components/parameters/RequestId"
    post:
      summary: Send Single Credit Transfer
      description:
        This service can be used by a RTR Sending Participant to send a new RTR Payment
        to RTR Exchange using ISO 20022 pacs.008 message format.
      tags:
        - single credit transfer
      security:
        - oAuth:
            - client_credentials
      requestBody:
        content:
          application/vnd.api.v1+json:
            schema:
              $ref: "#/components/schemas/SendPayment"
      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: Payment Status Report
          headers:
            x-jws-signature:
              $ref: "#/components/headers/x-jws-signature"
          content:
            application/vnd.api.v1+json:
              schema:
                $ref: "#/components/schemas/PacsResponse"

  /payments/status: #pacs.028 - pacs.002
    parameters:
      - $ref: "#/components/parameters/TraceabilityId"
      - $ref: "#/components/parameters/Signature"
      - $ref: "#/components/parameters/RequestId"
    post:
      summary: Send Payment Status Report Enquiry
      description:
        This service can be used by a RTR Sending Participant or RTR Receiving Participant to
        send a Payment Status Report Enquiry using ISO 20022 pacs.028 message format
      tags:
        - single credit transfer status enquiry
      security:
        - oAuth:
            - client_credentials
      requestBody:
        content:
          application/vnd.api.v1+json:
            schema:
              $ref: "#/components/schemas/SendStatusEnquiry"
      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: Payment Status Report
          headers:
            x-jws-signature:
              $ref: "#/components/headers/x-jws-signature"
          content:
            application/vnd.api.v1+json:
              schema:
                $ref: "#/components/schemas/PacsResponse"

#Components Section
components:
  securitySchemes:
    oAuth:
      type: oauth2
      description: This API uses OAuth 2 with the implicit grant flow. (The access token expires in 5 minutes)
      flows:
        clientCredentials: # <---- OAuth flow(authorizationCode, implicit, password or clientCredentials)
          tokenUrl: https://api.payments.ca/accesstoken
          scopes:
            client_credentials: Required to get credentials for the API call
  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
  parameters:
    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:
          - pacs.008
          - pacs.004 (post-R1 scope)
          - pacs.028
          - camt.029 (post-R1 scope)
          - camt.056 (post-R1 scope)
          - camt.006
        Note 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
    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
  responses:
    400-bad-request:
      description: Bad Request - Validation Errors
      content:
        application/vnd.api.v1+json:
          schema:
            $ref: "types.yaml#/ErrorModel"
    401-unauthorized:
      description: Unauthorized
    403-forbidden:
      description: Forbidden
      content:
        application/vnd.api.v1+json:
          schema:
            $ref: "types.yaml#/ErrorModel"
    404-not-found:
      description: Resources Not Found
    429-too-many-requests:
      description: Too many requests; blocked due to rate limiting.
    500-internal-server-error:
      description: Internal Server Error
      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.

  schemas:
    IsoHeader:
      type: object
      required:
        - business_application_header
      properties:
        business_application_header:
          $ref: "BusinessApplicationHeaderV02.yaml#/definitions/business_application_header"

    PacsResponse:
      allOf:
        - $ref: "#/components/schemas/IsoHeader"
        - oneOf:
            - $ref: "#/components/schemas/SyntaxError"
            - $ref: "#/components/schemas/PaymentStatusReport"
    PaymentStatusReport: #pacs.002
      description: >
        pacs.002 message wrapper - There are 2 possible scenarios of pacs.002 response:  1.
        Validation or Business Error - Transaction Status is RJCT,  2. Successful
        response - Transaction Status is not RJCT
      type: object
      required:
        - fi_to_fi_payment_status_report
      properties:
        fi_to_fi_payment_status_report:
          $ref: "FIToFIPaymentStatusReportV10.yaml#/definitions/fi_to_fi_payment_status_report"

    SendPayment: #pacs.008
      description: pacs.008 message wrapper
      allOf:
        - $ref: "#/components/schemas/IsoHeader"
        - type: object
          required:
            - fi_to_fi_customer_credit_transfer
          properties:
            fi_to_fi_customer_credit_transfer:
              $ref: "FIToFICustomerCreditTransferIncomingV08.yaml#/definitions/fi_to_fi_customer_credit_transfer"
    SendStatusEnquiry: #pacs.028
      description: pacs.028 message wrapper
      allOf:
        - $ref: "#/components/schemas/IsoHeader"
        - type: object
          required:
            - fi_to_fi_payment_status_request
          properties:
            fi_to_fi_payment_status_request:
              $ref: "FIToFIPaymentStatusRequestV03.yaml#/definitions/fi_to_fi_payment_status_request"

    SyntaxError: #admi.002
      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"