psd2 apis technical documentation - otp bankaotp bank does accept confidential clients only....

PSD2 APIS TECHNICAL DOCUMENTATION

OTP BANKA SLOVENSKO, A.S.

Version: 2.0

Bratislava, 01.06.2019

PSD2 APIs technical documentation Version 2.0

2

CONTENT

1 USED ABBREVIATIONS ..................................................................................................................4

2 TPP AUTHENTICATION ..................................................................................................................5

3 PSD2 APIS....................................................................................................................................5

3.1 STANDARD HEADER ............................................................................................................................. 5

3.1.1 Request header definition ...................................................................................................... 5

3.1.2 Response header definition .................................................................................................... 6

3.2 ERROR CODES .................................................................................................................................... 7

3.3 ENROLLMENT ..................................................................................................................................... 8

3.3.1 HTTP Request Example ......................................................................................................... 10

3.3.2 HTTP Response Example....................................................................................................... 11

3.4 AUTHORIZATION ............................................................................................................................... 12

3.4.1 HTTP Request Example ......................................................................................................... 13

3.4.2 HTTP Response Example....................................................................................................... 13

3.5 AISP APIS ....................................................................................................................................... 13

3.5.1 Endpoints definition ............................................................................................................. 14

3.5.2 AISP Operation: Account information................................................................................... 14

3.5.3 AISP Operation: Account transactions .................................................................................. 17

3.5.4 AISP Operation: List of accounts........................................................................................... 26

3.5.5 Access token ......................................................................................................................... 29

3.5.6 Refreshing an access token .................................................................................................. 31

3.6 PISP APIS ....................................................................................................................................... 32

3.6.1 Endpoints definition ............................................................................................................. 32

3.6.2 PISP Operation: Standard SEPA payment initialization (XML) .............................................. 33

3.6.3 PISP Operation: Standard payment submission ................................................................... 39


3

3.6.4 PISP Operation: Payment order status ................................................................................. 41

3.6.5 PISP Operation: Standard SEPA payment initialization (JSON) ............................................. 44

3.6.6 PISP Operation: Cancelling of SEPA payment ....................................................................... 48

3.6.7 PISP Operation: International payment initialization ........................................................... 50

3.6.8 PISP Operation: Balance check ............................................................................................. 60

3.6.9 Access token ......................................................................................................................... 60

3.6.10 Code tables ........................................................................................................................... 62

3.7 PIISP APIS ...................................................................................................................................... 63

3.7.1 Endpoint definition ............................................................................................................... 63

3.7.2 PIISP Operation: Balance check ............................................................................................ 63

3.7.3 Access token ......................................................................................................................... 67


4

1 USED ABBREVIATIONS AISP Account information service provider

ASPSP Account Servicing Payment Service Provider

PIISP Payment Instrument Issuer Service Provider

PISP Payment initiation service provider

PSD2 Payment Services Directive 2

PSP Payment service provider

PSU Payment service user

TPP Third party provider


5

2 TPP AUTHENTICATION For the authentication of the TPP as a client, the eIDAS-based site authentication certificate will be used.

The TPP must also be licensed by the National Bank of Slovakia to provide PSD2 services. The certificate

used must be issued in accordance with ETSI TS 119 495 (Qualified Certificate Profiles and TSP Policy

Requirements under the payment services Directive (EU) 2015/2366).

3 PSD2 APIS

3.1 STANDARD HEADER Recommended set of request and response headers for PSD2 endpoints.

3.1.1 REQUEST HEADER DEFINITION

Attribute Optionality Type Description

Host Mandatory String Domain name of the server and optional TCP port number.

Content-

Type

Mandatory String application/json or application/xml

Request-ID Mandatory String A unique identifier of a particular request message. Although it may be

arbitrary string, it is strongly recommended to use a Universally Unique

Identifier (UUID) version 4 form (RFC4122).

Correlation-

ID

Optional String A unique correlation identifier correlates the request and the response

messages as a pair especially useful for audit logs. Although it may be arbitrary

string, it is strongly recommended to use a Universally Unique Identifier

(UUID) version 4 form (RFC4122).

Process-ID Optional String Identifier of a business or technical process to what the set of requests and

response pairs are organized (e.g. paging of transaction history should have

the same Process-ID). Although it may be arbitrary string, it is strongly

recommended to use a Universally Unique Identifier (UUID) version 4 form

(RFC4122).

PSU–IP-

Address

Mandatory String Identifier of a customer’s IP address from which he/she is connected to the

TPP infrastructure. It might be in the format of IPv4 o IPv6 address. ASPSP shall

indicate which values are acceptable.

PSU-

Device-OS

Mandatory String A customer’s device and/or operating system identification from which he/she

is connected to the TPP infrastructure.


6

PSU-User-

Agent

Mandatory String A customer’s web browser of other client device identification from which

he/she is connected to the TPP infrastructure. Agent header field of the http

request between PSU and TPP.

PSU-Geo-

Location

Optional String The GPS coordinates of the current customer’s location in the moment of

connection to the TPP infrastructure.

(Required GPS format: Latitude, Longitude)

PSU-Last-

Logged-

Time

Optional DateTime Last date and time when user was logged to TPP app (RFC3339 format).

PSU-

Presence

Optional Enum The presence status of user (PSU) during an API call. The value of the

parameter could be „true“ (PSU is present) or „false“ (PSU is not present).

HTTP Request header example

Host: api.banka.sk

Content-Type: application/json ;charset=UTF-8

Request-ID: c2c48fc8-1f79-4934-a47b-56d61a28f351

Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b

Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe

PSU-Last-Logged-Time: 2019-02-16T14:54:32+01:00

PSU–IP-Address: 192.168.0.100

PSU-Device-OS: iOS 12.1.4

PSU-User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML,

like Gecko) Chrome/72.0.3626.109 Safari/537.36

PSU-Geo-Location: 48.1569126, 17.119287

PSU-Presence: true

3.1.2 RESPONSE HEADER DEFINITION


7


Content-

Type

Mandatory String application/json or application/xml.

Response-

ID

Mandatory String A unique identifier of a particular request message.

Although it may be arbitrary string, it is strongly recommended to use a Universally

Unique Identifier (UUID) version 4 form (RFC4122).

Correlation-

ID

Optional String A unique correlation identifier correlates the request and the response messages as

a pair especially useful for audit logs.



Process-ID Optional String Identifier of a business or technical process to what the set of requests and

response pairs are organized (e.g. paging of transaction history should have same

Process-ID).



HTTP Response header example

Content-Type: application/json;charset=UTF-8

Response-ID: ac30869e-29e2-40f7-83fb-ed1c6bdde216



3.2 ERROR CODES

HTTP Status Error code Popis

400 parameter_missing Mandatory parameter is missing.

400 parameter_invalid Value of input parameter is not valid.

500, 503 server_error Authorization server error.


8

Rest of HTTP Status codes and error codes are defined according to RFC 6749, Section 5.2.

https://tools.ietf.org/html/rfc6749#section-5.2

3.3 ENROLLMENT By calling this resource, a TPP can request the automatic assignment of client_id and client_secret.

The output is client_id and client_secret, which the TPP needs to get access and refresh token.

Endpoint: POST https://api.otpbanka.sk/otp-psd2-gw/enroll

Request:


redirect_uris Mandatory Array of

strings e.g.

URL

[Max 3x

2047 B]

A list of URLs to which the authentication flow is redirected at the

end. The authorization request must contain just one of these

registered URIs in the exact format.

client_name Mandatory String

[Max 255 B]

TPP application name.

client_type Mandatory String OAuth defines two client types, based on their ability to

authenticate securely with the authorization server

(Confidential/Public).

OTP Bank does accept confidential clients only.

client_name#en-

US

Optional String

[Max 1024 B]

TPP name in the appropriate language / encoding.

logo_uri Optional URI

[Max 2047 B]

Application logo URI (or where to download it at registration).

https://tools.ietf.org/html/rfc6749#section-5.2


9

contacts Mandatory Array of

strings e-

mail

[Max 10x

255 B]

E-mails as a contact to a responsible person on the TPP side.

scopes Optional Array of

strings

[Max 10x

255 B]

Array of the required scopes by application. At registration, scopes

are validated against the content of the certificate used.

licence_number Mandatory String

[Max

1024 B]

Licence number obtained from national regulator.

Response:


client_id Mandatory String The client_id assigned to the application. This ID starts the

authentication process and the communication process

when replacing the code and refresh_token.

client_secret Mandatory String The client_secret - password / token issued by the ASPSP for

the application (client_id) of the TPP.

client_secret_expires_at Optional DateTime The default value is 0 (client_id never expires). Otherwise,

the value is in seconds from 1970-01-01T0: 0: 0Z.

api_key Optional String The API key that the application uses to communicate with

the OTP Bank's API. If API does not support API keys, it

returns "NOT_PROVIDED".

redirect_uris Mandatory Array of

strings e.g.

URL

[Max 3x

2047 B]

A list of URLs to which the authentication flow is redirected

at the end. The authorization request must contain just one

of these registered URIs in the exact format.


10

client_name Mandatory String

[Max 255 B]

TPP application name.

client_name#en-US Optional String

[Max 1024

B]

TPP name in the appropriate language / encoding.

client_type Mandatory String OAuth defines two client types, based on their ability to

authenticate securely with the authorization server

(Confidential/Public). OTP Bank does accept confidential

clients only.

logo_uri Optional URI

[Max 2047

B]

Application logo URI (or where to download it at

registration).

contacts Mandatory Array of

strings e-

mail

[Max 10x

255 B]

E-mails as a contact to a responsible person on the TPP side.

scopes Optional Array of

strings

[Max 10x

255 B]

Array of the required scopes by application. At registration,

scopes are validated against the content of the certificate

used.

licence_number Mandatory String

[Max 1024

B]

Licence number obtain by national regulator.

3.3.1 HTTP REQUEST EXAMPLE POST /enroll HTTP/1.1

Host: api.banka.sk


{


11

"redirect_uris":

["https://www.example.pay.sk/start",

"https://www.example.pay.sk/start2"],

"client_name": "Moj platobny portal",

"client_name#en-US": "My payment portal",

"client_type": "confidential",

"logo_uri": "https://www.example.pay.sk/logo.png",

"contacts": ["[email protected]"],

"scopes": ["AISP", "PISP"],

"licence_number": "30813182"

}

3.3.2 HTTP RESPONSE EXAMPLE HTTP/1.1 201 Created


Cache-Control: no-store

Pragma: no-cache

{

"client_id": "a0b25291f0",

"client_secret":"AAjkk45suiyui564568712_4555g5g5g5gg",

"client_secret_expires_at": 0,

"api_key": "00000000-1212-0f0f-a0a0-123456789abc",

"redirect_uris":

["https://www.myexample.pay.sk/start",

"https://www.myexample.pay.sk/start2"],

"client_name": "Moj platobny portal",

"client_name#en-US": "My payment portal",

"logo_uri": "https://www.example.pay.sk/logo.png",

"contacts": ["[email protected]"],

"scopes": ["AISP", "PISP"],

https://www.example.pay.sk/start%22

https://www.example.pay.sk/start2%22

https://www.example.pay.sk/logo.png%22

https://www.myexample.pay.sk/start%22

https://www.myexample.pay.sk/start2%22

https://www.example.pay.sk/logo.png%22


12

"client_type": "confidential",

"licence_number": "30813182"

}

3.4 AUTHORIZATION The TPP (AISP/PISP) creates an Authorization request for the PSU to consent to the AISP/PISP request.

The request is an Oauth 2.0. Authorization Code Grant.

Endpoint: https://api.otpbanka.sk/otp-psd2-gw/auth/authorize

Request:


response_type Mandatory Code Mandatory parameter. Specifies the authentication flow used,

in this case, a code grant. For the authentication process, this

means that, as a result of a successful identification and

authentication, a one-time auth_code is expected instead

of access_token.

client_id Mandatory String Unique TPP application identifier issued by the ASPSP.

redirect_uri Mandatory URL The URL to which the authentication flow is redirected at the

end. This URL is set when client_id is issued, and this parameter

is validated against the URL introduced to client_id in the

ASPSP. The value should match one of the values introduced

using registration.

scope Mandatory String Space separated string of attributes of the application required

scope.

login_hint Optional User

identification

for

automation

Hint to the Authorization Server about the login identifier the

End-User might use to log in (http://openid.net/specs/openid-

connect-core-1_0.html).

state Mandatory Random

string [min

128 bits]

With this parameter, TPP needs to enrich redirect_uri when

redirecting. It protects against CSRF attacks and passes

information from the application through authentication flow.

Requested CSRF token length is min. 128 bits.

http://openid.net/specs/openid-connect-core-1_0.html

http://openid.net/specs/openid-connect-core-1_0.html


13

Response:


code Mandatory String Authorization code.

state Mandatory String Attribute state from TPP request.

3.4.1 HTTP REQUEST EXAMPLE GET /authorize HTTP/1.1

Host: api.banka.sk

Content-Type: application/x-www-form-urlencoded

response_type=code&

scope=AISP&

client_id=CLIENT_ID&

state=STATE&

redirect_uri=https://www.myexample.pay.sk/start&

login_hint=USER_ID

3.4.2 HTTP RESPONSE EXAMPLE HTTP/1.1 303 See Other

content-type: application/x-www-form-urlencoded

location: https://www.myexample.pay.sk/start?

code=AUTH_CODE&

state=STATE

3.5 AISP APIS This chapter defines the list of methods provided for AISP.

Prerequisites:

• The TPP is registered for the AISP role and valid AISP scope.

• The TPP has been successfully checked and authenticated.

• The TPP has presented its "OAuth2 Authorization Code Grant" access token which allows the OTB

Bank to identify the relevant PSU.


14

3.5.1 ENDPOINTS DEFINITION

Endpoint Method Description

https://api.otpbanka.sk/otp-

psd2-

gw/api/v1/accounts/information

POST Account information – service provides information and balances related to

an account.


psd2-

gw/api/v1/accounts/transactions

POST Account transactions – service provides list of transactions in defined date

range related to an account.


psd2-gw/api/v2/accounts

GET List of accounts – service returns the list of accounts to which the client has

given a long-term consent to specific TPP (not a list of all client accounts)

without balances.

The TPP can execute a maximum of 4 AISP requests per IBAN without SCA within 24 hours (excluding the

list of accounts). Subsequently, SCA must be executed.

The number of possible AISP requests without SCA will be reset after SCA or after 24 hours (it depends on

which action occurs earlier).

3.5.2 AISP OPERATION: ACCOUNT INFORMATION The operation provides the relevant data about PSU account identified by IBAN and two types of account

balances.

Format: JSON

Request:

Attributes structure Optionality Type Description

Level 1

iban Mandatory String [34] International Bank Account Number (IBAN)

Response:


15


Level 1 Level 2 Level 3

account name Mandatory String [70] Account name - usually client name

account productName Optional String [70] Product name - commercial product

designation

account type Optional Enum Account type is enumeration: ISO

20022 - Cash Account Type Code e.g.

(CACC - Current account)

account baseCurrency Mandatory String [3] Account currency (currency code

according to ISO 4217 - 3 capital

letters)

balances typeCodeOrProprietary Mandatory Enum Balance type is enumeration: ISO 20022

- Balance Type Code. Following

balances mandatory are published:

- ITBD (Interim booked balance)

- ITAV (Interim available balance)

balances amount value Mandatory Number

Float [12.2]

Balance amount. Numeric value of the

amount as a fractional number. The

fractional part has a maximum of two

digits

balances amount currency Mandatory String [3] Balance currency (currency code

according to ISO 4217 - 3 capital

letters)

balances creditDebitIndicator Mandatory Enum Credit/Debit indicator is enumeration:

- CRDT (Credit)

- DBIT (Debit)

balances dateTime Mandatory DateTime Timestamp of balances (official

local date and time of Slovak republic

in RFC 3339 format)

3.5.2.1 HTTP Request Example

Header:


16

POST /api/v1/accounts/information HTTP/1.1

Host: api.banka.sk


Authorization:Bearer IDWJJBCHQ5DZJWEMO7ZWM4DLYWOFWKXX







PSU-User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36

(KHTML, like Gecko) Chrome/72.0.3626.109 Safari/537.36

PSU-Geo-Location: 48.1569126, 17.119287

PSU-Presence: true

Body:

{

"iban": "SK0252009999930000000107"

}

3.5.2.2 HTTP Response Example

Header

HTTP/1.1 200 OK


Response-ID: 7deb90a9-9900-4c90-a91c-3ecc888c2c88



Body

{

"account": {


17

"name": "John Doe",

"productName": "BestAccount",

"type": "CACC",

"baseCurrency": "EUR"

},

"balances": [

{

"typeCodeOrProprietary": "ITBD",

"amount": {

"value": 1234.56,

"currency": "EUR"

},

"creditDebitIndicator": "CRDT",

"dateTime": "2019-02-15T17:18:45.727Z"

},

{

"typeCodeOrProprietary": " ITAV ",

"amount": {

"value": 1214.06,

"currency": "EUR"

},


"dateTime": "2019-02-15T17:18:45.727Z"

}

]

}

3.5.3 AISP OPERATION: ACCOUNT TRANSACTIONS The operation provides the list of financial transactions performed on a customer’s bank account within

a date period. Transactions will be ordered from the most recent to the oldest.

Format: JSON


18

Request:

Attributes

structure

Optionality Type Description

Level 1

iban Mandatory String

[34]

International Bank Account Number (IBAN).

dateFrom Optional Date The starting date of a date period for transaction history. Default value is

actual day.

dateTo Optional Date The end date of a date period for transaction history. OTP Bank has to

support transaction history for at least 13 months. Default value is actual

day.

pageSize Optional Integer The number of records included in one page for displaying. Default value

is 50 records. OTP Bank has to support maximum 100 records on page.

page Optional Integer The sequence number of a page in regards to page size for a record set.

Because it starts at number 0, it should be considered as an offset from

the beginning from a page set. Default value is 0.

status Optional Enum Transaction status indicator is enumeration:

- BOOK (booked transactions)

- INFO (settled transactions)

- ALL (all transactions)

Default value is ALL

Response:

Attributes structure Option

ality

Type Description

Level 0 Level 1 Level 2 Level 3 Level 4

pageCo

unt

Option

al

Num

ber

Number of

pages in the


19

selected

range

transac

tions

amount value Manda

tory

Num

ber

Float

[12.2

]

Transaction

amount

value in

account

currency.

Numeric

value of the

amount as a

fractional

number.

amount currency Manda

tory

Strin

g [3]

Transaction

amount

currency.

Formated in

Alphabetic

codes from

ISO 4712.

creditDebitInd

icator

Manda

tory

Enu

m

Credit/Debit

indicator is

enumeration:

- CRDT

(Credit)

- DBIT (Debit)

status Manda

tory

Enu

m

The status of

a transaction,

related to the

query

parameter

'transactionSt

atus'.

Transaction

status

indicator is

enumeration:

- BOOK

(booked

transactions)

- INFO

(settled trans

actions)

For OTP Bank

only "INFO"

value is

relevant.


20

bookingDate Manda

tory

for

booke

d tnx.

Date Transaction

booking

date. The

date of the

execustion of

the

transaction.

valueDate Manda

tory

Date Transaction

value

date. The

requested

date by a

bank

customer to

execute the

transaction.

bankTransacti

onCode

Option

al

Strin

g

[11]

The category

code of the

transaction

type from the

SBA's code

list.

transactionDe

tails

references endToEndIdent

ification

Manda

tory in

case

this

attribu

te is

provid

ed by

client

Strin

g

[35]

Unique

identification

defined by a

requestor.

transactionDe

tails

references chequeNumber Option

al

Strin

g

[35]

For card

transactions,

this is the

card number

in format

**** ****

**** 1111

transactionDe

tails

relatedParties debtor name Option

al

Strin

g

[140]

Name of the

debtor


21

transactionDe

tails

relatedParties debtorAccount identification Option

al

Strin

g

[34]

Unique

identification

of the debtor

account,

usually IBAN.

transactionDe

tails

relatedParties creditor name Option

al

Strin

g

[140]

Name of the

creditor

transactionDe

tails

relatedParties creditorAccoun

t

identification Option

al

Strin

g

[34]

Unique

identification

of

the creditor

account,

usually IBAN.

transactionDe

tails

relatedParties tradingParty name Option

al

Strin

g

[140]

Name of a

third party.

For card

transaction,

this is the

name of

merchant.

transactionDe

tails

relatedAgents debtorAgent financialInstitutionId

entification

Option

al

Strin

g

[11]

Correspondin

g

identification

of a debtor

bank managin

g the

account,

usually Bank

Identification

Code (BIC).

transactionDe

tails

relatedAgents creditorAgent financialInstitutionId

entification

Option

al

Strin

g

[11]

Correspondin

g

identification

of a creditor

bank managin

g the

account,

usually Bank

Identification

Code (BIC).


22

transactionDe

tails

remittanceInformatio

n

Manda

tory in

case

this

attribu

te is

provid

ed by

client

Strin

g

[140]

The text

aimed as the

information

for a receiver

of the

transaction.

transactionDe

tails

additionalTransaction

Information

Option

al

Strin

g

[140]

Bank

transaction

description.


Header:

POST /api/v1/accounts/transactions HTTP/1.1

Host: api.banka.sk











PSU-Geo-Location: 48.1569126, 17.119287

PSU-Presence: false

Body:

{

"iban": "SK0252009999930000000107",


23

"status": "ALL",

"dateFrom": "2019-02-09",

"dateTo": "2019-02-18",

"pageSize": 50,

"page": 0

}


Header:

HTTP/1.1 200 OK





Body:

{

"pageCount": 1,

"transactions": [{

"amount": {

"value": 1,

"currency": "EUR"

},

"creditDebitIndicator": "DBIT",

"status": "INFO",

"bookingDate": "2019-02-15",

"valueDate": "2019-02-15",

"transactionDetails": {

"remittanceInformation": "SERVICE FEES"

}

},


24

{

"amount": {

"value": 7.7,

"currency": "EUR"

},


"status": "INFO",

"bookingDate": "2019-02-15",

"valueDate": "2019-02-15",


"relatedParties": {

"debtorAccount": {

"identification": "SK0252009999930000000107"

},

"creditorAccount": {

"identification": "SK7752009999930000000115"

}

},

"relatedAgents": {

"debtorAgent": {

"financialInstitutionIdentification": "OTPVSKBX"

},

"creditAgent": {

"financialInstitutionIdentification": "OTPVSKBXXXX"

}

},

"remittanceInformation": "príkaz na úhradu"

}

},

{


25

"amount": {

"value": 1,

"currency": "EUR"

},


"status": "INFO",

"bookingDate": "2019-02-14",

"valueDate": "2019-02-14",



}

},

{

"amount": {

"value": 1,

"currency": "EUR"

},


"status": "INFO",

"bookingDate": "2019-02-14",

"valueDate": "2019-02-14",



}

},

{

"amount": {

"value": 1,

"currency": "EUR"

},


26


"status": "INFO",

"bookingDate": "2019-02-14",

"valueDate": "2019-02-14",



}

}

]

}

3.5.4 AISP OPERATION: LIST OF ACCOUNTS The operation provides the list of accounts to which the client has given a long-term consent to specific

TPP (not a list of all client accounts) without balances.

Format: JSON

Request:

Empty payload.

Response:


27

Attributes sturcture Optionality Type Description


creationDateTime Mandatory DateTime The date and

time in RFC3339

format at which a

particular action

has been requested

or executed.

accounts identification iban Mandatory String International Bank

Account Number

(IBAN)

accounts name Mandatory String

[70]

Account name -

usually client name

accounts productName Optional String

[70]

Product name -

commercial

product designation

accounts type Optional Enum Account type is

enumeration: ISO

20022 - Cash

Account Type Code

e.g. (CACC - Current

account)

accounts baseCurrency Mandatory String [3] Account

currency (currency

code according to

ISO 4217 - 3 capital

letters)

accounts servicer financialInstitutionIdentification Mandatory String

[11]

Corresponding

identification of

OTP Bank - Bank

Identification

Code (BIC).


28

accounts scope Mandatory Array

[String]

Attribute contains

set of particular

account scopes for

TPP.

Formatted as array

of following

enumerations:

AISP, PISP, PIISP.


Header:

GET /api/v2/accounts HTTP/1.1

Host: api.banka.sk






PSU-Last-Logged-Time: 2019-02-16T14:54:32+01:00PSU–IP-Address: 192.168.0.100




PSU-Geo-Location: 48.1569126, 17.119287

PSU-Presence: false

Body:

{

}


Header:


29

HTTP/1.1 200 OK





Body:

{

"creationDateTime": "2019-02-16T14:54:32+01:00",

"accounts": [

{

"identification": {

"iban": "SK0252009999930000000107"

},

"name": "John Doe",

"productName": "BestAccount",

"type": "CACC",

"baseCurrency": "EUR",

"servicer": {

"financialInstitutionIdentification": "OTPVSKBXXXX"

},

"scope": ["AISP", "PISP"]

}

]

}

3.5.5 ACCESS TOKEN Service to obtain an Access Token from the ASPSP using the Authorization Code.

Endpoint: POST https://api.otpbanka.sk/otp-psd2-gw/auth/token


30

Request:


grant_type Mandatory String Under the existing OAuth2 definition, this value will be the authorization_code if the

TPP requested refresh_token.

code Mandatory String The authorization code received from the authorization server.

redirect_uri Mandatory URL The redirect URL matches the URL passed in the authentication request.

client_id Mandatory String The client_id assigned to the application in the enrollment process.

Response:


scope Optional String List of permissions separated by the space for which the token is issued.

access_token Mandatory String Short-term (e.g. 3600 seconds, in some cases, one-time) token, which can be

reissued using refresh_token. This token serves to authorize TPP request on

ASPSP API.

token_type Mandatory String Type of token „Bearer“

expires_in Mandatory Number The remaining time to expiration of access_token - in seconds.

refresh_token Optional String Long-term token (e.g. 100 days) issued as a replacement

for authorization_code.

3.5.5.1 HTTP Request Example POST /token HTTP/1.1

Host: api.banka.sk


Authorization: Basic BASE64(CLIENT_ID + ":" + CLIENT_SECRET)

grant_type=authorization_code& code=AUTH_CODE& client_id=tpp&

redirect_uri=REDIRECT_URI& //[https://www.mymultipay.sk/start]

https://www.mymultipay.sk/start%5D


31

3.5.5.2 HTTP Response Example HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8

{

"scope": "AISP",

"access_token": "at_A7ZDPnuFLe9F90rPxL-u7oZUFioaCm8CVNh88zWl",

"token_type": "Bearer",

"expires_in": 7199,

"refresh_token": "rt_DxCYMdboCT9G0SWuDTM-xRwlqCZS_9xsOdsdrP30"

}

3.5.6 REFRESHING AN ACCESS TOKEN Endpoint: POST https://api.otpbanka.sk/otp-psd2-gw/auth/token

Request:


grant_type Mandatory String Value MUST be set to "refresh_token".

refresh_token Mandatory String The refresh token issued to the client.


Response:



access_token Mandatory String Short-term (e.g. 3600 seconds, in some cases, one-time) token, which can be

reissued using refresh_token. This token serves to authorize TPP request on

ASPSP API.



32



Host: api.banka.sk


Authorization: Basic BASE64(CLIENT_ID + ":" + CLIENT_SECRET) grant_type=refresh_token&

refreshToken=rt_DxCYMdboCT9G0SWuDTM-xRwlqCZS_9xsOdsdrP30&scope=AISP

3.5.6.2 HTTP Response Example HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8

{

"scope": "AISP",

"access_token": "at_7sCr8Db6h_ufmQR63TZI1CEbEjk6LH6Z8T_80HjB",

"token_type": "Bearer",

"expires_in": 7199

}

3.6 PISP APIS Chapter defines list of services provided for PISP.

Prerequisites:

• The TPP is registered for the PISP role and valid PISP scope

• The TPP has been successfully authenticated

• The TPP has presented its access token to call PISP services.

3.6.1 ENDPOINTS DEFINITION

Endpoints Method Description

https://api.otpbanka.sk/otp-psd2-

gw/api/v1/payments/standard/iso

POST Standard SEPA payment initialization – service allows to initialize

payment in XML format (PAIN.001.001.03)


gw/api/v1/payments/submission

POST Standard payment submission – service allows the authorization of

initialized payment


gw/api/v1/payments/{orderId}/status

GET Payment order status – service provides actual information about

initialized payment


33


gw/api/v2/payments/standard/sba

POST Standard SEPA payment initialization – service allows to initialize

payment in JSON format


gw/api/v1/payments/{orderId}/rcp

DELETE Cancelling of SEPA payment - service allows cancelling of initialized

SEPA payment or submitted future-dated SEPA payment


gw/api/v1/payments/swift/iso

POST International payment initialization - service allows to initialize

payment in XML format (PAIN.001.001.03)


gw/api/v1/accounts/balanceCheck

POST Balance check – service provides information about sufficient

balance with the yes/no answer

3.6.2 PISP OPERATION: STANDARD SEPA PAYMENT INITIALIZATION (XML) The operation allows to initialize payment in XML format (PAIN.001.001.03). The PISP sends a ISO20022

pain.001 based structure that specifies the payment activation request that is related to a commercial

transaction between a PSU and the merchant.

Format: XML

Request:

Cut off time: 21:00 (requests sent between 21:00 and 0:00 end up with error code 400).

The maximum payment amount from an account in a foreign currency is max. 2999,99 EUR. If the

condition is not met, the payment will be rejected.

Message contains xml: pain.001.001.03

Link to message definition:

https://www.iso20022.org/documents/general/Payments_Maintenance_2009.zip

Link to message examples:

https://www.iso20022.org/documents/messages/pain/instances/pain.001.001.03.zip

Allowed characters for attributes <CstmrCdtTrfInitn.PmtInf.Dbtr.Nm>,

<CstmrCdtTrfInitn.PmtInf.CdtTrfTxInf.Cdtr.Nm>,

<CstmrCdtTrfInitn.PmtInf.CdtTrfTxInf.PmtId.EndToEndId>,

<CstmrCdtTrfInitn.PmtInf.CdtTrfTxInf.RmtInf.Ustrd>, <CstmrCdtTrfInitn.PmtInf.CdtTrfTxInf.RmtInf.Strd>:

• The first character must be only from the set: a-z, A-Z, 0-9, Á á É é Í í Ó ó Ú ú Ý ý Ä ä Ě ě Ô ô Ĺ ĺ Ŕ ŕ

Č č Ď ď Ľ ľ Ň ň Ř ř Š š Ť ť Ž ž $ @ ! % . : - _ [ ] } ? ) + ´ ,

https://www.iso20022.org/documents/general/Payments_Maintenance_2009.zip

https://www.iso20022.org/documents/messages/pain/instances/pain.001.001.03.zip


34

• Other characters must be from the set: a-z, A-Z, 0-9, Á á É é Í í Ó ó Ú ú Ý ý Ä ä Ě ě Ô ô Ĺ ĺ Ŕ ŕ Č č Ď ď

Ľ ľ Ň ň Ř ř Š š Ť ť Ž ž $ @ ! % . : - _ [ ] } ? ) + ´ , and space

• The maximum string length for the attribute <CstmrCdtTrfInitn.PmtInf.CdtTrfTxInf.Cdtr.Nm>

specific for OTP Bank: 32 characters

• If the <CstmrCdtTrfInitn.PmtInf.CdtTrfTxInf.PmtId.EndToEndId> attribute is

in /VS1234567890/SS1234567890/KS0308 format, the "/" character is allowed

Response:

Attribute XML structure

mapping


orderId TxInfAndSts/AcctSvcrRef Mandatory String

[35]

OrderId is Unique reference, as assigned by

the account servicing institution, to

unambiguously identify the instruction.

status TxInfAndSts/TxSts Mandatory Enum Transaction status indicator is enumeration:

- ACTC (AcceptedTechnicalValidation)

- ACWC (AcceptedWithChange)

- RJCT (Rejected)

reasonCode TxInfAndSts/StsRsnInf/Rsn Optional Enum ISO 20022 Rejected Status Reason Code

statusDateTime GrpHdr/CreDtTm Optional DateTime Transaction entry date. The date of receiving

the transaction in a bank.


Header:

POST /api/v1/payments/standard/iso HTTP/1.1

Host: api.banka.sk

Content-Type: application/xml;charset=UTF-8

Authorization: Bearer IDWJJBCHQ5DZJWEMO7ZWM4DLYWOFWKXX




35







PSU-Geo-Location: 48.145745, 17.116062

PSU-Presence: true

Body:

<?xml version="1.0" encoding="UTF-8"?>

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03">

<CstmrCdtTrfInitn>

<GrpHdr>

<MsgId>MCCT1708164657382965</MsgId>

<CredDtTm>2019-02-16T14:08:36</CredDtTm>

<NbOfTxs>1</NbOfTxs>

<CtrlSum>1.75</CtrlSum>

<InitgPty>

<Nm>Company, a.s.</Nm>

<Id>

<OrgId>

<Othr>

<Id>ffdc2f2d-1288-4212-be38-

a011838ee051</Id>

</Othr>

</OrgId>

</Id>

</InitgPty>

</GrpHdr>


36

<PmtInf>

<PmtInfId>17081600001</PmtInfId>

<PmtMtd>TRF</PmtMtd>

<PmtTpInf>

<InstrPrty>NORM</InstrPrty>

<SvcLvl>

<Cd>NURG</Cd>

</SvcLvl>

<CtgyPurp>

<Cd>SEPA</Cd>

</CtgyPurp>

</PmtTpInf>

<ReqdExctnDt>2019-02-16</ReqdExctnDt>

<Dbtr>

<Nm>Firm, a.s.</Nm>

<Id>

<OrgId>

<Othr>

<Id>123456</Id>

</Othr>

</OrgId>

</Id>

</Dbtr>

<DbtrAcct>

<Id>

<Iban>SK5852009999930000000166</Iban>

</Id>

<Issr>Issuer</Issr>

</DbtrAcct>

<DbtrAgt>


37

<FinInstnId />

</DbtrAgt>

<ChrgBr>SLEV</ChrgBr>

<CdtTrfTx>

<PmtId>

<InstrId>MCCT170816000005</InstrId>

<EndToEndId>NOTPROVIDED</EndToEndId>

</PmtId>

<Amt>

<InstdAmt>1.75</InstdAmt>

<Ccy>EUR</Ccy>

</Amt>

<CdtrAgt>

<FinInstnId>

<BIC>NOTPROVIDED</BIC>

</FinInstnId>

</CdtrAgt>

<Cdtr>

<Nm>NOTPROVIDED</Nm>

<Id>

<OrgId>

<Othr>

<Id>NOTPROVIDED</Id>

</Othr>

</OrgId>

</Id>

</Cdtr>

<CdtrAcct>

<Id>

<Iban>SK8952009999930000000190</Iban>


38

</Id>

<Issr>Issuer</Issr>

</CdtrAcct>

<UltmtCdtr>

<Nm>Fero Skrutka</Nm>

<Id>

<OrgId>

<Othr>

<Id>654321</Id>

</Othr>

</OrgId>

</Id>

</UltmtCdtr>

<Purp>

<Cd>ACCT</Cd>

</Purp>

<RmtInf>

<Ustrd>Payment for the goods</Ustrd>

</RmtInf>

</CdtTrfTx>

</PmtInf>

</CstmrCdtTrfInitn>

</Document>


Header:

HTTP/1.1 200 OK






39

Body:


<Document>

<CstmrPmtStsRpt>

<GrpHdr>

<MsgId>8b4265e6-45a5-4755-b8ce-a3d374067cd</MsgId>

<CreDtTm>2019-02-14T12:12:12</CreDtTm>

</GrpHdr>

<OrgnlGrpInfAndSts>

<OrgnlMsgId>8b4265e6-45a5-4755-b8ce-a3d374067cd</OrgnlMsgId>

<OrgnlMsgNmId />

</OrgnlGrpInfAndSts>

<OrgnlPmtInfAndSts>

<TxInfAndSts>

<TxSts>ACTC</TxSts>

<StsRsnInf>

<Rsn />

</StsRsnInf>

<AcctSvcrRef>PAYMENT_tr_uSmwffUaB-gLCB3z-mC6iBcP0BOwj76d7UlfB-

mr</AcctSvcrRef>

</TxInfAndSts>

</OrgnlPmtInfAndSts>

</CstmrPmtStsRpt>

</Document>

3.6.3 PISP OPERATION: STANDARD PAYMENT SUBMISSION The operation provides authorization of initialized payment.

Format: JSON


40

Request:

The authorization header will contain a "bearer token" that corresponds to "payment order".

Response:

Attributes

structure


Level 1

orderId Mandatory String

[35]

OrderId is Unique reference, as assigned by the account servicing

institution, to unambiguously identify the instruction.

status Mandatory Enum Transaction status indicator is enumeration:



- RJCT (Rejected)

reasonCode Optional Enum ISO 20022 Rejected Status Reason Code

statusDateTime Mandatory DateTime The date and time in RFC3339 format at which a particular action has

been requested or executed.


Header:

POST /api/v1/payments/submission HTTP/1.1

Host: api.banka.sk


Authorization: Bearer 1VVKPKO9IJUBFFXUKLW8JDVWM3B5XUBG






41





PSU-Geo-Location: 48.145745, 17.116062

PSU-Presence: true

Body:

{

"orderId":"ffdc2f2d-1288-4212-be38-a011838ee051"

}


Header:

HTTP/1.1 200 OK





Body:

{

"orderId":"ffdc2f2d-1288-4212-be38-a011838ee051",

"status":"ACSC",

"statusDateTime":"2019-02-16T12:02:12+01:00"

}

3.6.4 PISP OPERATION: PAYMENT ORDER STATUS The operation provides information about processing status of a received payment instruction based on

payment orderId identification.

Format: JSON


42

Request:

Empty payload.

Response:

Attributes

structure


Level 1


[35]






- RJCT (Rejected)

- PDNG (Pending)

- ACSP (AcceptedSettlementInProcess)

- ACSC (AcceptedSettlementCompleted)





Header:

GET /api/v1/payments/ffdc2f2d-1288-4212-be38-a011838ee051/status HTTP/1.1

Host: api.banka.sk





43








PSU-Geo-Location: 48.145745, 17.116062

PSU-Presence: false

Body:

{

}


Header:

HTTP/1.1 200 OK





Body:

{

"orderId":"ffdc2f2d-1288-4212-be38-a011838ee051",

"status": "RJCT",

"reasonCode": "AM21",

"statusDateTime": "2019-02-18T09:59:27+01:00"

}


44

3.6.5 PISP OPERATION: STANDARD SEPA PAYMENT INITIALIZATION (JSON) The operation allows to initialize payment in JSON format.

Format: JSON

Request:

Cut off time: 21:00 (requests sent between 21:00 and 0:00 end up with error code 400).


Level 1 Level 2

instructionIdentification Mandatory String [200] Technical identification of the payment generated

by a PISP (or PSU).

creationDateTime Optional DateTime The date and time in RFC3339 format at which a

particular action has been requested or executed.

debtor name Mandatory String [70] Debtor name (first name and surname in case of

individual persons or company name)

See allowed characters mentioned below.

debtor iban Mandatory String [34] Debtor account International Bank Account

Number (IBAN)

creditor name Mandatory String [32] Creditor name (first name and surname in case of

individual persons or company name)


creditor iban Mandatory String [34] Creditor account International Bank Account

Number (IBAN)

instructedAmount value Mandatory Number

Float [12.2]

Transaction amount value in account currency.

Numeric value of the amount as a fractional

number. The fractional part has a maximum of

two digits.


45

The maximum payment amount from an account

in a foreign currency is max. 2999,99 EUR. If the

condition is not met, the payment will be rejected.

instructedAmount currency Mandatory String [3] Transaction amount currency. Formated in

Alphabetic codes from ISO 4712.

requestedExecutionDate Mandatory Date Expected execution date

The due date can be up to 3 months in the future

endToEndIdentification Optional String [35] Unique identification defined by a requestor

(PSU).


remittanceInformation Optional String [140] The text aimed as the information for a receiver of

the transaction.


purposeCode Optional String [4] If the purposeCode is set to „RINP“, the payment

request will have the character of recurring

payments.

Allowed characters for attributes <debtor.name>, <creditor.name>, <endToEndIdentification>,

<remittanceInformation>:

• The first character must be only from the set: a-z, A-Z, 0-9, Á á É é Í í Ó ó Ú ú Ý ý Ä ä Ě ě Ô ô Ĺ ĺ Ŕ ŕ

Č č Ď ď Ľ ľ Ň ň Ř ř Š š Ť ť Ž ž $ @ ! % . : - _ [ ] } ? ) + ´ ,

• Other characters must be from the set: a-z, A-Z, 0-9, Á á É é Í í Ó ó Ú ú Ý ý Ä ä Ě ě Ô ô Ĺ ĺ Ŕ ŕ Č č Ď ď

Ľ ľ Ň ň Ř ř Š š Ť ť Ž ž $ @ ! % . : - _ [ ] } ? ) + ´ , and space

• if the <endToEndIdentification> attribute is in /VS1234567890/SS1234567890/KS0308 format,

the "/" character is allowed

Response:

Attributes

structure


Level 1


46


[35]






- RJCT (Rejected)

- PDNG (Pending)

- ACSP (AcceptedSettlementInProcess)

- ACSC (AcceptedSettlementCompleted)




request Optional String Signed JWT - security mitigation for unauthorized payment request

changes


Header:

POST /api/v2/payments/standard/sba HTTP/1.1

Host: api.banka.sk










47



PSU-Geo-Location: 48.145745, 17.116062

PSU-Presence: true

Body:

{

"instructionIdentification": "9b766084-57de-48b2-be53-1bd2804ae0b7",


"debtor": {

"name": "John Doe",

"iban": "SK5852009999930000000166"

},

"creditor": {

"name": "John Doe",

"iban": "SK8952009999930000000190"

},

"instructedAmount": {

"value": 1234.56,

"currency": "EUR"

},

"endToEndIdentification": "/VS123/SS456/KS0308",

"remittanceInformation": "Payment for a utility service.",

"requestedExecutionDate": "2019-02-18",

"purposeCode": "RINP"

}


Header:

Content-Type: application/json



48



Body:

{

"orderId": "ffdc2f2d-1288-4212-be38-a011838ee051",

"status": "RJCT",

"reasonCode": "AM21",

"statusDateTime": "2019-02-16T11:59:27+01:00"

}

3.6.6 PISP OPERATION: CANCELLING OF SEPA PAYMENT The operation allows cancelling of initialized SEPA payment or submitted future-dated SEPA payment.

Format: JSON

Request:

No input.

Response:

In case of a successful payment cancellation, the result is HTTP status 200.

Attributes

structure



[35]

OrderId is Unique reference (different from the payment order_ID), as

assigned by the account servicing institution, to unambiguously identify the

instruction.

Error codes:

Error code Description


49

exception.order.id.notFound Nonexistent orderId

exception.order.id.unableToCancel The due date of SEPA payment is current date

exception.order.id.notSepa Payment is not a SEPA payment

exception.order.id.alreadyCanceled SEPA payment has already been canceled


Header:

DELETE api/v1/payments/aichz8i8z4c2ynabqtkymddhx2raw29zrzj/rcp HTTP/1.1

Host: api.banka.sk











PSU-Geo-Location: 48.1569126, 17.119287

PSU-Presence: true


Header:

HTTP/1.1 200 OK


Response-ID: 71ac4012-e21d-421b-b776-988564f1fbb4



50


Body:

{

"orderId": "6j74qbrt7bufixd2yw6jr3kgbvb7yd3dizf"

}

3.6.7 PISP OPERATION: INTERNATIONAL PAYMENT INITIALIZATION The operation allows to initialize international payment in XML format (PAIN.001.001.03).

Format: XML

Request:

Atribute in PAIN.001.001.03 Type Mandatory Description

CstmrCdtTrfInitn.PmtInf.Db

trAcct.Id.IBAN

String [34] yes Debtor account -

International Bank Account

Number (IBAN)


tr.Nm

String [70] yes Debtor name

CstmrCdtTrfInitn.PmtInf.Cdt

TrfTxInf.Cdtr.Nm

String [35] yes Creditor name

See allowed characters

mentioned below.

CstmrCdtTrfInitn.GrpHdr.Ini

tgPty.PstlAdr.StrtNm

String [70] no Creditor postal address -

street


mentioned below.


tgPty.PstlAdr.BldgNb


building number


mentioned below.


51


tgPty.PstlAdr.PstCd


postal code


mentioned below.


tgPty.PstlAdr.TwnNm


city


mentioned below.


tgPty.PstlAdr.Ctry

Enum no Creditor postal address -

country

Country code according to

ISO3166

Format: [A-Z]{2,2}


TrfTxInf.CdtrAcct.Id.IBAN

String [34] required

if CstmrCdtTrfInitn.PmtInf.C

dtTrfTxInf.CdtrAcct.Id.Othr.I

d is not filled

Creditor account number in

IBAN format

If the request contains an

account number in a other

format than IBAN, this

attribute must be omitted,

otherwise the payment will

not be processed

The attribute can not

contain OTP Bank IBAN, ie.

bank code in the IBAN can

not be 5200


TrfTxInf.CdtrAcct.Id.Othr.Id

String [34] required

if CstmrCdtTrfInitn.PmtInf.C

dtTrfTxInf.CdtrAcct.Id.IBAN

is not filled

Creditor account number in

other format than IBAN

If the request contains an

account number in IBAN

format, this attribute must

be omitted, otherwise the

payment will not be

processed


52


TrfTxInf.CdtrAgt.FinInstnId.

BIC

String [11] required if creditor account

number is not in IBAN

format (account number is

filled

in CstmrCdtTrfInitn.PmtInf.

CdtTrfTxInf.CdtrAcct.Id.Othr

.Id) and at the same time

creditor bank name and

creditor bank address is not

filled

(CstmrCdtTrfInitn.PmtInf.Cd

tTrfTxInf.CdtrAgt.FinInstnId.

Nm,



PstlAdr.StrtNm,



PstlAdr.BldgNb,



PstlAdr.PstCd,



PstlAdr.TwnNm,



PstlAdr.Ctry)

Creditor BIC code

Attribute can not contain

OTP Bank BIC code



Nm

String [35] required if creditor account

number is not in IBAN

format (account number is

filled

in CstmrCdtTrfInitn.PmtInf.

CdtTrfTxInf.CdtrAcct.Id.Othr

.Id) and creditor BIC code is

not filled

(CstmrCdtTrfInitn.PmtInf.Cd

tTrfTxInf.CdtrAgt.FinInstnId.

BIC)

Creditor bank name



PstlAdr.StrtNm

String [70] Creditor bank address -

street



PstlAdr.BldgNb


building number


53



PstlAdr.PstCd


postal code



PstlAdr.TwnNm

String [35] Creditor bank address - city



PstlAdr.Ctry

Enum Creditor bank address -

country

Country code according to

ISO3166

Format: [A-Z]{2,2}


TrfTxInf.Amt.InstdAmt

Number Float [12.2] yes Payment amount

For HUF and JPY currency

only integer number is

accepted, payments in HUF

or JPY currency with

decimal amount will be

rejected

Parameter Ccy

atribútu CstmrCdtTrfInitn.P

mtInf.CdtTrfTxInf.Amt.Instd

Amt

Enum yes Payment currency

Allowed values:

• AUD

• CAD

• CHF

• CZK

• DKK

• EUR

• GBP

• HUF

• JPY

• NOK


54

• PLN

• RUB

• SEK

• USD

In case of other currency,

the payment will be

rejected

CstmrCdtTrfInitn.PmtInf.Re

qdExctnDt

ISODate yes Requested execution date

Payment to be executed

with today's due date can

be entered until 15:00,

payments sent after this

time must already be with

the due date shifted by 1

day.

A payment sent after 15:00

with the current due date

will be rejected.


TrfTxInf.PmtId.EndToEndId

String [35] no Payer's reference

If the request contains

EndToEndId value, it will be

ignored.


TrfTxInf.RmtInf.Ustrd

String [140] no Remittance information

If the request contains the

Ustrd attribute multiple

times, only the first value

will be used, others will be

ignored.

CstmrCdtTrfInitn.PmtInf.Pm

tTpInf.InstrPrty

Enum no Priority

Allowed values:

• NORM

• HIGH


55

For HIGH priority, an extra

charge will be charged to

the client

If the attribute is not filled,

the priority "NORM" will be

used


TrfTxInf.ChrgBr

Enum no Details for charges

Allowed values:

• CRED - all charges

are borne by

creditor

• DEBT - all charges

are borne by

debtor

• SHAR - debtor

and creditor pay

charges of their

own bank

If the BIC code is from the

SEPA area, it is necessary to

send value "SHAR",

regardless of the payment

currency

If the attribute is not filled,

value "SHAR" will be used


TrfTxInf.RmtInf.Strd.AddtlR

mtInf

String [140] no Additional remittance

information

If the request contains

attribute multiple times,

only first 70 chars of first

value will be used, other

chars of first value and

other occurrences will be

ignored


tr.CtctDtls.Nm

String [35] no Name of the contact person


56


tr.CtctDtls.PhneNb

String [15] no Telephone number of the

contact person

Format: \+[0-9]{1,3}-[0-

9()+\-]{1,30}

Example: +421-911123123


tr.CtctDtls.EmailAdr

String [35] no E-mail address of the

contact person

Allowed characters

• a-z, A-Z, 0-9, Á á É é Í í Ó ó Ú ú Ý ý Ä ä Ě ě Ô ô Ĺ ĺ Ŕ ŕ Č č Ď ď Ľ ľ Ň ň Ř ř Š š Ť ť Ž ž / - ? : ( ) . ’ + space

Crlf

Response:

Attribute Mapping in the XML

structure

Mandatory Type Description

orderId TxInfAndSts/AcctSvcr

Ref

yes String [35] OrderId is Unique

reference, as

assigned by the

account servicing

institution, to

unambiguously

identify the

instruction.

status TxInfAndSts/TxSts yes Enum Transaction status

indicator is

enumeration:

• "ACTC"

(AcceptedT

echnicalVal

idation)

• "ACWC"

(Accepted

WithChang

e)


57

• "RJCT"

(Rejected)

reasonCode TxInfAndSts/StsRsnIn

f/Rsn

no Enum ISO 20022 Rejected

Status Reason Code

statusDateTime GrpHdr/CreDtTm no DateTime The date and time in

RFC3339 format at

which a particular

action has been

requested or

executed.


Header:

POST /api/v1/payments/swift/iso HTTP/1.1

Host: api.nedsecure-int.com











PSU-Geo-Location: 48.1569126, 17.119287

PSU-Presence: true

Body:


<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03">


58

<CstmrCdtTrfInitn>

<GrpHdr>

<MsgId>payment 1</MsgId>

<CreDtTm>2019-01-13T14:24:39</CreDtTm>

<NbOfTxs>1</NbOfTxs>

<InitgPty />

</GrpHdr>

<PmtInf>

<PmtInfId>8b4265e6-45a5-4755-b8ce-a3d374067cd</PmtInfId>

<PmtMtd>CHK</PmtMtd>

<PmtTpInf>

<InstrPrty>NORM</InstrPrty>

</PmtTpInf>

<ReqdExctnDt>NOW()</ReqdExctnDt>

<Dbtr>

<Nm>Jan Novak</Nm>

</Dbtr>

<DbtrAcct>

<Id>

<IBAN>SK5852009999930000000166</IBAN>

</Id>

</DbtrAcct>

<DbtrAgt>

<FinInstnId />

</DbtrAgt>

<CdtTrfTxInf>

<PmtId>

<EndToEndId>pisp</EndToEndId>

</PmtId>

<Amt>


59

<InstdAmt Ccy="EUR">100</InstdAmt>

</Amt>

<ChrgBr>SHAR</ChrgBr>

<Cdtr>

<Nm>Ivana Prva</Nm>

</Cdtr>

<CdtrAcct>

<Id>

<IBAN>SK6807200002891987426353</IBAN>

</Id>

</CdtrAcct>

<RmtInf>

<Ustrd>string</Ustrd>

<Strd>

<AddtlRmtInf>string2</AddtlRmtInf>

</Strd>

</RmtInf>

</CdtTrfTxInf>

</PmtInf>

</CstmrCdtTrfInitn>

</Document>


Header:

HTTP/1.1 200 OK


Response-ID: 71ac4012-e21d-421b-b776-988564f1fbb4



Body:


60


<ns2:Document xmlns:ns2="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03">

<CstmrPmtStsRpt>

<ns2:GrpHdr>

<ns2:MsgId>payment 1</ns2:MsgId>

<ns2:CreDtTm>2019-01-13T14:24:39</ns2:CreDtTm>

</ns2:GrpHdr>

<ns2:OrgnlGrpInfAndSts>

<ns2:OrgnlMsgId>payment 1</ns2:OrgnlMsgId>

<ns2:OrgnlMsgNmId />

</ns2:OrgnlGrpInfAndSts>

<ns2:OrgnlPmtInfAndSts>

<ns2:TxInfAndSts>

<ns2:TxSts>ACTC</ns2:TxSts>

<ns2:StsRsnInf>

<ns2:Rsn />

</ns2:StsRsnInf>

<ns2:AcctSvcrRef>PAYMENT_tr_ffdc2f2d-1288-4212-be38-

a011838ee051</ns2:AcctSvcrRef>

</ns2:TxInfAndSts>

</ns2:OrgnlPmtInfAndSts>

</CstmrPmtStsRpt>

</ns2:Document>

3.6.8 PISP OPERATION: BALANCE CHECK Please see chapter 3.7.2 PIISP Operation: Balance check for further information.

3.6.9 ACCESS TOKEN This structure is used for:

• payment initialization,

• status of a payment,


61

• payment cancellation,

• balance check.

Before payment submission the same structure as for AISP tokens is used.

Endpoint: POST https://api.otpbanka.sk/otp-psd2-gw/auth/token

Request:


grant_type Mandatory String client_credentials exclusively to assign one-time access_token

scope Mandatory String Required scope: "PISP" or „PIISP“

Response:


scope Optional String "PISP" or „PIISP“

access_token Mandatory String Short-term (one-time) token. This token is used to authorize the API request.




Host: api.banka.sk


Authorization: Basic BASE64(CLIENT_ID +

":" + CLIENT_SECRET)


62

grant_type=client_credentials&

scope=PISP

3.6.9.2 HTTP Response Example HTTP/1.1 200 OK


{

"scope":"PISP",

"access_token":"ACCESS_TOKEN_0",

"token_type":"bearer",

"expires_in":3600

}

3.6.10 CODE TABLES

3.6.10.1 Rejected Status Reason Codes

Rejected Status Reason Code Description

AC02 Debtor account number invalid or missing

AC03 Creditor account number invalid or missing

AC10 Debtor account currency is invalid or missing

AG08 Transaction failed due to invalid or missing user or access right

AM02 Specific transaction/message amount is greater than allowed maximum

AM04 Amount of funds available to cover specified message amount is insufficient

AM21 Transaction amount exceeds limits agreed between bank and client

DT01 Invalid date (eg, wrong or missing settlement date)

FF10 File or transaction cannot be processed due to technical issues at the bank side


63

Rejected Status Reason Code Description

RC04 Creditor bank identifier is invalid or missing

RC07 Creditor BIC identifier is invalid or missing

RR10 Character set supplied not valid for the country and payment type

TM01 Associated message, payment information block, or transaction was received after

agreed processing cut-off time

AB04 Settlement process aborted due to a fatal error

3.7 PIISP APIS Chapter defines list of services provided for PIISP.

Prerequisites:

• The TPP is registered for the PISP/PIISP role and valid PISP/PIISP scope

• The TPP has been successfully authenticated

• The TPP has presented its “OAuth2 Authorization Client Credential Grant” access token which

allows OTP Bank to identify the TPP

3.7.1 ENDPOINT DEFINITION

Endpoint Method Description


gw/api/v1/accounts/balanceCheck

POST Balance check – service provides information about sufficient balance

with the yes/no answer

3.7.2 PIISP OPERATION: BALANCE CHECK The operation provides the resolution whether the balance of a bank customer's account identified by

IBAN is sufficient for asked amount.

Format: JSON

Request:


64



instructionIdentification Mandatory String Technical identification of

payment, generated by

the PIISP

creationDateTime Optional DateTime The date and time in

RFC3339 format at which

a particular action has

been requested or

executed.

iban Mandatory String [34] International Bank

Account Number (IBAN)

amount value

Mandatory Number

Float

[12.2]

Transaction amount value

in account currency.

Numeric value of the

amount as a fractional

number.

amount currency

Mandatory String [3] Transaction amount

currency. Formated in

Alphabetic codes from ISO

4712.

relatedParties tradingParty identification Optional String [35] Unique identification of a

third party.

For card transaction, this

is ID of merchant.

relatedParties tradingParty name Optional String

[140]

Name of a third party.

For card transaction, this

is the name of merchant.

relatedParties tradingParty address Optional String [70] Merchant cummulative

address identification

usually containing


65

concatenation of street

name, street number, etc.

relatedParties tradingParty countryCode Optional String [2] The two letter merchant

country code adopted

from ISO3166.

relatedParties tradingParty merchantCode Optional String [4] A Merchant Category

Code (MCC) coordinated

by MasterCard and Visa.

references chequeNumber Optional String [35] For card transactions, this

is the card number in

format **** **** ****

1111

references holderName Optional String [35] Card holder name

Response:

Attributes

structure


Level 1

response Mandatory Enum Response is enumeration:

- APPR (sufficient funds on the account)

- DECL (insufficient funds in the account)

dateTime Mandatory DateTime The date and time in RFC3339 format at which a particular action has



Header:

POST /api/v1/accounts/balanceCheck

Host: api.banka.sk




66







PSU-Geo-Location: 48.145745, 17.116062


PSU-Presence: false

Body:

{

"instructionIdentification": "9b766084-57de-48b2-be53-1bd2804ae0b7",


"iban": "SK0252009999930000000107",

"amount": {

"value": 1234.56,

"currency": "EUR"

},

"relatedParties": {

"tradingParty": {

"identification": "AAA-GG-SSSS",

"name": "Jane Doe Company",

" adress": "My street 123, MyLand",

"countryCode": "SK",

"merchantCode": "3370"

},

},

"references": {

"chequeNumber": "************3456",


67

"holderName": "Jane Doe"

}

}


Header:

HTTP/1.1 200 OK





Body:

{

"result": "APPR",

"creationDateTime": "2019-02-15T14:55:02+01:00"

}

3.7.3 ACCESS TOKEN It is necessary to use service and structure as with PISP service but with scope PIISP.

psd2 apis technical documentation - otp bankaotp bank does accept confidential clients only....

Documents