Release of PSS v4

PSS Version 4.0

Today, we are excited to announce the release of the new major version of the Payment Submission Service API on bLink!

This release is the result of extensive discussions within the SFTI community, where existing API issues were throroughly examined and improved through various changes. Explore the detailed changes in the SFTI GitHub Changelog. A big thank you to the entire community for their contributions and to SFTI for the orchestration and refinement of the API.

Release

• XE/XP: 05/2024
• Prod: 11/2024

Added

• New value RCVD added to schema paymentSubmissionStatus

Changed

• Description of endpoints POST/iso20022/payments changed to specify supported XML-Schema
• Description of endpoints POST/iso20022/payments/{submissionId}/status changed to specify supported XML-Schema
• Status condition postalAddress in schema paymentCreditor changed to required
• Description of Location in headers changed to indicate that relative path shall be returned

Removed

• Endpoint GET/payments/{submissionId} removed
• Endpoint GET/iso20022/payments/{submissionId} removed

Changes in YAML

  '/payments':
    post:
    ...
- '/payments/{submissionId}':
-   get:
-     tags:
-       - payments
-     summary: Retrieve a payment submission
-     operationId: retrievePaymentSubmission
-     parameters:
-       - $ref: '#/components/parameters/path_submissionId'
-       - $ref: '#/components/parameters/permissionid_in_header' 
-       - $ref: '#/components/parameters/correlation_in_header'
-       - $ref: '#/components/parameters/agent_in_header'
-       - $ref: '#/components/parameters/targetid_in_header' 
-       - $ref: '#/components/parameters/psu_ip_in_header' 
-       - $ref: '#/components/parameters/psu_user_agent_in_header' 
-       - $ref: '#/components/parameters/optional_authorization_in_header' 
-       - $ref: '#/components/parameters/optional_instance_id_in_header' 

-     responses:
-       '200':
-         description: The original payment submission
-         headers:
-           X-Correlation-ID:
-             $ref: '#/components/headers/X-Correlation-ID'
-           X-CorAPI-Source:
-             $ref: '#/components/headers/X-CorAPI-Source'
-         content:
-           application/json:
-             schema:
-               $ref: '#/components/schemas/paymentSubmissionRequest'
-       '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'

  '/payments/{submissionId}/status':
   ...

  /iso20022/payments:
    post:
      tags:
        - iso20022
      summary: Submit an ISO20022 XML payment instruction (PAIN.001)
      description: |
        Submit an XML pain.001 payment instruction according to the ISO20022 specification.
+         * bLink supports payment instructions only in XML-Schema «pain.001.001.09».
      operationId: submitIso20022PaymentInstruction

- '/iso20022/payments/{submissionId}':
-   get:
-     tags:
-       - iso20022
-     summary: Retrieve the submitted ISO20022 XML PAIN.001 message.
-     operationId: retrieveIso20022PaymentInstruction
-     parameters:
-       - $ref: '#/components/parameters/path_submissionId'
-       - $ref: '#/components/parameters/permissionid_in_header' 
-       - $ref: '#/components/parameters/correlation_in_header'
-       - $ref: '#/components/parameters/agent_in_header'
-       - $ref: '#/components/parameters/targetid_in_header' 
-       - $ref: '#/components/parameters/psu_ip_in_header' 
-       - $ref: '#/components/parameters/psu_user_agent_in_header' 
-       - $ref: '#/components/parameters/optional_authorization_in_header' 
-       - $ref: '#/components/parameters/optional_instance_id_in_header' 

-     responses:
-       '200':
-         description: Returns the submitted ISO20022 XML PAIN.001 message
-         headers:
-           X-Correlation-ID:
-             $ref: '#/components/headers/X-Correlation-ID'
-           X-CorAPI-Source:
-             $ref: '#/components/headers/X-CorAPI-Source'
-         content:
-           application/xml:
-             schema:
-               type: string
-               format: binary
-       '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'

  /iso20022/payments/{submissionId}/status:
    get:
      tags:
        - iso20022
      summary: Retrieve ISO20022 XML status report of a payment instruction (PAIN.002)
      description: |
        Retrieve the status report for the requested XML ISO20022 payment instruction (PAIN.002).
+         * bLink supports status reports only in XML-Schema «pain.002.001.10».
      operationId: retrieveIso20022PaymentInstructionStatusReport

    ...
    ExpectedDurationInSeconds:
      description: Indicates by when Retrieve ISO20022 XML status report (PAIN.002) can be called to fetch the related PAIN.002.
      schema:
        type: string
    Location:
-     description: Location (submissionId) of the submitted message. Add /status for the status report.
+     description: Location (URI-reference) of the submitted message. The relative path shall be returned as URI-reference.
      schema:
        type: string
    X-Correlation-ID:
      description: Client defined ID from request to correlate HTTP requests between a client and a server
      schema:
      ...

    paymentCreditor:
      title: Payment Creditor
      type: object
      required:
        - name
+       - postalAddress
      properties:
        name:
          type: string
          maxLength: 70
          example: Hans Muster
        postalAddress:
          $ref: '#/components/schemas/paymentStructuredOrUnstructuredAddress'

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