Changes

Page history
Update SEPA TIS Specs authored by Konrad Botor's avatar Konrad Botor
Hide whitespace changes
Inline Side-by-side
Architecture/SEPA-TIS-Specs.md
View page @ 6d7e01d6
...@@ -8,13 +8,17 @@ info: ...@@ -8,13 +8,17 @@ 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:
...@@ -30,13 +34,13 @@ paths: ...@@ -30,13 +34,13 @@ paths:
parameters: parameters:
- in: body - in: body
name: paymentRequest name: paymentRequest
description: Payment requet to send description: Payment request to send
schema: schema:
$ref: '#/definitions/PaymentRequest' $ref: '#/definitions/PaymentRequest'
responses: responses:
'200': 200:
description: ALways HTTP code 200 description: ALways HTTP code 200
schema: schema:
$ref: '#/definitions/Response' $ref: '#/definitions/Response'
/payment-return-request: /payment-return-request:
post: post:
...@@ -52,61 +56,133 @@ paths: ...@@ -52,61 +56,133 @@ paths:
parameters: parameters:
- in: body - in: body
name: paymentReturnRequest name: paymentReturnRequest
description: Payment requet to send description: Payment return request to send
schema: schema:
$ref: '#/definitions/PaymentReturnRequest' $ref: '#/definitions/PaymentReturnRequest'
responses: responses:
'200': 200:
description: ALways HTTP code 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: schema:
$ref: '#/definitions/PaymentReturn'
responses:
200:
description: ALways HTTP code 200
schema:
$ref: '#/definitions/Response' $ref: '#/definitions/Response'
definitions: definitions:
PaymentRequest: PaymentRequest:
type: object type: object
required: required:
- jsonrpc - jsonrpc
- id - id
- method - method
- params - params
properties: properties:
jsonrpc: jsonrpc:
type: number type: number
format: double format: double
example: 1 enum:
- 1.0
- 2.0
description: JSON-RPC standard version number
example: 1.0
id: id:
type: integer type: integer
description: Request ID
example: 1 example: 1
method: method:
type: string type: string
enum:
- ffcctrns
description: Method name
example: ffcctrns example: ffcctrns
params: params:
type: array type: array
description: Request parameters
items: items:
$ref: '#/definitions/PaymentRequestParams' $ref: '#/definitions/PaymentRequestParams'
PaymentReturnRequest: PaymentReturnRequest:
type: object type: object
required: required:
- jsonrpc - jsonrpc
- id - id
- method - method
- params - params
properties: properties:
jsonrpc: jsonrpc:
type: number type: number
format: double format: double
enum:
- 1.0
- 2.0
description: JSON-RPC standard version number
example: 1.0
id:
type: integer
description: Request ID
example: 1 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: id:
type: integer type: integer
description: Request ID
example: 1 example: 1
method: method:
type: string type: string
example: ffcctrns enum:
- prtrn
description: Method name
example: prtrn
params: params:
type: array type: array
description: Request parameters
items: items:
$ref: '#/definitions/PaymentReturnRequestParams' $ref: '#/definitions/PaymentReturnParams'
PaymentRequestParams: PaymentRequestParams:
type: object type: object
description: Payment request data
required: required:
- header - header
- payment_data - payment_data
...@@ -118,28 +194,35 @@ definitions: ...@@ -118,28 +194,35 @@ definitions:
$ref: '#/definitions/PaymentData' $ref: '#/definitions/PaymentData'
chrg_br: chrg_br:
type: string type: string
enum:
- SLEV
description: Charge Bearer
example: SLEV example: SLEV
PaymentReturnRequestParams: PaymentReturnRequestParams:
type: object type: object
description: Payment return request data
required: required:
- header - header
- assigner_bic - assigner_bic
- assignee_bic - assignee_bic
- cancellation_id - cancellation_id
- payment_data
- cancellation_reason
- cancelling_party - cancelling_party
- cancellation_reason
- payment_data
properties: properties:
header: header:
$ref: '#/definitions/DocumentHeader' $ref: '#/definitions/DocumentHeader'
assigner_bic: assigner_bic:
type: string type: string
description: Assigner BIC
example: PCTULT21XXX example: PCTULT21XXX
assignee_bic: assignee_bic:
type: string type: string
description: Assignee (BoL) BIC
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.
example: D118100301085772 example: D118100301085772
cancelling_party: cancelling_party:
$ref: '#/definitions/CancellingParty' $ref: '#/definitions/CancellingParty'
...@@ -147,8 +230,60 @@ definitions: ...@@ -147,8 +230,60 @@ definitions:
$ref: '#/definitions/CancellationReason' $ref: '#/definitions/CancellationReason'
payment_data: payment_data:
$ref: '#/definitions/PaymentData' $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: DocumentHeader:
type: object type: object
description: Document header
required: required:
- doc_id - doc_id
- type - type
...@@ -158,21 +293,33 @@ definitions: ...@@ -158,21 +293,33 @@ 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.
example: D118091001045732 example: D118091001045732
type: type:
type: string type: string
enum:
- FFCCTRNS
- FFPCRQST
- PRTRN
- ROINVSTG
description: Document type. Allowed values are FFCCTRNS/FFPCRQST/PRTRN/ROINVSTG
example: FFCCTRNS example: FFCCTRNS
date_time: date_time:
type: string type: string
format: date-time format: date-time
description: Document creation timestamp
example: 2018-10-03T08:48:09
priority: priority:
type: integer type: integer
description: Document priority
example: 51 example: 51
business_area: business_area:
type: string type: string
example: SEAPSCT description: Document business area
example: SEPASCT
PaymentData: PaymentData:
type: object type: object
description: Payment data
required: required:
- instr_id - instr_id
- end_to_end_id - end_to_end_id
...@@ -188,31 +335,46 @@ definitions: ...@@ -188,31 +335,46 @@ definitions:
properties: properties:
instr_id: instr_id:
type: string type: string
description: Instruction identification
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.
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.
example: 8e7070743da24402a7fc290bc62fbcd0 example: 8e7070743da24402a7fc290bc62fbcd0
amount: amount:
type: number type: number
format: double format: double
description: Payment amount
example: 13.31 example: 13.31
currency: currency:
type: string type: string
enum:
- EUR
description: Payment currency
example: EUR example: EUR
date: date:
type: string type: string
description: Payment date. In payment request must be current or next TARGET2 business day.
format: date format: date
mtd: mtd:
type: string type: string
enum:
- CLRG
description: Settlment method
example: CLRG example: CLRG
prtry: prtry:
type: string type: string
description: Clearing system
example: LITAS-MIG example: LITAS-MIG
cd: cd:
type: string type: string
enum:
- SEPA
description: Service level code
example: SEPA example: SEPA
debtor: debtor:
$ref: '#/definitions/Participant' $ref: '#/definitions/Participant'
...@@ -220,22 +382,73 @@ definitions: ...@@ -220,22 +382,73 @@ definitions:
$ref: '#/definitions/Participant' $ref: '#/definitions/Participant'
CancellingParty: CancellingParty:
type: object type: object
description: Cancelling party data. Only one of available properties can be filled.
properties: properties:
customer_name: customer_name:
type: string type: string
description: Customer name or BIC
example: Dan Notestein or PCTULT21XXX example: Dan Notestein or PCTULT21XXX
bank_bic: bank_bic:
type: string type: string
description: Bank BIC
example: PCTULT21XXX example: PCTULT21XXX
CancellationReason: CancellationReason:
type: object type: object
properties: description: Cancellation reason. Only one of available properties can be filled
properties:
iso_code: iso_code:
type: string type: string
enum:
- DUPL
description: ISO code of cancellation reason
example: DUPL example: DUPL
code: code:
type: string 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: Participant:
type: object type: object
required: required:
...@@ -245,24 +458,34 @@ definitions: ...@@ -245,24 +458,34 @@ definitions:
properties: properties:
bic: bic:
type: string type: string
description: Participant;s BIC
example: LIABLT20XXX example: LIABLT20XXX
iban: iban:
type: string type: string
description: Participant's IBAN
example: LT261010000002132402 example: LT261010000002132402
name: name:
type: string type: string
description: Participant's name
example: Dan Notestein example: Dan Notestein
country: country:
type: string type: string
example: LT description: Participant's country ISO 3166-1 alpha-2 code
example: US
address_line1: address_line1:
type: string type: string
description: Participant's address
example: PO Box 10608
address_line2: address_line2:
type: string type: string
description: Participant's address
example: Blacksburg, VA 24062-0608
Response: Response:
type: object type: object
description: API response type for 'output' type endpoints
required: required:
- id - id
- result
properties: properties:
id: id:
type: integer type: integer
...@@ -273,27 +496,40 @@ definitions: ...@@ -273,27 +496,40 @@ definitions:
$ref: '#/definitions/Error' $ref: '#/definitions/Error'
Result: Result:
type: object type: object
description: Operation result
required: required:
- doc_id - doc_id
- status - status
properties: properties:
doc_id: doc_id:
type: string type: string
description: Document ID
example: D118091001045732 example: D118091001045732
status: status:
type: string type: string
enum:
- Accepted
- Error
description: Request status. Available values are Accepted, Error
example: Accepted example: Accepted
Error: Error:
type: object type: object
description: Error object. Only sent if result.status is 'Error'
required: required:
- code - code
- message - message
properties: properties:
code: code:
type: string 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 example: DIS-0001
message: message:
type: string type: string
description: Error message
example: Document with given ID already exists example: Document with given ID already exists
host: localhost host: localhost
basePath: / basePath: /
... ...
......