openapi: 3.0.2

info:
  title: RMA API
  description: |
    The Swift Relationship Management Application (RMA) provides the ability to record and enforce pre-agreed relationships to send or receive traffic between participants of a Swift service. RMA APIs are a component of the RMA service presenting customers another channel to access RMA data.

    `This specification supports following functionalities :`

    * Check the status of the relationship with a counterparty with regards to the ability of sending or receiving a particular message type.

    * View the message type details of an existing relationship with a counterparty as available in the RMA portal.


  version: 1.0.0
  contact:
    email: developer-support@swift.com
    name: Developer Hub
  license:
    name: API Restricted License
    url: https://developer.swift.com/api-license

servers:
  - description: URL for Sandbox Environment.
    url: https://sandbox.swift.com/swift-rma/v1
  - description: URL for Pilot.
    url: https://api-test.swiftnet.sipn.swift.com/swift-rma/v1
  - description: URL for Live.
    url: https://api.swiftnet.sipn.swift.com/swift-rma/v1


tags:
  - name: Authorization

security:
  - oauthBearerToken: []

paths:

  /authorizations/status:
    post:
      tags:
        - Authorization
      summary: Status of the relationship.
      description: >-
        This API provides the ability to check the status of the relationship with a counterparty with regards to the ability of sending or receiving a particular message type.


        Allows customers to ensure that they send messages only if they have an existing valid relationship and avoids receiving a NACK (negative acknowledgement) from the Swift network.

      operationId: checkAuthorisationStatus
      parameters:
        - $ref: '#/components/parameters/X-Request-ID'
      requestBody:
        content:
          application/json:
            schema:
                $ref: '#/components/schemas/AuthorizationStatusRequest'
            examples:
              Authorization-Status-Request:
                  $ref: '#/components/examples/AuthorizationStatus'
      responses:
        '200':
          description: OK
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/AuthorizationStatusResponse'
              examples:
                Example-Authorized:
                  $ref: '#/components/examples/AuthorizationStatus_AUTH'
                Example-Not-Authorized:
                  $ref: '#/components/examples/AuthorizationStatus_NOTAUTH'
        '400':
          $ref: '#/components/responses/400-BadRequest'
        '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'

  /authorizations/details:
    post:
      tags:
        - Authorization
      summary: Details for an existing relationship.
      description: >-
        Details of the existing relationship with a counterparty.


        Allows customers to view the message type details of an existing relationship with a counterparty as available in the RMA portal.
      operationId: AuthorizationDetails
      parameters:
        - $ref: '#/components/parameters/X-Request-ID'
      requestBody:
        content:
          application/json:
            schema:
                $ref: '#/components/schemas/AuthorizationDetailsRequest'
            examples:
              Authorization-Details-Request:
                $ref: '#/components/examples/AuthorizationDetails'

              Authorization-Details-Multi-Request:
                $ref: '#/components/examples/AuthorizationDetailsMultiRequest'
      responses:
        '200':
          description: OK
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthorizationDetailsResponse'
                maxItems: 50
              examples:
                Example-Single:
                  $ref: '#/components/examples/AuthorizationDetailsSingle'
                Example-Multi:
                  $ref: '#/components/examples/AuthorizationDetailsMulti'
        '400':
          $ref: '#/components/responses/400-BadRequest'
        '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:

  securitySchemes:
    oauthBearerToken:
      type: http
      scheme: bearer
      bearerFormat: Signed JWT

  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: 75
  headers:
    X-Request-ID:
      description: End to end tracking ID. This value identifies the callers request in the Swift API Platform.
      schema:
        type: string
        maxLength: 75
      example: nlartp03-2674166-324389-2
  schemas:
    AuthorizationStatusRequest:
      type: object
      additionalProperties: false
      properties:
        issuer_bic:
          #description: The BIC8 (or BIC0 for Pilot swift.fin service) which has granted the authorisation.'
          $ref: '#/components/schemas/BICIdentifier'
        correspondent_bic:
          #description: The BIC8 (or BIC0 for Pilot swift.fin service) that has received the authorisation.
          $ref: '#/components/schemas/BICIdentifier'
        service_name:
          type: string
          description: Swiftnet service name that processes business messages exchanged between customers for which the authorisation applies.
        request_type:
          type: string
          description: Requested message type like pacs.008,101, etc. This parameter should have only a single message type as its value.
      required:
      - issuer_bic
      - correspondent_bic
      - service_name
      - request_type

    AuthorizationDetailsRequest:
      type: object
      additionalProperties: false
      properties:
        issuer_bic:
          #description: The BIC8 (or BIC0 for Pilot swift.fin service) which has granted the authorisation.'
          $ref: '#/components/schemas/BICIdentifier'
        correspondent_bic:
          #description: The BIC8 (or BIC0 for Pilot swift.fin service) that has received the authorisation.
          $ref: '#/components/schemas/BICIdentifier'
        service_name:
          type: string
          description: Swiftnet service name that processes business messages exchanged between customers for which the authorisation applies.
            The service name should be the name of the service that is in scope of RMA service. To know the services that are in scope of RMA, please refer to this link, https://www2.swift.com/knowledgecentre/publications/rma_serv_rma_ptl_get_st/38.0?topic=ref_2675476099.htm.

            If the value is provided as swift.finplus, then the API response will be applicable only for swift.finplus service. If you want the authorisation details for all services then you provide the value 'All' for the service_name parameter. Default value is 'All', if this parameter is not provided in the API call.
      required:
      - issuer_bic
      - correspondent_bic

    AuthorizationStatusResponse:
      description: |
        Current status of an authorization.
      type: object
      additionalProperties: false
      properties:
        authorization_status:
          type: string
          description: |
            AUTHORIZED: Indicates that valid RMA authorisation record exists in RMA data store. In the Pilot environment RMA is not mandated, meaning if the RMA record doesn't exist then messaging traffic can flow (this is similar to the situation where a valid RMA authorisation exists).

            NOT-AUTHORIZED : Indicates there is no valid RMA authorisation record in RMA data store. Refer reasons for NOT-AUTHORIZED status.
          enum:
          - AUTHORIZED
          - NOT-AUTHORIZED
        reason:
          type: string
          description: |
            Reason for NOT-AUTHORIZED status

            REVOKED – Indicates that the issuer BIC has revoked the previously granted authorization with the correspondent BIC.

            REJECTED – Indicates that the correspondent BIC has rejected the authorization.

            EXPIRED - Indicated that the previously granted authorisation has expired.

            NON-EXISTENT - This value is applicable only for Live environment.
          enum:
          - REVOKED
          - REJECTED
          - EXPIRED
          - NON-EXISTENT

    AuthorizationDetailsResponse:
      type: object
      additionalProperties: false
      properties:
        service_name:
          type: string
          description: Swiftnet service name that processes business messages exchanged between customers.
        authorization_status:
          type: string
          description: |
            Current status of an authorization

            Status 'NOT-AUTHORIZED' indicates Authorisation does not exist.
            Response payload will not include following parameters:
              - service_name
              - allowed_mesg_types
              - activated_mesg_types
              - issued_date
              - activated_date
              - validity_period_from_date
              - validity_period_to_date
          enum:
          - AUTHORIZED
          - REVOKED
          - REJECTED
          - NOT-AUTHORIZED
        allowed_mesg_types:
          type: string
          description: |
            list of message types that were included by the issuer of the authorisation like pacs.008, pacs.004, etc for swift.finplus or 101, 103, etc for swift.fin

            When wildcards are used such as 1** or pacs, this means that all category 1 messages are included and all pacs messages are included, respectively. Exclusions are represented with “-“. For example, if you see 1**, -101 this means that all category 1 messages are included except 101 message or if you see -1** or -pacs.008 this means that all category 1 messages are excluded and pacs.008 message is excluded, respectively. If you see the response as ALL, this means all messages are supported for that service.
        activated_mesg_types:
          type: string
          description: |
            list of message types that were activated by the correspondent who received the authorisation like pacs.008, pacs.004, etc for swift.finplus or 101, 103, etc for swift.fin

            When wildcards are used such as 1** or pacs, this means that all category 1 messages are included and all pacs messages are included, respectively. Exclusions are represented with “-“. For example, if you see 1**, -101 this means that all category 1 messages are included except 101 message or if you see -1** or -pacs.008 this means that all category 1 messages are excluded and pacs.008 message is excluded, respectively. If you see the response as ALL, this means all messages are supported for that service.
        issued_date:
          type: string
          description: date of authorisation issued
          format: string
          pattern: ^(0?[1-9]|[12][0-9]|3[01])[\/\-](0?[1-9]|1[012])[\/\-]\d{4}$
          example: 21/07/2023
        activated_date:
          description: date when the authorisation was activated
          type: string
          pattern: ^(0?[1-9]|[12][0-9]|3[01])[\/\-](0?[1-9]|1[012])[\/\-]\d{4}$
          example: 21/07/2024
        validity_period_from_date:
          description: Authorisation validity period, beginning date. If absent, this value is not set currently.
          type: string
          pattern: ^(0?[1-9]|[12][0-9]|3[01])[\/\-](0?[1-9]|1[012])[\/\-]\d{4}$
          example: 21/08/2024
        validity_period_to_date:
          description: Authorisation validity period, end date. If absent, this value is not set currently.
          type: string
          pattern: ^(0?[1-9]|[12][0-9]|3[01])[\/\-](0?[1-9]|1[012])[\/\-]\d{4}$
          example: 21/09/2025
    BICIdentifier:
      type: string
      description: 'Code allocated to a financial or non-financial institution by the ISO 9362 Registration Authority, as described in ISO 9362: 2014 - "Banking - Banking telecommunication messages - Business identifier code (BIC)".'
      pattern: ^[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}$

    ErrorMessage:
      type: object
      additionalProperties: false
      properties:
        severity:
          description: Specifies the severity of the error.
          type: string
          enum:
            - Fatal
            - Transient
            - Logic
        code:
          description: |
            A unique string which should identify the error and the system or service where it originated.
            * SwAPxxx codes are from Swift API gateway Platform.
            * Sw.RMA.xxx codes are from RMA Service Provider.

          type: string
          maxLength: 50
        text:
          description: free-text field which should describe the problem and any recovery or remediation steps which can be taken.
          type: string
          maxLength: 1000

      required:
        - severity
        - code
        - text

  responses:

    400-BadRequest:
      description: >-
        RMA Provider Errors
        * Sw.RMA.BadRequest - Invalid Data

        All error codes starting with SwAP5xx are API Gateway Errors.
        Covers the following API Platform error scenarios:
        * SwAP501 - API request is malformed.
        * SwAP504 - JSON request body does not conform to policy.
        * SwAP509 - Missing mandatory signature on the non-repudiation API transaction.
        * SwAP510 - The API method does not support non-repudiation.
        * SwAP521 - The request cannot be processed. The mandatory header(s) are not included.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            400-SwRMA:
              $ref: '#/components/examples/400-SwRMA'
            400-SwAP501:
              $ref: '#/components/examples/400-SwAP501'
            400-SwAP504:
              $ref: '#/components/examples/400-SwAP504'
            400-SwAP509:
              $ref: '#/components/examples/400-SwAP509'
            400-SwAP510:
              $ref: '#/components/examples/400-SwAP510'
            400-SwAP521:
              $ref: '#/components/examples/400-SwAP521'
    401-Unauthorized:
      description: >-
        Covers the following API Platform error scenarios:

        * SwAP502 - Invalid OAuth access token.

        * SwAP508 - OAuth access token not provided.

        * SwAP509 - Missing mandatory signature on the non-repudiation API transaction.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            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: >-
        RMA Provider Errors
        * Sw.RMA.Forbidden - Forbidden
        Covers the following API Platform error scenarios:

        - SwAP503 - OAuth access token has insufficient scope for the requested service.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            403-SwRMA:
              $ref: '#/components/examples/403-SwRMA'
            403-SwAP503:
              $ref: '#/components/examples/403-SwAP503'
    404-NotFound:
      description: >-
        Covers the following API Platform error scenarios:

        - SwAP506 - Resource does not exist.
      headers:
        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'
    405-MethodNotAllowed:
      description: 'Method Not Allowed'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    406-NotAcceptable:
      description: Not Acceptable
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            406-Encoding:
              $ref: '#/components/examples/406-Encoding'
            406-Language:
              $ref: '#/components/examples/406-Language'
    415-UnsupportedMediaType:
      description: Unsupported Media Type
      headers:
        X-Request-ID:
          description: End to end tracking ID. This value identifies the callers request in the Swift API Platform.
          schema:
            type: string
            maxLength: 75
          example: nlartp03-2674166-324389-2
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            415-UnsupportedMediaType:
              $ref: '#/components/examples/415-UnsupportedMediaType'
    429-TooManyRequests:
      description: >-
        Covers the following API Platform error scenarios:

        - SwAP507 - Request cannot be processed at this time. Please try again..
      headers:
        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: >-
        RMA Provider Errors
        * Sw.RMA.InternalError - InternalError

        Covers the following API Platform error scenarios:
        * SwAP590 - Service is temporarily unavailable.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            503-SwRMA:
              $ref: '#/components/examples/503-SwRMA'
            503-SwAP590:
              $ref: '#/components/examples/503-SwAP590'

    504-GatewayTimeout:
      description: >-
        Covers the following scenarios:

        - SwAP591 - Service Provider time out.
      headers:
        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'

    # Default error response #
    500-InternalServerError:
      description: 'Internal Server Error'
      headers:
        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-SwRMA:
      summary: >-
         Request body has invalid data.
      value:
        severity: Fatal
        code: Sw.RMA.BadRequest
        text: Request body has invalid data.
    400-SwAP501:
      summary: >-
        SwAP501: API request is malformed.
      value:
        severity: Fatal
        code: SwAP501
        text: API request is malformed.
    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-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-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-SwAP521:
      summary: >-
        SwAP521: The request cannot be processed. The mandatory header(s) are not included.
      value:
        severity: Fatal
        code: SwAP521
        text: The request cannot be processed. The mandatory header(s)  <missing_headers> are not included.

    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: Missing mandatory signature on the non-repudiation API transaction.
      value:
        severity: Fatal
        code: SwAP509
        text: Customer number not defined.
    403-SwRMA:
      summary: >-
         DN does not have scope over the issuer BIC or correspondent BIC
      value:
        severity: Fatal
        code: Sw.RMA.Forbidden
        text: DN does not have scope over the issuer BIC or correspondent BIC.
    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.
    406-Encoding:
      summary: Unsupported encoding
      value:
        severity: Fatal
        code: <error code>
        text: Encoding must be UTF-8. Other encodings are not supported.
    406-Language:
      summary: Unsupported language
      value:
        severity: Fatal
        code: <error code>
        text: Language <language> is not supported.
    415-UnsupportedMediaType:
      summary: Unsupported Media Type
      value:
        severity: Fatal
        code: <error code>
        text: Media type <media-type> is not supported.
    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-SwRMA:
      summary: >-
         DRMA service internal error.
      value:
        severity: Transient
        code: Sw.RMA.InternalError
        text: RMA service internal error.
    503-SwAP590:
      summary: >-
        SwAP590: Service is temporarily unavailable.
      value:
        severity: Transient
        code: SwAP590
        text: Service is temporarily unavailable.
    503-SwAP599:
      summary: >-
        SwAP599: Service is temporarily unavailable.
      value:
        severity: Transient
        code: SwAP599
        text: Service is temporarily unavailable.
    504-SwAP591:
      summary: >-
        SwAP591: Service Provider time out.
      value:
        severity: Transient
        code: SwAP591
        text: Service Provider time out.
    # Default error response.
    500-InternalServerError:
      summary: Internal Server Error
      value:
        severity: Transient
        code: <error code here>
        text: Server encountered an unexpected condition and cannot fulfill the request.

###########################
#       Examples          #
###########################
    # POST Authorization Status
    AuthorizationStatus:
      summary: Authorization Status Check Request
      value:
          issuer_bic: BANKUSA1
          correspondent_bic: BANKUSA2
          service_name: swift.fin
          request_type: '101'
    AuthorizationStatus_AUTH:
      summary: Example-Authorized
      value:
          authorization_status: AUTHORIZED
    AuthorizationStatus_NOTAUTH:
      summary: Example- Not Authorized
      value:
          authorization_status: NOT-AUTHORIZED
          reason: REJECTED

    # POST Authorization Details
    AuthorizationDetails:
      summary: Authorisation Details Request for a single service name
      value:
          issuer_bic: EGHIRXBR
          correspondent_bic: BANKBEBB
          service_name: swift.fin

    AuthorizationDetailsSingle:
      summary: Example-1- Authorization Details Single
      value:
        - service_name: swift.fin
          authorization_status: AUTHORIZED
          allowed_mesg_types: 1**, -101, 202, 204, 599
          activated_mesg_types: 103, 204, 599
          issued_date: 06/08/2023
          activated_date: 06/08/2023
          validity_period_from_date: 06/08/2023
          validity_period_to_date: 04/03/2025

    AuthorizationDetailsMultiRequest:
      summary: Authorisation Details Request for multiple services
      value:
          issuer_bic: EGHIRXBR
          correspondent_bic: BANKBEBB
          service_name: All

    AuthorizationDetailsMulti:
      summary: Example-1- Authorization Details Multi
      value:
        - service_name: swift.fin
          authorization_status: AUTHORIZED
          allowed_mesg_types: 101, 202, 204,  599
          activated_mesg_types: 101
          issued_date: 06/08/2023
          activated_date: 06/08/2023
          validity_period_from_date: 06/08/2023
          validity_period_to_date: 04/03/2025
        - service_name: swift.finplus
          authorization_status: AUTHORIZED
          allowed_mesg_types: pacs.002, pacs.004, pacs.008, camt.052, camt.053, camt.054
          activated_mesg_types: pacs.002, camt.053
          issued_date: 06/08/2023
          activated_date: 06/08/2023
          validity_period_from_date: 06/08/2023
          validity_period_to_date: 04/03/2025