openapi: "3.0.0"
info:
  version: 0.9.6
  title: Common Payment API
  description: 
    This specification defines a simple payment API for payment types used in Switzerland. The API is supposed to be used by customers who want to initiate a payment at their bank. Note that, consents and SCA will be handled in a dedicated specification file.
    This specification uses schema definitions from the Common Data Model v1.2.1.
  termsOfService: 'Tbd'
  contact:
    email: info@common-api.ch
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  - url: payment.common-api.ch
externalDocs:
  description: Find out more about SFTI API specifications
  url: 'https://www.common-api.ch'
security:
  - OAuth2:
      - read
      - write
paths:
  /payments:
    post:
      tags:
        - Payments submissions
      summary: Initiate new payments submission
      description: Create new payments submission
      operationId: submitPaymentsSubmissionUsingPOST
      requestBody:
        description: Details of payments submission to be added
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/paymentSubmissionRequest'
      responses:
        '201':
          description: created
          headers:
            location:
              schema:
                type: string
                format: uri
                description: Link to the created resource

  /payments/{submissionId}:
    get:
      tags:
        - Payments submissions
      description: Retrieve a specific payment submission
      summary: Get a specific payment submission
      parameters:
        - name: submissionId
          in: path
          description: ID of payment submission to be retrieved
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: The original payment submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentSubmissionRequest'

  /payments/{submissionId}/status:
    get:
      tags:
        - Payments submissions
      description: Retrieve a specific payment submission's status
      summary: Get status information for the specific payment submission
      parameters:
        - name: submissionId
          in: path
          description: ID of chosen payment submission
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Status information for the specific payment submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentSubmissionStatus'

  /iso20022/payments:
    post:
      tags:
        - iso20022
      summary: Submit ISO20022 XML payment instruction (PAIN.001)
      description: Submit an XML PAIN.001 payment instruction according to the ISO20022 specification.
      requestBody:
        description: The XML PAIN.001
        required: true
        content:
          application/xml:
            schema:
              type: string
      responses:
        '201':
          description: created
          headers:
            location:
              schema:
                type: string
                format: uri
                description: link to the created resource
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /iso20022/payments/{submissionId}:
    get:
      tags:
        - iso20022
      summary: Retrieve a submitted ISO20022 XML PAIN.001 message.
      parameters:
        - in: path
          name: submissionId
          schema:
            type: string
          required: true
          description: Unique ID of the ISO20022 payment instruction
      responses:
        '200':
          description: Returns the requested ISO20022 XML PAIN.001 message
          content:
            application/xml:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /iso20022/payments/{submissionId}/status:
    get:
      tags:
        - iso20022
      summary: Get the ISO20022 XML status report (PAIN.002) for a specific payment instruction
      description: The status report for the requested XML ISO20022 payment instruction (PAIN.002)
      parameters:
        - in: path
          name: submissionId
          schema:
            type: string
          required: true
          description: Unique ID of the ISO20022 payment instruction
      responses:
        '200':
          description: Returns the requested ISO20022 XML PAIN.002 message
          content:
            application/xml:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /iso20022/statements:
    get:
      tags:
        - iso20022
      summary: Get list of resource links to account statements (CAMT.053)
      description: The resources links to available account statements (CAMT.053)
      responses:
        '200':
          description: Returns a list of resource links to ISO20022 XML CAMT.053 messages
          content:
            application/json:
              schema:
                type: object
                properties:
                  conditionList: 
                    type: array
                    items:
                      $ref: '#/components/schemas/iso20022ReportReference'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /iso20022/statements/{reportId}:
    get:
      tags:
        - iso20022
      summary: Retrieves a specifically requested ISO20022 XML CAMT.053 document
      parameters:
        - in: path
          name: reportId
          schema:
            type: string
          required: true
          description: Unique ID of the requested ISO20022 XML CAMT.053 document
      responses:
        '200':
          description: Returns the requested ISO20022 XML CAMT.053 message
          content:
            application/xml:
              schema:
                type: string 
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

          
# -------------------------
# -------- Models ---------
# -------------------------
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access
  schemas:

    # ---- From SIX ----
    paymentSubmissionRequest:
      title: Payment Submission Request
      type: object
      required:
        - messageId
        - initiatingPartyId
        - debtorAccount
        - bookingInstruction
        - transactions
        - requestedExecutionDate
      properties:
        messageId:
          type: string
          maxLength: 35
          example: "eb6305c91f7f49deaed016487c27b42d"
        initiatingPartyId:
          type: string
          maxLength: 32
          example: "TPP01746"
        requestedExecutionDate:
          type: string
          format: date
          example: "2018-04-07"
        debtorAccount:
          $ref: '#/components/schemas/paymentIbanAccount'
        bookingInstruction:
          $ref: '#/components/schemas/paymentBookingInstruction'
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/paymentInstructionItem'

    paymentIbanAccount:
      title: Payment IBAN Account
      type: object
      required:
        - type
        - identification
      properties:
        type:
          type: string
          description: The allowed account identification type for the creditor account depends on the payment type. The debtor account must always be an IBAN.
          enum:
            - "IBAN"
        identification:
          type: string
          maxLength: 34
          example: "CH9300762011623852957"
          pattern: "[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}"

    paymentQrIbanAccount:
      title: Payment QR-IBAN Account
      type: object
      required:
        - type
        - identification
      properties:
        type:
          type: string
          description: IBAN or QR-IBAN of the creditor, only IBANs with CH or LI country code permitted.
          enum:
            - "IBAN"
            - "QR_IBAN"
        identification:
          type: string
          maxLength: 34
          example: "CH9300762011623852957"
          pattern: "[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}"

    paymentOtherAccount:
      title: Payment Other Account
      type: object
      required:
        - type
        - identification
      properties:
        "type":
          type: string
          description: The allowed account identification type for the creditor account depends on the payment type. The debtor account must always be an IBAN.
          enum:
            - "OTHER"
        identification:
          type: string
          maxLength: 34
          example: "01-39139-1"

    paymentBookingInstruction:
      title: Payment Booking Instruction
      type: string
      enum:
        - "SINGLEBOOKING_SIA"
        - "SINGLEBOOKING_NOA"
        - "BATCHBOOKING_SALA_NOA"
        - "BATCHBOOKING_SALA_CND"
        - "BATCHBOOKING_NOA"
        - "BATCHBOOKING_CND"
        - "BATCHBOOKING_CWD"
      example: "BATCHBOOKING_SALA_CND"

    paymentInstructionItem:
      title: Payment Instruction Item
      type: object
      required:
        - instructionId
        - endToEndId
        - instructedAmount
      properties:
        instructionId:
          type: string
          maxLength: 35
          example: "INSTR-001"
        endToEndId:
          type: string
          maxLength: 35
          example: "ENDTOENDID-001"
        instructedAmount:
          $ref: '#/components/schemas/paymentCurrencyAmount'
        ibanDetails:
          $ref: '#/components/schemas/paymentIBANDetail'
        isrDetails:
          $ref: '#/components/schemas/paymentISRDetail'
        otherDetails:
          $ref: '#/components/schemas/paymentOtherDetail'
        qrDetails:
          $ref: '#/components/schemas/paymentQRDetail'

    paymentCurrencyAmount:
      title: Payment Currency-Amount
      type: object
      required:
        - currency
        - amount
      properties:
        currency:
          type: string
          maxLength: 3
          minLength: 3
          example: "CHF"
        amount:
          type: string
          pattern: "[0-9]{1,12}([.][0-9]{1,5})?"
          maxLength: 18
          example: "10.25"

    paymentIBANDetail:
      title: Payment IBAN Detail
      type: object
      required:
        - creditorAccount
        - creditor
      properties:
        sepaIndicator:
          type: boolean
          example: true
        creditorAccount:
          $ref: '#/components/schemas/paymentIbanAccount'
        creditorAgent:
          $ref: '#/components/schemas/paymentCreditorAgent'
        creditor:
          $ref: '#/components/schemas/paymentCreditor'
        chargeBearer:
          $ref: '#/components/schemas/paymentChargeBearerMethod'
        remittanceReference:
          $ref: '#/components/schemas/paymentIbanRemittanceReference'
        remittanceInformation:
          $ref: '#/components/schemas/paymentRemittanceInformation'

    paymentISRDetail:
      title: Payment ISR Detail
      type: object
      required:
        - remittanceReference
      properties:
        creditorAccount:
          $ref: '#/components/schemas/paymentOtherAccount'
        creditor:
          $ref: '#/components/schemas/paymentCreditor'
        remittanceReference:
          $ref: '#/components/schemas/paymentIsrRemittanceReference'

    paymentOtherDetail:
      title: Payment Other Detail
      type: object
      required:
        - creditorAccount
        - creditorAgent
        - creditor
      properties:
        creditorAccount:
          $ref: '#/components/schemas/paymentOtherAccount'
        creditorAgent:
          $ref: '#/components/schemas/paymentCreditorAgent'
        creditor:
          $ref: '#/components/schemas/paymentCreditor'
        chargeBearer:
          $ref: '#/components/schemas/paymentChargeBearerMethod'
        remittanceReference:
          $ref: '#/components/schemas/paymentOtherRemittanceReference'

    paymentQRDetail:
      title: Payment QR Detail
      type: object
      required:
        - creditor
        - creditorAccount
      properties:
        creditorAccount:
          $ref: '#/components/schemas/paymentQrIbanAccount'
        creditor:
          $ref: '#/components/schemas/paymentCreditor'
        ultimateCreditor:
          $ref: '#/components/schemas/paymentCreditor'
        ultimateDebtor:
          $ref: '#/components/schemas/paymentDebtor'
        remittanceReference:
          $ref: '#/components/schemas/paymentIbanRemittanceReference'
        remittanceInformation:
          $ref: '#/components/schemas/paymentRemittanceInformation'

    paymentCreditorAgent:
      type: object
      properties:
        bic:
          type: string
          maxLength: 11
          example: "BDEMMXMM"
        clearingSystemMemberIdentification:
          $ref: '#/components/schemas/commonClearingSystemMemberIdentification'

    commonClearingSystemMemberIdentification:
      title: Common Clearing System Member Identification
      type: object
      required:
        - code
        - memberId
      properties:
        code:
          type: string
          maxLength: 5
          example: "CHBCC"
        memberId:
          type: string
          maxLength: 35
          example: "00230"
    
    paymentCreditor:
      title: Payment Creditor
      type: object
      required:
        - name
        - postalAddress
      properties:
        name:
          type: string
          maxLength: 140
        postalAddress:
          $ref: '#/components/schemas/paymentStructuredOrUnstructuredAddress'

    paymentDebtor:
      title: Payment Debtor
      type: object
      required:
        - name
        - postalAddress
      properties:
        name:
          type: string
        postalAddress:
          $ref: '#/components/schemas/paymentStructuredOrUnstructuredAddress'

    paymentChargeBearerMethod:
      title: Payment Charge Bearer Method
      type: string
      enum:
        - "DEBT"
        - "CRED"
        - "SHAR"
        - "SLEV"
      example: "SHAR"

    paymentIbanRemittanceReference:
      title: Payment Remittance Reference
      description: either remittanceReference or remittanceInformation must be set
      type: object
      properties:
        type:
          type: string
          enum:
            - SCOR
            - QRR
        reference:
          type: string
          maxLength: 35
          example: "210000000003139471430009017"

    paymentIsrRemittanceReference:
      title: Payment Remittance Reference
      description: either remittanceReference or remittanceInformation must be set
      type: object
      properties:
        type:
          type: string
          enum:
            - ISR
        reference:
          type: string
          maxLength: 35
          example: "210000000003139471430009017"

    paymentOtherRemittanceReference:
      title: Payment Remittance Reference
      description: either remittanceReference or remittanceInformation must be set
      type: object
      properties:
        type:
          type: string
          enum:
            - SCOR
        reference:
          type: string
          maxLength: 35
          example: "210000000003139471430009017"

    paymentRemittanceInformation:
      title: Payment Remittance Information
      description: either remittanceReference or remittanceInformation must be set
      type: string
      maxLength: 140
      example: "Rechnung Nr. 408"

    paymentStructuredAddress:
      title: Structured Address for Payments
      type: object
      required:
        - streetName
        - postCode
        - townName
        - country
      properties:
        streetName:
          type: string
          maxLength: 70
          example: "Rue de la gare"
        buildingNumber:
          type: string
          maxLength: 16
          example: "24"
        postCode:
          type: string
          maxLength: 16
          example: "2501"
        townName:
          type: string
          maxLength: 35
          example: "Biel"
        country:
          type: string
          maxLength: 2
          example: "CH"

    paymentUnstructuredAddress:
      title: Unstructured Address for Payments
      type: object
      required:
        - addressLines
        - country
      properties:
        addressLines:
          type: array
          description: max 2 lines of 70 characters
          maxLength: 2
          example: ["Robert Schneider SA", "Rue de la gare 24"]
          items:
            type: string
            maxLength: 70
        country:
          type: string
          maxLength: 2
          example: "CH"

    paymentStructuredOrUnstructuredAddress:
      title: Payment Structured or Unstructured Address
      description: Either structured or unstructered must be set
      type: object
      properties:
        structured:
          $ref: '#/components/schemas/paymentStructuredAddress'
        unstructured:
          $ref: '#/components/schemas/paymentUnstructuredAddress'

    paymentSubmissionStatus:
      title: Payment Submission Status
      type: object
      required:
        - statusCode
      properties:
        messageId:
          type: string
          example: "eb6305c91f7f49deaed016487c27b42d"
        statusCode:
          type: string
          enum:
            - ACCP
            - RJCT
            - PART
          example: "PART"
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/paymentInstructionItemStatus'

    paymentInstructionItemStatus:
      title: Payment Instruction Item Status
      type: object
      required:
        - instructionId
        - statusCode
      properties:
        instructionId:
          type: string
          maxLength: 35
          example: "DNCS-20180322-IXN0-TXN0"
        statusCode:
          type: string
          enum:
            - ACCP
            - RJCT
          example: "RJCT"
        reasonCode:
          type: string
          example: "CURR"
        reasonInformation:
          type: string
          maxLength: 105
          example: "currency USD not allowed for payment type ISR"

    iso20022ReportReference:
      title: ISO 20022 Report Reference
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        type:
          type: string
          enum:
            - CAMT53
        id:
          type: string
    # --- End SIX -----

    # ---- Common Data Model v1.2.0
    # ---- Date Formats
    Date:
      type: string
      format: date
      example: 2018-04-13
      
    DateTime:
      type: string
      format: date-time
      example: 2018-04-13T11:11:11Z
    # --------
    # ---- Links ----
    Links:
      description: links returned in the answer of an API call
      type: object
      properties:
        self:
          type: string
        first:
          type: string
        previous:
          type: string
        next:
          type: string
        last:
          type: string 
    # ---------
    # ---- Currency ----
    Currency:
      description: ISO 4217 code
      type: string
      pattern: '[A-Z]{3}'
    # ---------
    # ---- Amount ----
    Amount:
      description: amount with currency
      type: object
      required:
        - currency
        - content
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
        content:
          description: amount given with fractional digits, the separator is a dot
          type: string
          pattern: '-?\d{1,14}(?:\.\d{1,3})?'
    # --------
    # ---- Error Response (compliant to SIX b.Link)
    commonErrorResponse:
      title: Common Error Response
      type: object
      properties:
        type:
          $ref: '#/components/schemas/commonErrorType'
        title:
          type: string
          example:
            This is the general problem description
        detail:
          type: string
          example:
            Detailed problem description with respect to the current request
        instance:
          type: string
          example:
            path/to/corresponding/resource

    commonErrorType:
      title: Common Error Type
      description: Error Types for commonErrorResponse.
      type: string
      enum:
        - /problems/INVALID_PAYLOAD
        - /problems/MALFORMED_PAYLOAD
        - /problems/INVALID_TOKEN
        - /problems/EXPIRED_TOKEN
        - /problems/INSUFFICIENT_PRIVILEGES
        - /problems/NO_ACCESS_TO_RESOURCE
        - /problems/RESOURCE_DOES_NOT_EXIST
        - /problems/RESOURCE_NOT_READY
        - /problems/RESOURCE_TOO_LARGE
        - /problems/WRONG_METHOD
        - /problems/OPERATION_NOT_ALLOWED
        - /problems/TECHNICAL_ERROR
        - /problems/NOT_IMPLEMENTED
        - /problems/SERVICE_UNAVAILABLE
      example: '/problems/TECHNICAL_ERROR'
    # ---- End Error Response
    # ---- End Common Data Model

  # ---- Responses - Standard Errors Common Data Model v1.2.1----
  responses:
    standard400:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
      description: Bad Request - The server cannot or will not process the request due to something that is perceived to be a client error as malformed request syntax.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard401:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
      description: Unauthorized - The request has not been applied because it lacks valid authentication credentials for the target resource.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard403:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
      description: Forbidden - The server understood the request but refuses to authorize it. 
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard404:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
      description: Not Found - The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard405:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
      description: Method Not Allowed - The method received in the request-line is known by the origin server but not supported by the target resource.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard500:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
      description: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard501:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
      description: Not Implemented - The server does not support the functionality required to fulfill the request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard503:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
      description: Service Unavailable. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
  # ---- End Responses - Standard Errors