Update SEPA TIS Specs authored by Konrad Botor's avatar Konrad Botor
...@@ -3,22 +3,18 @@ ...@@ -3,22 +3,18 @@
Note: All endpoints will be on the same path, only `method` parameter will change Note: All endpoints will be on the same path, only `method` parameter will change
```yaml ```yaml
swagger: '2.0' openapi: 3.0.0
info: info:
description: API for TIS connection to DIS in SEPA connector project description: API for TIS connection to DIS in SEPA connector project
version: 1.0.0 version: 1.0.0
title: SEPA-TIS title: SEPA-TIS
# put the contact info for your development or API team
contact: contact:
email: kbotor@syncad.com email: kbotor@syncad.com
# tags are used for organizing operations
tags: tags:
- name: input - name: input
description: Endpoints for mesages incoming from bank description: Endpoints for mesages incoming from bank
- name: output - name: output
description: Endpoints for messages outgoing to bank description: Endpoints for messages outgoing to bank
paths: paths:
/payment-request: /payment-request:
post: post:
...@@ -27,21 +23,19 @@ paths: ...@@ -27,21 +23,19 @@ paths:
summary: Sends payment request to bank summary: Sends payment request to bank
operationId: paymentRequest operationId: paymentRequest
description: Sends payment request to bank description: Sends payment request to bank
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: paymentRequest
description: Payment request to send
schema:
$ref: '#/definitions/PaymentRequest'
responses: responses:
200: '200':
description: ALways HTTP code 200 description: ALways HTTP code 200
content:
application/json:
schema:
$ref: '#/components/schemas/Response'
requestBody:
content:
application/json:
schema: schema:
$ref: '#/definitions/Response' $ref: '#/components/schemas/PaymentRequest'
description: Payment request to send
/payment-return-request: /payment-return-request:
post: post:
tags: tags:
...@@ -49,21 +43,19 @@ paths: ...@@ -49,21 +43,19 @@ paths:
summary: Sends payment return request to bank summary: Sends payment return request to bank
operationId: paymentReturnRequest operationId: paymentReturnRequest
description: Sends payment return request to bank description: Sends payment return request to bank
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: paymentReturnRequest
description: Payment return request to send
schema:
$ref: '#/definitions/PaymentReturnRequest'
responses: responses:
200: '200':
description: ALways HTTP code 200 description: ALways HTTP code 200
content:
application/json:
schema: schema:
$ref: '#/definitions/Response' $ref: '#/components/schemas/Response'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentReturnRequest'
description: Payment return request to send
/payment-return: /payment-return:
post: post:
tags: tags:
...@@ -71,22 +63,63 @@ paths: ...@@ -71,22 +63,63 @@ paths:
summary: Sends payment return to bank summary: Sends payment return to bank
operationId: paymentReturn operationId: paymentReturn
description: Sends payment return to bank description: Sends payment return to bank
consumes: responses:
- application/json '200':
produces: description: ALways HTTP code 200
- application/json content:
parameters: application/json:
- in: body schema:
name: paymentReturn $ref: '#/components/schemas/Response'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentReturn'
description: Payment return to send description: Payment return to send
/resolution-of-investigation:
post:
tags:
- output
summary: Sends resolution of investigation to bank
operationId: resloutionOfInvestigation
description: Sends resolution of investigation to bank
responses:
'200':
description: ALways HTTP code 200
content:
application/json:
schema: schema:
$ref: '#/definitions/PaymentReturn' $ref: '#/components/schemas/Response'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ResolutionOfInvestigation'
description: Resolution of investigation to send
/next-message:
post:
tags:
- input
summary: Checks for new mesages from bank
operationId: nextMessage
description: Checks for new mesages from bank
responses: responses:
200: '200':
description: ALways HTTP code 200 description: ALways HTTP code 200
content:
application/json:
schema: schema:
$ref: '#/definitions/Response' $ref: '#/components/schemas/NextMessageResponse'
definitions: requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NextMessageRequest'
description: Next message request
servers:
- url: 'https://localhost:8080/'
components:
schemas:
PaymentRequest: PaymentRequest:
type: object type: object
required: required:
...@@ -99,10 +132,10 @@ definitions: ...@@ -99,10 +132,10 @@ definitions:
type: number type: number
format: double format: double
enum: enum:
- 1.0 - 1
- 2.0 - 2
description: JSON-RPC standard version number description: JSON-RPC standard version number
example: 1.0 example: 1
id: id:
type: integer type: integer
description: Request ID description: Request ID
...@@ -117,7 +150,9 @@ definitions: ...@@ -117,7 +150,9 @@ definitions:
type: array type: array
description: Request parameters description: Request parameters
items: items:
$ref: '#/definitions/PaymentRequestParams' $ref: '#/components/schemas/PaymentRequestParams'
minItems: 1
maxItems: 1
PaymentReturnRequest: PaymentReturnRequest:
type: object type: object
required: required:
...@@ -130,10 +165,10 @@ definitions: ...@@ -130,10 +165,10 @@ definitions:
type: number type: number
format: double format: double
enum: enum:
- 1.0 - 1
- 2.0 - 2
description: JSON-RPC standard version number description: JSON-RPC standard version number
example: 1.0 example: 1
id: id:
type: integer type: integer
description: Request ID description: Request ID
...@@ -148,7 +183,9 @@ definitions: ...@@ -148,7 +183,9 @@ definitions:
type: array type: array
description: Request parameters description: Request parameters
items: items:
$ref: '#/definitions/PaymentReturnRequestParams' $ref: '#/components/schemas/PaymentReturnRequestParams'
minItems: 1
maxItems: 1
PaymentReturn: PaymentReturn:
type: object type: object
required: required:
...@@ -161,10 +198,10 @@ definitions: ...@@ -161,10 +198,10 @@ definitions:
type: number type: number
format: double format: double
enum: enum:
- 1.0 - 1
- 2.0 - 2
description: JSON-RPC standard version number description: JSON-RPC standard version number
example: 1.0 example: 1
id: id:
type: integer type: integer
description: Request ID description: Request ID
...@@ -179,7 +216,75 @@ definitions: ...@@ -179,7 +216,75 @@ definitions:
type: array type: array
description: Request parameters description: Request parameters
items: items:
$ref: '#/definitions/PaymentReturnParams' $ref: '#/components/schemas/PaymentReturnParams'
minItems: 1
maxItems: 1
ResolutionOfInvestigation:
type: object
required:
- jsonrpc
- id
- method
- params
properties:
jsonrpc:
type: number
format: double
enum:
- 1
- 2
description: JSON-RPC standard version number
example: 1
id:
type: integer
description: Request ID
example: 1
method:
type: string
enum:
- roinvstg
description: Method name
example: roinvstg
params:
type: array
description: Request parameters
items:
$ref: '#/components/schemas/ResolutionOfInvestigationParams'
minItems: 1
maxItems: 1
NextMessageRequest:
type: object
required:
- jsonrpc
- id
- method
- params
properties:
jsonrpc:
type: number
format: double
enum:
- 1
- 2
description: JSON-RPC standard version number
example: 1
id:
type: integer
description: Request ID
example: 1
method:
type: string
enum:
- nextmsg
description: Method name
example: nextmsg
params:
type: array
description: RequestParameters
items:
$ref: '#/components/schemas/NextMessageRequestParams'
minItems: 1
maxItems: 1
PaymentRequestParams: PaymentRequestParams:
type: object type: object
description: Payment request data description: Payment request data
...@@ -189,9 +294,9 @@ definitions: ...@@ -189,9 +294,9 @@ definitions:
- chrg_br - chrg_br
properties: properties:
header: header:
$ref: '#/definitions/DocumentHeader' $ref: '#/components/schemas/DocumentHeader'
payment_data: payment_data:
$ref: '#/definitions/PaymentData' $ref: '#/components/schemas/PaymentData'
chrg_br: chrg_br:
type: string type: string
enum: enum:
...@@ -211,7 +316,7 @@ definitions: ...@@ -211,7 +316,7 @@ definitions:
- payment_data - payment_data
properties: properties:
header: header:
$ref: '#/definitions/DocumentHeader' $ref: '#/components/schemas/DocumentHeader'
assigner_bic: assigner_bic:
type: string type: string
description: Assigner BIC description: Assigner BIC
...@@ -222,14 +327,17 @@ definitions: ...@@ -222,14 +327,17 @@ definitions:
example: LIABLT2XMSD example: LIABLT2XMSD
cancellation_id: cancellation_id:
type: string 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. 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 example: D118100301085772
cancelling_party: cancelling_party:
$ref: '#/definitions/CancellingParty' $ref: '#/components/schemas/CancellingParty'
cancellation_reason: cancellation_reason:
$ref: '#/definitions/CancellationReason' $ref: '#/components/schemas/CancellationReason'
payment_data: payment_data:
$ref: '#/definitions/PaymentData' $ref: '#/components/schemas/PaymentData'
PaymentReturnParams: PaymentReturnParams:
type: object type: object
description: Payment return data description: Payment return data
...@@ -245,15 +353,18 @@ definitions: ...@@ -245,15 +353,18 @@ definitions:
- payment_data - payment_data
properties: properties:
header: header:
$ref: '#/definitions/DocumentHeader' $ref: '#/components/schemas/DocumentHeader'
return_id: return_id:
type: string 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. 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 example: D118100301086072
return_amount: return_amount:
type: number type: number
format: double format: double
description: Returned amount, calculated according to return reason description: 'Returned amount, calculated according to return reason'
example: 13.31 example: 13.31
return_currency: return_currency:
type: string type: string
...@@ -269,18 +380,84 @@ definitions: ...@@ -269,18 +380,84 @@ definitions:
example: SLEV example: SLEV
settlment_date: settlment_date:
type: string type: string
description: Current or next TARGET2 business day
format: date format: date
description: Current or next TARGET2 business day
example: '2018-10-03T00:00:00.000Z'
additional_info: additional_info:
type: string type: string
description: Cancellation transaction identifier from FFPCRQST, only filled if return_reason/iso_code is FOCR description: >-
Cancellation transaction identifier from FFPCRQST, only filled if
return_reason/iso_code is FOCR
example: D118100301085772 example: D118100301085772
returning_party: returning_party:
$ref: '#/definitions/ReturningParty' $ref: '#/components/schemas/ReturningParty'
return_reason: return_reason:
$ref: '#/definitions/ReturnReason' $ref: '#/components/schemas/ReturnReason'
payment_data: payment_data:
$ref: '#/definitions/PaymentData' $ref: '#/components/schemas/PaymentData'
ResolutionOfInvestigationParams:
type: object
description: Resoultion of investigation data
required:
- header
- assigner_bic
- assignee_bic
- status
- resolution_id
- rejecting_party
- rejection_reason
- payment_data
properties:
header:
$ref: '#/components/schemas/DocumentHeader'
assigner_bic:
type: string
description: Assigner BIC
example: PCTULT21XXX
assignee_bic:
type: string
description: Assignee (BoL) BIC
example: LIABLT2XMSD
status:
type: string
enum:
- RJCR
description: Confirmation of resolution of investigation
example: RJCR
resolution_id:
type: string
description: >-
Identification of the cancellation request transaction status.
Unique, as required in Chapter IX of the document SEPA-MMS User
Detailed Functional Specifications for Credit Transfer Processing
(SCT). Uniqueness is checked.
example: D118100301086192
rejecting_party:
$ref: '#/components/schemas/RejectingParty'
rejection_reason:
$ref: '#/components/schemas/RejectionReason'
additional_info:
type: array
items:
type: string
minItems: 1
maxItems: 2
description: To be used only when code is ‘LEGL’ in order to precise the reason.
example:
- AT51Description
- AT57Description
payment_data:
$ref: '#/components/schemas/PaymentData'
NextMessageRequestParams:
type: object
description: Next message request parameters
required:
- tis_code
properties:
tis_code:
type: string
description: Two character TIS code - all generated IDs start with this
example: D1
DocumentHeader: DocumentHeader:
type: object type: object
description: Document header description: Document header
...@@ -293,7 +470,9 @@ definitions: ...@@ -293,7 +470,9 @@ definitions:
properties: properties:
doc_id: doc_id:
type: string type: string
description: Document ID - the structure is established in Section IX of the document LITAS-Pranesimu formatai.docx. description: >-
Document ID - the structure is established in Section IX of the
document LITAS-Pranesimu formatai.docx.
example: D118091001045732 example: D118091001045732
type: type:
type: string type: string
...@@ -308,7 +487,7 @@ definitions: ...@@ -308,7 +487,7 @@ definitions:
type: string type: string
format: date-time format: date-time
description: Document creation timestamp description: Document creation timestamp
example: 2018-10-03T08:48:09 example: '2018-10-03T08:48:09.000Z'
priority: priority:
type: integer type: integer
description: Document priority description: Document priority
...@@ -339,11 +518,17 @@ definitions: ...@@ -339,11 +518,17 @@ definitions:
example: D118091001048175 example: D118091001048175
end_to_end_id: end_to_end_id:
type: string 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. 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 example: NOTPROVIDED
tx_id: tx_id:
type: string 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. 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 example: 8e7070743da24402a7fc290bc62fbcd0
amount: amount:
type: number type: number
...@@ -358,8 +543,11 @@ definitions: ...@@ -358,8 +543,11 @@ definitions:
example: EUR example: EUR
date: date:
type: string type: string
description: Payment date. In payment request must be current or next TARGET2 business day. description: >-
Payment date. In payment request must be current or next TARGET2
business day.
format: date format: date
example: '2018-10-03T00:00:00.000Z'
mtd: mtd:
type: string type: string
enum: enum:
...@@ -377,9 +565,9 @@ definitions: ...@@ -377,9 +565,9 @@ definitions:
description: Service level code description: Service level code
example: SEPA example: SEPA
debtor: debtor:
$ref: '#/definitions/Participant' $ref: '#/components/schemas/Participant'
creditor: creditor:
$ref: '#/definitions/Participant' $ref: '#/components/schemas/Participant'
CancellingParty: CancellingParty:
type: object type: object
description: Cancelling party data. Only one of available properties can be filled. description: Cancelling party data. Only one of available properties can be filled.
...@@ -411,7 +599,9 @@ definitions: ...@@ -411,7 +599,9 @@ definitions:
example: FRAD example: FRAD
ReturningParty: ReturningParty:
type: object type: object
description: Data of party returning payment. Only one of available properties can be filled description: >-
Data of party returning payment. Only one of available properties can be
filled
properties: properties:
customer_name: customer_name:
type: string type: string
...@@ -423,7 +613,9 @@ definitions: ...@@ -423,7 +613,9 @@ definitions:
example: PCTULT21XXX example: PCTULT21XXX
ReturnReason: ReturnReason:
type: object type: object
description: Reason for payment return, Only one of available properties can be filled description: >-
Reason for payment return, Only one of available properties can be
filled
properties: properties:
iso_code: iso_code:
type: string type: string
...@@ -444,11 +636,54 @@ definitions: ...@@ -444,11 +636,54 @@ definitions:
- RR02 - RR02
- RR03 - RR03
- RR04 - 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 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 example: FOCR
code: code:
type: string type: string
description: Custom code of payment return reason description: Custom code of payment return reason
RejectingParty:
type: object
description: >-
Data of party rejecting payment return. 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
RejectionReason:
type: object
description: >-
Reason for payment return rejection, Only one of available properties
can be filled
properties:
iso_code:
type: string
enum:
- LEGL
- CUST
description: >-
ISO code of payment return rejection reason. Allowed values are
LEGL, CUST
example: LEGL
code:
type: string
enum:
- ARDT
- AC04
- AM04
- NOAS
- NOOR
description: >-
Custom code of payment return reason. Allowed values are ARDT, AC04,
AM04, NOAS, NOOR
Participant: Participant:
type: object type: object
required: required:
...@@ -479,7 +714,7 @@ definitions: ...@@ -479,7 +714,7 @@ definitions:
address_line2: address_line2:
type: string type: string
description: Participant's address description: Participant's address
example: Blacksburg, VA 24062-0608 example: 'Blacksburg, VA 24062-0608'
Response: Response:
type: object type: object
description: API response type for 'output' type endpoints description: API response type for 'output' type endpoints
...@@ -489,11 +724,29 @@ definitions: ...@@ -489,11 +724,29 @@ definitions:
properties: properties:
id: id:
type: integer type: integer
description: Request ID
example: 1 example: 1
result: result:
$ref: '#/definitions/Result' $ref: '#/components/schemas/Result'
error: error:
$ref: '#/definitions/Error' $ref: '#/components/schemas/Error'
NextMessageResponse:
type: object
description: API response type for NextMessage endpoint
required:
- id
- result
properties:
id:
type: integer
description: Request ID
example: 1
result:
oneOf:
- $ref: '#/components/schemas/ErrorDocument'
- $ref: '#/components/schemas/Document'
error:
$ref: '#/components/schemas/Error'
Result: Result:
type: object type: object
description: Operation result description: Operation result
...@@ -510,8 +763,50 @@ definitions: ...@@ -510,8 +763,50 @@ definitions:
enum: enum:
- Accepted - Accepted
- Error - Error
description: Request status. Available values are Accepted, Error description: 'Request status. Available values are Accepted, Error'
example: Accepted example: Accepted
ErrorDocument:
type: object
description: >-
Document describing an error received from PAS (AUTHRES, SYNRES, RETURN)
or processing error in CPR subsystem
required:
- doc_id
- doc_ref_id
- timestamp
- error_code
- error_message
properties:
doc_id:
type: string
description: >-
ID of this document - generated either by PAS or CDR - the same
format as any other document ID
example: PS18091010000007
doc_ref_id:
type: string
description: Reference to the document that caused the error
example: D118091001045732
timestamp:
type: string
format: date-time
description: Timestamp of this document's creation
example: '2018-09-10T11:41:54.000Z'
error_code:
type: string
description: Error code as provided by PAS or CPR
example: PAS-81500000
error_message:
type: string
description: Error message as provided by PAS or CPR
example: >-
Priimami tik pasirašyti LITAS-INST ir PROXY sistemų pranešimai. Only
LITAS-INST and PROXY signed messages are accepted.
Document:
type: object
description: >-
One of possible incoming document types - data will be deserialized from
XML to Java class and then serialized to JSON
Error: Error:
type: object type: object
description: Error object. Only sent if result.status is 'Error' description: Error object. Only sent if result.status is 'Error'
...@@ -525,14 +820,12 @@ definitions: ...@@ -525,14 +820,12 @@ definitions:
- DIS-0001 - DIS-0001
- DIS-0002 - DIS-0002
- DIS-0003 - DIS-0003
description: Error code (1 - document with given ID already exists, 2 - missing required data, 3 - technical error) description: >-
Error code (1 - document with given ID already exists, 2 - missing
required data, 3 - technical error)
example: DIS-0001 example: DIS-0001
message: message:
type: string type: string
description: Error message description: Error message
example: Document with given ID already exists example: Document with given ID already exists
host: localhost
basePath: /
schemes:
- https
``` ```
\ No newline at end of file