openapi: 3.0.0
info:
  title: Settlement Instructions PoC API
  description: >
      T2S Settlement Instruction API allows T2S Actors to perform queries on settlement instruction based on the actor’s roles and privileges.
      For example,
       - for T2S Actors all instructions that have been sent by either the T2S Actor or by other T2S Actors that have been authorised by the T2S Actor to do so;
       - for CSDs in T2S all instructions that refer to accounts legally attributed to the CSD, and all instructions that the CSD has sent (these might refer to Inter-CSD accounts in issuer CSDs in T2S);
       - for NCBs:
         - Where NCBs act as parties in a CSD, they can query instructions like any user in a CSD, and with the related rights.
         - Where NCBs act as a CSD, they can query instructions like any CSD.
  version: 1.0.0
tags:
  - name: Settlement Instruction Status
    description: >
      Settlement Instruction Status queries allow T2S Actors to get the current status of a single Settlement Instruction.
servers:
  - description: URL for PoC in the Swift Pilot environment.
    url: https://api-test.swiftnet.sipn.swift.com/ecb-settlementinstruction/v1

security:
  - oauthBearerToken: []

paths:
  /settlement-instruction/t2s-ref/{t2s-ref-id}/status:
    get:
      tags: 
        - Settlement Instruction Status
      description: >
        Get the current status of a settlement instruction, 
        identified by the instruction identification code assigned by T2S.
      summary: Get Settlement Instruction Status by T2S Reference
      operationId: getInxStatusByT2SRef
      parameters:
        - name: x-userContext
          in: header
          description: User context is in base64 format. It will include the institution BIC. Participants do not need to send this value. This will be populated at Network Level.
          required: false
          schema:
            type: string
            format: byte
          example: eyJhbGciOiJSUzI1NiIsImtpZCI6ImN1cmwgLXYgbGRhcDovL0RJUkwwMS5zd2lmdG5ldC5zaXBuLnN3aWZ0LmNvbTozODkvY249dHNzY2hhbm5lbCxvPXN3bGliZWIzLG89c3dpZnQ/dXNlckNlcnRpZmljYXRlIiwidHlwIjoiSldUIn0=
        - name: X-T2S-UserRef
          in: header
          description: Party or User as base64Url format
          required: true
          style: simple
          explode: false
          schema:
            type: string            
        - name: t2s-ref-id        
          in: path
          description: T2S Reference of the instruction, also known as Market Infrastructure Transaction Identification (MITI).
          required: true
          schema:
             type: string
             minLength: 1
             maxLength: 35  
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementInstructionStatusResponse'
        "404":
          description: Instruction Not Found
        "401":
          description: User Not Authorized
        default:
          description: Payload Error
  /settlement-instruction/actor-ref/{actor-ref-id}/party-bic/{party-bic-id}/status:
    get:
      description: >
        Get the current status of a settlement instruction, 
        identified by the combination of the T2S Actor Reference and the instructing party BIC.
      summary: Get Settlement Instruction Status by Actor Reference
      tags: 
        - Settlement Instruction Status
      operationId: getInxStatusByActorRefPartyBic
      parameters:
        - name: x-userContext
          in: header
          description: User context is in base64 format. It will include the institution BIC. Participants do not need to send this value. This will be populated at Network Level.
          required: false
          schema:
            type: string
            format: byte
          example: eyJhbGciOiJSUzI1NiIsImtpZCI6ImN1cmwgLXYgbGRhcDovL0RJUkwwMS5zd2lmdG5ldC5zaXBuLnN3aWZ0LmNvbTozODkvY249dHNzY2hhbm5lbCxvPXN3bGliZWIzLG89c3dpZnQ/dXNlckNlcnRpZmljYXRlIiwidHlwIjoiSldUIn0=
        - name: X-T2S-UserRef
          in: header
          description: Party or User as base64Url format
          required: true
          style: simple
          explode: false
          schema:
            type: string            
        - name: actor-ref-id
          in: path
          description: Actor Reference of the instruction, also known as Transaction Identification
          required: true
          schema:
             type: string
             minLength: 1
             maxLength: 35
        - name: party-bic-id
          in: path
          description: Instructing Party BIC
          required: true
          schema:
             type: string
             minLength: 1
             maxLength: 11
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementInstructionStatusResponse'
        "404":
          description: Instruction Not Found
        "401":
          description: User Not Authorized
        default:
          description: Payload Error
components:
  schemas:
    SettlementInstructionStatusResponse:
      type: object
      description: Settlement Instruction Status Return Info
      properties:
        inxT2SRef:
          type: string
          minLength: 1
          maxLength: 35
          description: Instruction T2S Reference
        inxActorRef:
          type: string    
          minLength: 1
          maxLength: 35
          description: Instruction Actor Reference
        secMoveType:
          type: string
          enum: ["DELI", "RECE"]
          description: |
            Securities Movement Type Code
            Shows if the movement on a securities account results from a deliver or a receive instruction from the possible values:
            - DELI: Deliver
            - RECE: Receive
        settledQty:
          type: integer
          description: Total quantity settled so far.
        settledAmt:
          type: object
          description: Total settlement amount settled so far.
          properties:
            amount:
              type: integer
            currency:
              type: string
              pattern: "[A-Z]{3,3}"
        matchingStatus:
          type: string
          enum: [ "MACH", "NMAT"]
          description: |
            Matching status of the instruction.
            - MACH: Matched
            - NMAT: Unmatched
        cancelStatus:
          type: string
          enum: ["CANC", "NCAN"]
          description: |
            Cancel Status.
            - CANC: Cancelled
            - NCAN: Not Cancelled
        csdValHoldStatus:
          type: boolean
          description: CSD validation hold status of the settlement instruction
        cosdHoldStatus:
          type: boolean
          description: CoSD hold status of the settlement instruction
        csdHoldStatus:
          type: boolean
          description: CSD hold status of the settlement instruction
        partyHoldStatus:
          type: boolean
          description: Party hold status of the settlement instruction
        settStatus:
          type: string
          enum: ["PSET", "SETT", "USET"]
          description: |
            Settlement Status.
            - PSET: Partially Settled
            - SETT: Settled
            - USET: Unsettled
        isoSettStatus:
          type: string
          enum: ["PEND", "PENF"]
          description: |
            ISO Setllement Status.
            - PEND: Pending
            - PENF: Failing

###########################
#  Security Definition    #
###########################
  securitySchemes:
    oauthBearerToken:
      type: http
      scheme: bearer
      bearerFormat: opaque OAuth 2.0
      description: |
        The access token obtained as a result of OAuth 2.0 flows. SWIFT supports two OAuth grant types for consumption depending on the environment where the API is exposed.

        * MV-SIPN - jwt-bearer grant type [RFC 7523](https://tools.ietf.org/html/rfc7523) with Signed JWT assertion
        * Internet - Password grant type with license credentials.

        This API uses JWT-Bearer grant type.

        Please visit [SWIFT OAuth Token API](https://developer.swift.com/swift-oauth-token-api) page for more information and examples on how to generate an OAuth token.

        In this declaration only the basic security element to transport the bearer token of an OAuth2 process is declared.