openapi: 3.0.0
info:
  title: Swift JVIN Interbank Messaging API
  description: |
    API to support bank to bank messaging for India JV
  contact:
    name: Developer Hub
    url: https://developer.swift.com
    email: developer-support@swift.com
  license:
    name: API Restricted License
    url: https://developer.swift.com/api-license
  version: 1.2.0
servers:
- url: https://sandbox.swift.com/swift-interbank-messaging/v1
  description: Sandbox
- url: https://api-test.swiftnet.sipn.swift.com/swift-interbank-messaging/v1
  description: Pilot (MV-SIPN)
- url: https://api.swiftnet.sipn.swift.com/swift-interbank-messaging/v1
  description: Live (MV-SIPN)
security:
- bearerToken: []
tags:
- name: MT
  description: Concerns MT messaging as governed by ISO 15022.
paths:
  /fin-messages:
    post:
      tags:
      - MT
      operationId: sendMtMessage
      summary: Sends an MT message
      description: |-     
        Sends one MT message to one recipient. 

        The message to be sent should be base64 encoded and placed inside a JSON wrapper in the property *message_body*.
    
      parameters:
        - $ref: '#/components/parameters/X-Request-ID'
        - $ref: '#/components/parameters/X-BIC'
        - $ref: '#/components/parameters/Swift-Message-Type'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - message_body
              properties:
                message_type:
                  type: string
                  minLength: 1
                  maxLength: 35
                message_body: 
                  type: string
                  format: binary
            example:
              {
                "message_type": "fin.940",
                "message_body": "DQo6MjA6TE9XLTAwMDA4MjAyNzYxNw0KOjI4RDoxMjM0NS8xMjM0NQ0KOjUwTDp4DQo6NTBIOi94DQp4DQo6MzA6OTYxMTIzDQo6MjE6TE9XLTAwMDA4MjAyNzYxNw0KOjMyQjpVU0QxLDM0DQo6NTJBOkNIQVNVUzMzDQo6NTk6eA0KOjcxQTpTSEENCjoyMTpMT1ctMDAwMDgyMDI3NjE3DQo6MzJCOlVTRDEsMzQNCjo1MkE6Q0hBU1VTMzMNCjo1OTp4DQo6NzFBOlNIQQ=="
              }
                
      responses:
        "202":
          description: Accepted
          headers:
            Swift-Request-ID:
              $ref: '#/components/headers/Swift-Request-ID'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'              
        "400":
          description: Bad Request
          headers:
            Swift-Request-ID:
              $ref: '#/components/headers/Swift-Request-ID'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'               
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              examples:
                "400-SwAP510":
                  $ref: '#/components/examples/400-SwAP510'
                "400-SwAP509":
                  $ref: '#/components/examples/400-SwAP509'
                "400-SwAP504-txt":
                  $ref: '#/components/examples/400-SwAP504-txt'
                "400-SwAP504-bic":
                  $ref: '#/components/examples/400-SwAP504-bic'
                "400-SwAP504-svc":
                  $ref: '#/components/examples/400-SwAP504-svc'
                "400-SwAP522":
                  $ref: '#/components/examples/400-SwAP522'
                "400-SwAP504":
                  $ref: '#/components/examples/400-SwAP504'
                "400-SwAP505":
                  $ref: '#/components/examples/400-SwAP505'
                "400-SwAP501":
                  $ref: '#/components/examples/400-SwAP501'
        "401":
          $ref: '#/components/responses/401-Unauthorized'
        "403":
          $ref: '#/components/responses/403-Forbidden'
        "404":
          $ref: '#/components/responses/404-NotFound'
        "429":
          $ref: '#/components/responses/429-TooManyRequests'
        "500":
          $ref: '#/components/responses/500-InternalServerError'
        "503":
          $ref: '#/components/responses/503-ServiceUnavailable'
        "504":
          $ref: '#/components/responses/504-GatewayTimeout'
        default:
          $ref: '#/components/responses/500-InternalServerError'
components:
  
  parameters:

    X-Request-ID:
      name: X-Request-ID
      in: header
      description: 'End to end tracking ID. This value will be returned to the caller as a response header of the same name. If no header is assigned by the caller, then one will be assigned by Swift.'
      required: false
      schema:
        type: string
        maxLength: 270
      example: rrt-1130311210763048898-c-geu2-21394-2055157-17
    X-BIC:
      name: X-BIC
      in: header
      description: The BIC code of the downstream provider which should recieve and process this request, in situations where there are multiple downstream providers. If Swift API Platform should recieve and process this request, the value of this header should be set to SWHQBEBB. 
      required: false
      schema:
        type: string 
        pattern: ^[a-zA-Z]{6,6}[a-zA-Z2-9][a-nA-Np-zP-Z0-9]$
        maxLength: 255
      example: DEUTDEFZ
    
    Swift-Message-Type:
      name: Swift-Message-Type
      in: header
      description: Describes the type of message being sent.
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 35
      example: fin.940

  schemas:

    ErrorMessage:
      required:
      - code
      - severity
      - text
      type: object
      properties:
        severity:
          type: string
          description: "The category of error.\n  * Fatal means the failure is permanent and the request should not be retried.\n  * Transient means the failure is temporary and the request can be retried after a suitable interval.\n  * Logic is a legacy code and should not be used. \n"
          enum:
          - Fatal
          - Transient
          - Logic
        code:
          maxLength: 50
          type: string
          description: A unique string which should identify the error and the system or service where it originated.
        text:
          maxLength: 1000
          type: string
          description: free-text field which should describe the problem and any recovery or remediation steps which can be taken.
        user_message:
          maxLength: 100
          type: string
          description: A message to display to an active user if there is one.
        more_info:
          type: string
          description: "A URL pointing to a resource which contains further information about the error, if one exists."
          format: uri
      additionalProperties: false
  responses:
    "401-Unauthorized":
      description: |-
        Covers the following scenarios:
        * SwAP502 - Invalid Signing Certificate. The certificate cannot be used for doing the API transaction.
        * SwAP502 - Invalid OAuth access token.
        * SwAP508 - OAuth access token not provided.
        * SwAP509 - Customer number not defined.
      headers:
        Swift-Request-ID:
          $ref: '#/components/headers/Swift-Request-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'          
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            "401-SwAP502-cert":
              $ref: '#/components/examples/401-SwAP502-cert'
            "401-SwAP502-token":
              $ref: '#/components/examples/401-SwAP502-token'
            "401-SwAP508":
              $ref: '#/components/examples/401-SwAP508'
            "401-SwAP509":
              $ref: '#/components/examples/401-SwAP509'
    "403-Forbidden":
      description: "Covers the following scenarios:\n- SwAP503 - OAuth access token has insufficient scope for the requested service. "
      headers:
        Swift-Request-ID:
          $ref: '#/components/headers/Swift-Request-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'           
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            "403-SwAP503":
              $ref: '#/components/examples/403-SwAP503'
    "404-NotFound":
      description: |-
        Covers the following scenarios:
        - SwAP506 - Resource does not exist.
      headers:
        Swift-Request-ID:
          $ref: '#/components/headers/Swift-Request-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'  
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            "404-SwAP506":
              $ref: '#/components/examples/404-SwAP506'
    "429-TooManyRequests":
      description: |-
        Covers the following scenarios:
        - SwAP507 - Request cannot be processed at this time. Please try again..
      headers:
        Swift-Request-ID:
          $ref: '#/components/headers/Swift-Request-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'  
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            "429-SwAP507":
              $ref: '#/components/examples/429-SwAP507'
    "503-ServiceUnavailable":
      description: |-
        Covers the following scenarios:
        - SwAP590 - Service is temporarily unavailable.
      headers:
        Swift-Request-ID:
          $ref: '#/components/headers/Swift-Request-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'  
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            "503-SwAP590":
              $ref: '#/components/examples/503-SwAP590'
    "504-GatewayTimeout":
      description: |-
        Covers the following scenarios:
        - SwAP591 - Service Provider time out.
      headers:
        Swift-Request-ID:
          $ref: '#/components/headers/Swift-Request-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'  
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            "504-SwAP591":
              $ref: '#/components/examples/504-SwAP591'
    "500-InternalServerError":
      description: Internal Server Error
      headers:
        Swift-Request-ID:
          $ref: '#/components/headers/Swift-Request-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'  
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            "500-InternalServerError":
              $ref: '#/components/examples/500-InternalServerError'

  examples:
    "400-SwAP510":
      summary: "SwAP510: The API method does not support non-repudiation."
      value:
        severity: Fatal
        code: SwAP510
        text: The API method does not support non-repudiation.
    "400-SwAP509":
      summary: "SwAP509: Missing mandatory signature on the non-repudiation API transaction."
      value:
        severity: Fatal
        code: SwAP509
        text: Missing mandatory signature on the non-repudiation API transaction.
    "400-SwAP504-txt":
      summary: "SwAP504: Text is custom to the schema error"
      value:
        severity: Fatal
        code: SwAP504
        text: Text is custom to the schema error
    "400-SwAP504-bic":
      summary: "SwAP504: Invalid Bic."
      value:
        severity: Fatal
        code: SwAP504
        text: Invalid Bic.
    "400-SwAP504-svc":
      summary: "SwAP504: Invalid Service."
      value:
        severity: Fatal
        code: SwAP504
        text: Invalid Service.
    "400-SwAP522":
      summary: "SwAP522: The request cannot processed. The x-bic value provided is not valid."
      value:
        severity: Fatal
        code: SwAP522
        text: The request cannot processed. The x-bic value provided is not valid.
    "400-SwAP504":
      summary: "SwAP504: JSON request body does not conform to policy."
      value:
        severity: Fatal
        code: SwAP504
        text: JSON request body does not conform to policy.
    "400-SwAP505":
      summary: "SwAP505: XML request body does not conform to policy."
      value:
        severity: Fatal
        code: SwAP505
        text: XML request body does not conform to policy.
    "400-SwAP501":
      summary: "SwAP501: API request is malformed."
      value:
        severity: Fatal
        code: SwAP501
        text: API request is malformed.
    "401-SwAP502-cert":
      summary: "SwAP502: Invalid Signing Certificate. The certificate cannot be used for doing the API transaction."
      value:
        severity: Fatal
        code: SwAP502
        text: Invalid Signing Certificate. The certificate cannot be used for doing the API transaction.
    "401-SwAP502-token":
      summary: "SwAP502: Invalid OAuth access token."
      value:
        severity: Fatal
        code: SwAP502
        text: Invalid OAuth access token.
    "401-SwAP508":
      summary: "SwAP508: OAuth access token not provided."
      value:
        severity: Fatal
        code: SwAP508
        text: OAuth access token not provided.
    "401-SwAP509":
      summary: "SwAP509: Customer number not defined."
      value:
        severity: Fatal
        code: SwAP509
        text: Customer number not defined.
    "403-SwAP503":
      summary: "SwAP503: OAuth access token has insufficient scope for the requested service. "
      value:
        severity: Fatal
        code: SwAP503
        text: OAuth access token has insufficient scope for the requested service.
    "404-SwAP506":
      summary: "SwAP506: Resource does not exist."
      value:
        severity: Fatal
        code: SwAP506
        text: Resource does not exist.
    "429-SwAP507":
      summary: "SwAP507: Request cannot be processed at this time. Please try again.."
      value:
        severity: Transient
        code: SwAP507
        text: Request cannot be processed at this time. Please try again..
    "503-SwAP590":
      summary: "SwAP590: Service is temporarily unavailable."
      value:
        severity: Transient
        code: SwAP590
        text: Service is temporarily unavailable.
    "504-SwAP591":
      summary: "SwAP591: Service Provider time out."
      value:
        severity: Transient
        code: SwAP591
        text: Service Provider time out.
    "500-InternalServerError":
      summary: Internal Server Error
      value:
        severity: Transient
        code: IJV-IBM-500
        text: Server encountered an unexpected condition and cannot fulfill the request.
  headers:
    X-Request-ID:
      description: Specify an unique end to end tracking request ID. The element will be populated by the SWIFT API gateway
      schema:
        type: string
        maxLength: 270
      required: true    
    Swift-Request-ID:
      required: false
      schema:
        type: string
        format: uuid
      examples:
        SwiftIdResponseHeader:
          value: ce480d68-2612-4aef-867a-e91566a1e012
      description: |-
        A Universally Unique Identifier (UUID) generated by the API Gateway for tracking and support purposes.
        This Swift-Request-ID response header must always be returned to the API consumer, even when the response is an error message
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: opaque OAuth 2.0