psd2 apis technical documentation - otp bankaotp bank does accept confidential clients only....
TRANSCRIPT
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
PSD2 APIs technical documentation Version 2.0
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
PSD2 APIs technical documentation Version 2.0
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
PSD2 APIs technical documentation Version 2.0
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.
PSD2 APIs technical documentation Version 2.0
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
PSD2 APIs technical documentation Version 2.0
7
Attribute Optionality Type Description
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.
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 same
Process-ID).
Although it may be arbitrary string, it is strongly recommended to use a Universally
Unique Identifier (UUID) version 4 form (RFC4122).
HTTP Response header example
Content-Type: application/json;charset=UTF-8
Response-ID: ac30869e-29e2-40f7-83fb-ed1c6bdde216
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
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.
PSD2 APIs technical documentation Version 2.0
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:
Attribute Optionality Type Description
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).
PSD2 APIs technical documentation Version 2.0
9
contacts Mandatory Array of
strings e-
[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:
Attribute Optionality Type Description
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.
PSD2 APIs technical documentation Version 2.0
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-
[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
Content-Type: application/json;charset=UTF-8
{
PSD2 APIs technical documentation Version 2.0
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
Content-Type: application/json;charset=UTF-8
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"],
PSD2 APIs technical documentation Version 2.0
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:
Attribute Optionality Type Description
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.
PSD2 APIs technical documentation Version 2.0
13
Response:
Attribute Optionality Type Description
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.
PSD2 APIs technical documentation Version 2.0
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.
https://api.otpbanka.sk/otp-
psd2-
gw/api/v1/accounts/transactions
POST Account transactions – service provides list of transactions in defined date
range related to an account.
https://api.otpbanka.sk/otp-
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:
PSD2 APIs technical documentation Version 2.0
15
Attributes structure Optionality Type Description
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:
PSD2 APIs technical documentation Version 2.0
16
POST /api/v1/accounts/information HTTP/1.1
Host: api.banka.sk
Content-Type: application/json;charset=UTF-8
Authorization:Bearer IDWJJBCHQ5DZJWEMO7ZWM4DLYWOFWKXX
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
Body:
{
"iban": "SK0252009999930000000107"
}
3.5.2.2 HTTP Response Example
Header
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Response-ID: 7deb90a9-9900-4c90-a91c-3ecc888c2c88
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
Body
{
"account": {
PSD2 APIs technical documentation Version 2.0
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"
},
"creditDebitIndicator": "CRDT",
"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
PSD2 APIs technical documentation Version 2.0
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
PSD2 APIs technical documentation Version 2.0
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.
PSD2 APIs technical documentation Version 2.0
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
PSD2 APIs technical documentation Version 2.0
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).
PSD2 APIs technical documentation Version 2.0
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.
3.5.3.1 HTTP Request Example
Header:
POST /api/v1/accounts/transactions HTTP/1.1
Host: api.banka.sk
Content-Type: application/json;charset=UTF-8
Authorization:Bearer IDWJJBCHQ5DZJWEMO7ZWM4DLYWOFWKXX
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: false
Body:
{
"iban": "SK0252009999930000000107",
PSD2 APIs technical documentation Version 2.0
23
"status": "ALL",
"dateFrom": "2019-02-09",
"dateTo": "2019-02-18",
"pageSize": 50,
"page": 0
}
3.5.3.2 HTTP Response Example
Header:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Response-ID: 7deb90a9-9900-4c90-a91c-3ecc888c2c88
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
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"
}
},
PSD2 APIs technical documentation Version 2.0
24
{
"amount": {
"value": 7.7,
"currency": "EUR"
},
"creditDebitIndicator": "CRDT",
"status": "INFO",
"bookingDate": "2019-02-15",
"valueDate": "2019-02-15",
"transactionDetails": {
"relatedParties": {
"debtorAccount": {
"identification": "SK0252009999930000000107"
},
"creditorAccount": {
"identification": "SK7752009999930000000115"
}
},
"relatedAgents": {
"debtorAgent": {
"financialInstitutionIdentification": "OTPVSKBX"
},
"creditAgent": {
"financialInstitutionIdentification": "OTPVSKBXXXX"
}
},
"remittanceInformation": "príkaz na úhradu"
}
},
{
PSD2 APIs technical documentation Version 2.0
25
"amount": {
"value": 1,
"currency": "EUR"
},
"creditDebitIndicator": "DBIT",
"status": "INFO",
"bookingDate": "2019-02-14",
"valueDate": "2019-02-14",
"transactionDetails": {
"remittanceInformation": "SERVICE FEES"
}
},
{
"amount": {
"value": 1,
"currency": "EUR"
},
"creditDebitIndicator": "DBIT",
"status": "INFO",
"bookingDate": "2019-02-14",
"valueDate": "2019-02-14",
"transactionDetails": {
"remittanceInformation": "SERVICE FEES"
}
},
{
"amount": {
"value": 1,
"currency": "EUR"
},
PSD2 APIs technical documentation Version 2.0
26
"creditDebitIndicator": "DBIT",
"status": "INFO",
"bookingDate": "2019-02-14",
"valueDate": "2019-02-14",
"transactionDetails": {
"remittanceInformation": "SERVICE FEES"
}
}
]
}
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:
PSD2 APIs technical documentation Version 2.0
27
Attributes sturcture Optionality Type Description
Level 1 Level 2 Level 3
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).
PSD2 APIs technical documentation Version 2.0
28
accounts scope Mandatory Array
[String]
Attribute contains
set of particular
account scopes for
TPP.
Formatted as array
of following
enumerations:
AISP, PISP, PIISP.
3.5.4.1 HTTP Request Example
Header:
GET /api/v2/accounts HTTP/1.1
Host: api.banka.sk
Content-Type: application/json;charset=UTF-8
Authorization:Bearer IDWJJBCHQ5DZJWEMO7ZWM4DLYWOFWKXX
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:00PSU–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: false
Body:
{
}
3.5.4.2 HTTP Response Example
Header:
PSD2 APIs technical documentation Version 2.0
29
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Response-ID: 7deb90a9-9900-4c90-a91c-3ecc888c2c88
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
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
PSD2 APIs technical documentation Version 2.0
30
Request:
Attribute Optionality Type Description
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:
Attribute Optionality Type Description
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
Content-Type: application/x-www-form-urlencoded
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]
PSD2 APIs technical documentation Version 2.0
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:
Attribute Optionality Type Description
grant_type Mandatory String Value MUST be set to "refresh_token".
refresh_token Mandatory String The refresh token issued to the client.
scope Optional String List of permissions separated by the space for which the token is issued.
Response:
Attribute Optionality Type Description
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“
PSD2 APIs technical documentation Version 2.0
32
expires_in Mandatory Number The remaining time to expiration of access_token - in seconds.
3.5.6.1 HTTP Request Example POST /token HTTP/1.1
Host: api.banka.sk
Content-Type: application/x-www-form-urlencoded
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)
https://api.otpbanka.sk/otp-psd2-
gw/api/v1/payments/submission
POST Standard payment submission – service allows the authorization of
initialized payment
https://api.otpbanka.sk/otp-psd2-
gw/api/v1/payments/{orderId}/status
GET Payment order status – service provides actual information about
initialized payment
PSD2 APIs technical documentation Version 2.0
33
https://api.otpbanka.sk/otp-psd2-
gw/api/v2/payments/standard/sba
POST Standard SEPA payment initialization – service allows to initialize
payment in JSON format
https://api.otpbanka.sk/otp-psd2-
gw/api/v1/payments/{orderId}/rcp
DELETE Cancelling of SEPA payment - service allows cancelling of initialized
SEPA payment or submitted future-dated SEPA payment
https://api.otpbanka.sk/otp-psd2-
gw/api/v1/payments/swift/iso
POST International payment initialization - service allows to initialize
payment in XML format (PAIN.001.001.03)
https://api.otpbanka.sk/otp-psd2-
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, Á á É é Í í Ó ó Ú ú Ý ý Ä ä Ě ě Ô ô Ĺ ĺ Ŕ ŕ
Č č Ď ď Ľ ľ Ň ň Ř ř Š š Ť ť Ž ž $ @ ! % . : - _ [ ] } ? ) + ´ ,
PSD2 APIs technical documentation Version 2.0
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
Optionality Type Description
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.
3.6.2.1 HTTP Request Example
Header:
POST /api/v1/payments/standard/iso HTTP/1.1
Host: api.banka.sk
Content-Type: application/xml;charset=UTF-8
Authorization: Bearer IDWJJBCHQ5DZJWEMO7ZWM4DLYWOFWKXX
Request-ID: c2c48fc8-1f79-4934-a47b-56d61a28f351
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
PSD2 APIs technical documentation Version 2.0
35
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
PSU-Last-Logged-Time: 2019-02-16T11:56: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.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>
PSD2 APIs technical documentation Version 2.0
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>
PSD2 APIs technical documentation Version 2.0
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>
PSD2 APIs technical documentation Version 2.0
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>
3.6.2.2 HTTP Response Example
Header:
HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8
Response-ID: 7deb90a9-9900-4c90-a91c-3ecc888c2c88
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
PSD2 APIs technical documentation Version 2.0
39
Body:
<?xml version="1.0" encoding="UTF-8"?>
<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
PSD2 APIs technical documentation Version 2.0
40
Request:
The authorization header will contain a "bearer token" that corresponds to "payment order".
Response:
Attributes
structure
Optionality Type Description
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:
- ACTC (AcceptedTechnicalValidation)
- ACWC (AcceptedWithChange)
- 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.
3.6.3.1 HTTP Request Example
Header:
POST /api/v1/payments/submission HTTP/1.1
Host: api.banka.sk
Content-Type: application/json;charset=UTF-8
Authorization: Bearer 1VVKPKO9IJUBFFXUKLW8JDVWM3B5XUBG
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-16T11:56:32+01:00
PSD2 APIs technical documentation Version 2.0
41
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.145745, 17.116062
PSU-Presence: true
Body:
{
"orderId":"ffdc2f2d-1288-4212-be38-a011838ee051"
}
3.6.3.2 HTTP Response Example
Header:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Response-ID: 7deb90a9-9900-4c90-a91c-3ecc888c2c88
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
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
PSD2 APIs technical documentation Version 2.0
42
Request:
Empty payload.
Response:
Attributes
structure
Optionality Type Description
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:
- ACTC (AcceptedTechnicalValidation)
- ACWC (AcceptedWithChange)
- RJCT (Rejected)
- PDNG (Pending)
- ACSP (AcceptedSettlementInProcess)
- ACSC (AcceptedSettlementCompleted)
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.
3.6.4.1 HTTP Request Example
Header:
GET /api/v1/payments/ffdc2f2d-1288-4212-be38-a011838ee051/status HTTP/1.1
Host: api.banka.sk
Content-Type: application/json;charset=UTF-8
Authorization: Bearer IDWJJBCHQ5DZJWEMO7ZWM4DLYWOFWKXX
Request-ID: c2c48fc8-1f79-4934-a47b-56d61a28f351
PSD2 APIs technical documentation Version 2.0
43
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
PSU-Last-Logged-Time: 2019-02-16T11:56: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.145745, 17.116062
PSU-Presence: false
Body:
{
}
3.6.4.2 HTTP Response Example
Header:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Response-ID: 7deb90a9-9900-4c90-a91c-3ecc888c2c88
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
Body:
{
"orderId":"ffdc2f2d-1288-4212-be38-a011838ee051",
"status": "RJCT",
"reasonCode": "AM21",
"statusDateTime": "2019-02-18T09:59:27+01:00"
}
PSD2 APIs technical documentation Version 2.0
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).
Attributes structure Optionality Type Description
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)
See allowed characters mentioned below.
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.
PSD2 APIs technical documentation Version 2.0
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).
See allowed characters mentioned below.
remittanceInformation Optional String [140] The text aimed as the information for a receiver of
the transaction.
See allowed characters mentioned below.
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
Optionality Type Description
Level 1
PSD2 APIs technical documentation Version 2.0
46
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:
- ACTC (AcceptedTechnicalValidation)
- ACWC (AcceptedWithChange)
- RJCT (Rejected)
- PDNG (Pending)
- ACSP (AcceptedSettlementInProcess)
- ACSC (AcceptedSettlementCompleted)
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.
request Optional String Signed JWT - security mitigation for unauthorized payment request
changes
3.6.5.1 HTTP Request Example
Header:
POST /api/v2/payments/standard/sba HTTP/1.1
Host: api.banka.sk
Content-Type: application/json;charset=UTF-8
Authorization: Bearer IDWJJBCHQ5DZJWEMO7ZWM4DLYWOFWKXX
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-16T11:56:32+01:00
PSU–IP-Address: 192.168.0.100
PSU-Device-OS: iOS 12.1.4
PSD2 APIs technical documentation Version 2.0
47
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.145745, 17.116062
PSU-Presence: true
Body:
{
"instructionIdentification": "9b766084-57de-48b2-be53-1bd2804ae0b7",
"creationDateTime": "2019-02-16T11:59:20+01:00",
"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"
}
3.6.5.2 HTTP Response Example
Header:
Content-Type: application/json
Response-ID: 7deb90a9-9900-4c90-a91c-3ecc888c2c88
PSD2 APIs technical documentation Version 2.0
48
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
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
Optionality Type Description
orderId Mandatory String
[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
PSD2 APIs technical documentation Version 2.0
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
3.6.6.1 HTTP Request Example
Header:
DELETE api/v1/payments/aichz8i8z4c2ynabqtkymddhx2raw29zrzj/rcp HTTP/1.1
Host: api.banka.sk
Content-Type: application/json;charset=UTF-8
Authorization: Bearer IDWJJBCHQ5DZJWEMO7ZWM4DLYWOFWKXX
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-16T11:56: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.6.6.2 HTTP Response Example
Header:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Response-ID: 71ac4012-e21d-421b-b776-988564f1fbb4
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
PSD2 APIs technical documentation Version 2.0
50
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
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)
CstmrCdtTrfInitn.PmtInf.Db
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
See allowed characters
mentioned below.
CstmrCdtTrfInitn.GrpHdr.Ini
tgPty.PstlAdr.BldgNb
String [16] no Creditor postal address -
building number
See allowed characters
mentioned below.
PSD2 APIs technical documentation Version 2.0
51
CstmrCdtTrfInitn.GrpHdr.Ini
tgPty.PstlAdr.PstCd
String [16] no Creditor postal address -
postal code
See allowed characters
mentioned below.
CstmrCdtTrfInitn.GrpHdr.Ini
tgPty.PstlAdr.TwnNm
String [35] no Creditor postal address -
city
See allowed characters
mentioned below.
CstmrCdtTrfInitn.GrpHdr.Ini
tgPty.PstlAdr.Ctry
Enum no Creditor postal address -
country
Country code according to
ISO3166
Format: [A-Z]{2,2}
CstmrCdtTrfInitn.PmtInf.Cdt
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
CstmrCdtTrfInitn.PmtInf.Cdt
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
PSD2 APIs technical documentation Version 2.0
52
CstmrCdtTrfInitn.PmtInf.Cdt
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,
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.CdtrAgt.FinInstnId.
PstlAdr.StrtNm,
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.CdtrAgt.FinInstnId.
PstlAdr.BldgNb,
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.CdtrAgt.FinInstnId.
PstlAdr.PstCd,
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.CdtrAgt.FinInstnId.
PstlAdr.TwnNm,
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.CdtrAgt.FinInstnId.
PstlAdr.Ctry)
Creditor BIC code
Attribute can not contain
OTP Bank BIC code
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.CdtrAgt.FinInstnId.
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
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.CdtrAgt.FinInstnId.
PstlAdr.StrtNm
String [70] Creditor bank address -
street
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.CdtrAgt.FinInstnId.
PstlAdr.BldgNb
String [16] Creditor bank address -
building number
PSD2 APIs technical documentation Version 2.0
53
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.CdtrAgt.FinInstnId.
PstlAdr.PstCd
String [16] Creditor bank address -
postal code
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.CdtrAgt.FinInstnId.
PstlAdr.TwnNm
String [35] Creditor bank address - city
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.CdtrAgt.FinInstnId.
PstlAdr.Ctry
Enum Creditor bank address -
country
Country code according to
ISO3166
Format: [A-Z]{2,2}
CstmrCdtTrfInitn.PmtInf.Cdt
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
PSD2 APIs technical documentation Version 2.0
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.
CstmrCdtTrfInitn.PmtInf.Cdt
TrfTxInf.PmtId.EndToEndId
String [35] no Payer's reference
If the request contains
EndToEndId value, it will be
ignored.
CstmrCdtTrfInitn.PmtInf.Cdt
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
PSD2 APIs technical documentation Version 2.0
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
CstmrCdtTrfInitn.PmtInf.Cdt
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
CstmrCdtTrfInitn.PmtInf.Cdt
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
CstmrCdtTrfInitn.PmtInf.Db
tr.CtctDtls.Nm
String [35] no Name of the contact person
PSD2 APIs technical documentation Version 2.0
56
CstmrCdtTrfInitn.PmtInf.Db
tr.CtctDtls.PhneNb
String [15] no Telephone number of the
contact person
Format: \+[0-9]{1,3}-[0-
9()+\-]{1,30}
Example: +421-911123123
CstmrCdtTrfInitn.PmtInf.Db
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)
PSD2 APIs technical documentation Version 2.0
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.
3.6.7.1 HTTP Request Example
Header:
POST /api/v1/payments/swift/iso HTTP/1.1
Host: api.nedsecure-int.com
Content-Type: application/json;charset=UTF-8
Authorization: Bearer IDWJJBCHQ5DZJWEMO7ZWM4DLYWOFWKXX
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-16T11:56: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
Body:
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03">
PSD2 APIs technical documentation Version 2.0
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>
PSD2 APIs technical documentation Version 2.0
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>
3.6.7.2 HTTP Response Example
Header:
HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8
Response-ID: 71ac4012-e21d-421b-b776-988564f1fbb4
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
Body:
PSD2 APIs technical documentation Version 2.0
60
<?xml version="1.0" encoding="UTF-8"?>
<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,
PSD2 APIs technical documentation Version 2.0
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:
Attribute Optionality Type Description
grant_type Mandatory String client_credentials exclusively to assign one-time access_token
scope Mandatory String Required scope: "PISP" or „PIISP“
Response:
Attribute Optionality Type Description
scope Optional String "PISP" or „PIISP“
access_token Mandatory String Short-term (one-time) token. This token is used to authorize the API request.
token_type Mandatory String Type of token „Bearer“
expires_in Mandatory Number The remaining time to expiration of access_token - in seconds.
3.6.9.1 HTTP Request Example POST /token HTTP/1.1
Host: api.banka.sk
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(CLIENT_ID +
":" + CLIENT_SECRET)
PSD2 APIs technical documentation Version 2.0
62
grant_type=client_credentials&
scope=PISP
3.6.9.2 HTTP Response Example HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"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
PSD2 APIs technical documentation Version 2.0
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
https://api.otpbanka.sk/otp-psd2-
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:
PSD2 APIs technical documentation Version 2.0
64
Attributes structure Optionality Type Description
Level 1 Level 2 Level 3
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
PSD2 APIs technical documentation Version 2.0
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
Optionality Type Description
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
been requested or executed.
3.7.2.1 HTTP Request Example
Header:
POST /api/v1/accounts/balanceCheck
Host: api.banka.sk
Content-Type: application/json;charset=UTF-8
Request-ID: c2c48fc8-1f79-4934-a47b-56d61a28f351
PSD2 APIs technical documentation Version 2.0
66
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
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.145745, 17.116062
PSU-Last-Logged-Time: 2019-02-07T14:54:32+01:00
PSU-Presence: false
Body:
{
"instructionIdentification": "9b766084-57de-48b2-be53-1bd2804ae0b7",
"creationDateTime": "2019-02-16T14:54:32+01:00",
"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",
PSD2 APIs technical documentation Version 2.0
67
"holderName": "Jane Doe"
}
}
3.7.2.2 HTTP Response Example
Header:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Response-ID: 7deb90a9-9900-4c90-a91c-3ecc888c2c88
Correlation-ID: 292163f5-4eee-4447-9292-5672fdf0013b
Process-ID: 4b88bf95-e129-42b8-a17d-1d2379810fbe
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.