Architecture/SEPA-TIS-Specs.md

@@ -8,13 +8,17 @@ info:
   description: API for TIS connection to DIS in SEPA connector project
   version: 1.0.0
   title: SEPA-TIS
+  # put the contact info for your development or API team
   contact:
     email: kbotor@syncad.com
+
+# tags are used for organizing operations
 tags:
-  - name: input
-    description: Endpoints for mesages incoming from bank
-  - name: output
-    description: Endpoints for messages outgoing to bank
+- name: input
+  description: Endpoints for mesages incoming from bank
+- name: output
+  description: Endpoints for messages outgoing to bank
+
 paths:
   /payment-request:
     post:
@@ -30,13 +34,13 @@ paths:
       parameters:
         - in: body
           name: paymentRequest
-          description: Payment requet to send
+          description: Payment request to send
           schema:
             $ref: '#/definitions/PaymentRequest'
       responses:
-        '200':
+        200:
           description: ALways HTTP code 200
-          schema:
+          schema: 
             $ref: '#/definitions/Response'
   /payment-return-request:
     post:
@@ -52,61 +56,133 @@ paths:
       parameters:
         - in: body
           name: paymentReturnRequest
-          description: Payment requet to send
+          description: Payment return request to send
           schema:
             $ref: '#/definitions/PaymentReturnRequest'
       responses:
-        '200':
+        200:
           description: ALways HTTP code 200
+          schema: 
+            $ref: '#/definitions/Response'
+  /payment-return:
+    post:
+      tags:
+        - output
+      summary: Sends payment return to bank
+      operationId: paymentReturn
+      description: Sends payment return to bank
+      consumes:
+        - application/json
+      produces:
+        - application/json
+      parameters:
+        - in: body
+          name: paymentReturn
+          description: Payment return to send
           schema:
+            $ref: '#/definitions/PaymentReturn'
+      responses:
+        200:
+          description: ALways HTTP code 200
+          schema: 
             $ref: '#/definitions/Response'
 definitions:
   PaymentRequest:
     type: object
     required:
-      - jsonrpc
-      - id
-      - method
-      - params
+    - jsonrpc
+    - id
+    - method
+    - params
     properties:
       jsonrpc:
         type: number
         format: double
-        example: 1
+        enum:
+          - 1.0
+          - 2.0
+        description: JSON-RPC standard version number
+        example: 1.0
       id:
         type: integer
+        description: Request ID
         example: 1
       method:
         type: string
+        enum:
+          - ffcctrns
+        description: Method name
         example: ffcctrns
       params:
         type: array
+        description: Request parameters
         items:
-          $ref: '#/definitions/PaymentRequestParams'
+            $ref: '#/definitions/PaymentRequestParams'
   PaymentReturnRequest:
     type: object
     required:
-      - jsonrpc
-      - id
-      - method
-      - params
+    - jsonrpc
+    - id
+    - method
+    - params
     properties:
       jsonrpc:
         type: number
         format: double
+        enum:
+          - 1.0
+          - 2.0
+        description: JSON-RPC standard version number
+        example: 1.0
+      id:
+        type: integer
+        description: Request ID
         example: 1
+      method:
+        type: string
+        enum:
+          - ffpcqrst
+        description: Method name
+        example: ffpcqrst
+      params:
+        type: array
+        description: Request parameters
+        items:
+            $ref: '#/definitions/PaymentReturnRequestParams'
+  PaymentReturn:
+    type: object
+    required:
+    - jsonrpc
+    - id
+    - method
+    - params
+    properties:
+      jsonrpc:
+        type: number
+        format: double
+        enum:
+          - 1.0
+          - 2.0
+        description: JSON-RPC standard version number
+        example: 1.0
       id:
         type: integer
+        description: Request ID
         example: 1
       method:
         type: string
-        example: ffcctrns
+        enum:
+          - prtrn
+        description: Method name
+        example: prtrn
       params:
         type: array
+        description: Request parameters
         items:
-          $ref: '#/definitions/PaymentReturnRequestParams'
+            $ref: '#/definitions/PaymentReturnParams'
   PaymentRequestParams:
     type: object
+    description: Payment request data
     required:
       - header
       - payment_data
@@ -118,28 +194,35 @@ definitions:
         $ref: '#/definitions/PaymentData'
       chrg_br:
         type: string
+        enum:
+          - SLEV
+        description: Charge Bearer
         example: SLEV
   PaymentReturnRequestParams:
     type: object
+    description: Payment return request data
     required:
       - header
       - assigner_bic
       - assignee_bic
       - cancellation_id
-      - payment_data
-      - cancellation_reason
       - cancelling_party
+      - cancellation_reason
+      - payment_data
     properties:
       header:
         $ref: '#/definitions/DocumentHeader'
       assigner_bic:
         type: string
+        description: Assigner BIC
         example: PCTULT21XXX
       assignee_bic:
         type: string
+        description: Assignee (BoL) BIC
         example: LIABLT2XMSD
       cancellation_id:
         type: string
+        description: Cancellation transaction identifier. Unique, as required in Chapter IX of the document SEPA-MMS User Detailed Functional Specifications for Credit Transfer Processing (SCT). Uniqueness is checked.
         example: D118100301085772
       cancelling_party:
         $ref: '#/definitions/CancellingParty'
@@ -147,8 +230,60 @@ definitions:
         $ref: '#/definitions/CancellationReason'
       payment_data:
         $ref: '#/definitions/PaymentData'
+  PaymentReturnParams:
+    type: object
+    description: Payment return data
+    required:
+      - header
+      - return_id
+      - return_reason
+      - returning_party
+      - return_amount
+      - return_currency
+      - chrg_br
+      - settlment_date
+      - payment_data
+    properties:
+      header:
+        $ref: '#/definitions/DocumentHeader'
+      return_id:
+        type: string
+        description: Return identification. Unique, as required in Chapter IX of the document SEPA-MMS User Detailed Functional Specifications for Credit Transfer Processing (SCT). Uniqueness is checked.
+        example: D118100301086072
+      return_amount:
+        type: number
+        format: double
+        description: Returned amount, calculated according to return reason
+        example: 13.31
+      return_currency:
+        type: string
+        enum:
+          - EUR
+        description: Returned amount currency
+        example: EUR
+      chrg_br:
+        type: string
+        enum:
+          - SLEV
+        description: Charge Bearer
+        example: SLEV
+      settlment_date:
+        type: string
+        description: Current or next TARGET2 business day
+        format: date
+      additional_info:
+        type: string
+        description: Cancellation transaction identifier from FFPCRQST, only filled if return_reason/iso_code is FOCR
+        example: D118100301085772
+      returning_party:
+        $ref: '#/definitions/ReturningParty'
+      return_reason:
+        $ref: '#/definitions/ReturnReason'
+      payment_data:
+        $ref: '#/definitions/PaymentData'
   DocumentHeader:
     type: object
+    description: Document header
     required:
       - doc_id
       - type
@@ -158,21 +293,33 @@ definitions:
     properties:
       doc_id:
         type: string
+        description: Document ID - the structure is established in Section IX of the document LITAS-Pranesimu formatai.docx.
         example: D118091001045732
       type:
         type: string
+        enum:
+          - FFCCTRNS
+          - FFPCRQST
+          - PRTRN
+          - ROINVSTG
+        description: Document type. Allowed values are FFCCTRNS/FFPCRQST/PRTRN/ROINVSTG
         example: FFCCTRNS
       date_time:
         type: string
         format: date-time
+        description: Document creation timestamp
+        example: 2018-10-03T08:48:09
       priority:
         type: integer
+        description: Document priority
         example: 51
       business_area:
         type: string
-        example: SEAPSCT
+        description: Document business area
+        example: SEPASCT
   PaymentData:
     type: object
+    description: Payment data
     required:
       - instr_id
       - end_to_end_id
@@ -188,31 +335,46 @@ definitions:
     properties:
       instr_id:
         type: string
+        description: Instruction identification
         example: D118091001048175
       end_to_end_id:
         type: string
+        description: A sending customer reference that must be passed to a receiveing customer. In the event that no reference was given, the value NOTPROVIDED must be used. 
         example: NOTPROVIDED
       tx_id:
         type: string
+        description: Unique Id of a transaction, as required in Chapter IX of the document SEPA-MMS User Detailed Functional Specifications for Credit Transfer Processing (SCT). Uniqueness is checked.
         example: 8e7070743da24402a7fc290bc62fbcd0
       amount:
         type: number
         format: double
+        description: Payment amount
         example: 13.31
       currency:
         type: string
+        enum:
+          - EUR
+        description: Payment currency
         example: EUR
       date:
         type: string
+        description: Payment date. In payment request must be current or next TARGET2 business day.
         format: date
       mtd:
         type: string
+        enum:
+          - CLRG
+        description: Settlment method
         example: CLRG
       prtry:
         type: string
+        description: Clearing system 
         example: LITAS-MIG
       cd:
         type: string
+        enum:
+          - SEPA
+        description: Service level code
         example: SEPA
       debtor:
         $ref: '#/definitions/Participant'
@@ -220,22 +382,73 @@ definitions:
         $ref: '#/definitions/Participant'
   CancellingParty:
     type: object
+    description: Cancelling party data. Only one of available properties can be filled.
     properties:
       customer_name:
         type: string
+        description: Customer name or BIC
         example: Dan Notestein or PCTULT21XXX
       bank_bic:
         type: string
+        description: Bank BIC
         example: PCTULT21XXX
   CancellationReason:
     type: object
-    properties:
+    description: Cancellation reason. Only one of available properties can be filled
+    properties: 
       iso_code:
         type: string
+        enum:
+          - DUPL
+        description: ISO code of cancellation reason
         example: DUPL
       code:
         type: string
-        example: FRAD or TECH
+        enum:
+          - FRAD
+          - TECH
+        description: Custom code of cancellation reason
+        example: FRAD
+  ReturningParty:
+    type: object
+    description: Data of party returning payment. Only one of available properties can be filled
+    properties:
+      customer_name:
+        type: string
+        description: Customer's name or BIC
+        example: Dan Notestein or PCTULT21XXX
+      bank_bic:
+        type: string
+        description: Bank BIC
+        example: PCTULT21XXX
+  ReturnReason:
+    type: object
+    description: Reason for payment return, Only one of available properties can be filled
+    properties: 
+      iso_code:
+        type: string
+        enum:
+          - AC01
+          - AC04
+          - AC06
+          - AG01
+          - AG02
+          - AM05
+          - BE04
+          - FOCR
+          - MD07
+          - MS02
+          - MS03
+          - RC01
+          - RR01
+          - RR02
+          - RR03
+          - RR04
+        description: ISO code of payment return reason. Allowed values are AC01, AC04, AC06, AG01, AG02, AM05, BE04, FOCR, MD07, MS02, MS03, RC01, RR01, RR02, RR03, RR04
+        example: FOCR
+      code:
+        type: string
+        description: Custom code of payment return reason
   Participant:
     type: object
     required:
@@ -245,24 +458,34 @@ definitions:
     properties:
       bic:
         type: string
+        description: Participant;s BIC
         example: LIABLT20XXX
       iban:
         type: string
+        description: Participant's IBAN
         example: LT261010000002132402
       name:
         type: string
+        description: Participant's name
         example: Dan Notestein
       country:
         type: string
-        example: LT
+        description: Participant's country ISO 3166-1 alpha-2 code
+        example: US
       address_line1:
         type: string
+        description: Participant's address
+        example: PO Box 10608
       address_line2:
         type: string
+        description: Participant's address
+        example: Blacksburg, VA 24062-0608
   Response:
     type: object
+    description: API response type for 'output' type endpoints
     required:
       - id
+      - result
     properties:
       id:
         type: integer
@@ -273,27 +496,40 @@ definitions:
         $ref: '#/definitions/Error'
   Result:
     type: object
+    description: Operation result
     required:
-      - doc_id
-      - status
+     - doc_id
+     - status
     properties:
       doc_id:
         type: string
+        description: Document ID
         example: D118091001045732
       status:
         type: string
+        enum:
+          - Accepted
+          - Error
+        description: Request status. Available values are Accepted, Error
         example: Accepted
   Error:
     type: object
+    description: Error object. Only sent if result.status is 'Error'
     required:
       - code
       - message
     properties:
       code:
         type: string
+        enum:
+          - DIS-0001
+          - DIS-0002
+          - DIS-0003
+        description: Error code (1 - document with given ID already exists, 2 - missing required data, 3 - technical error)
         example: DIS-0001
       message:
         type: string
+        description: Error message
         example: Document with given ID already exists
 host: localhost
 basePath: /