enable:Banking SDK
Welcome to Enable Banking SDK developer documentation! We are happy that you are interested our solution. In this documentation you have all information to start use our SDK.
Enable Banking SDK is for connecting your solution to Open Banking APIs without 3rd party solutions. With our solution you can build new business driven solutions and also connect your current solution to Open Banking APIs. We are believer for easy and fast development so we offer all needed documentation and code examples for you.
For starting you need to have developer license which you can order here. You will get your developer SDK, which is connected Open Banking API sandboxes.
For production usage please contact us or If you just need more info contact us at hello@enablebanking.com
Changelog
0.2.1
Added
- Added
DataRetrievalException
andInsufficientScopeException
derived fromHttpException
to represent particular cases.
0.2.0
Added
- [Java] Improved connector settings interface. Added
AbstractConnectorSettingsFactory
class with a factory methodcreateConnectorSettings
to simplify creation of connector settings.ApiClient
now has constructors takingConnectorSettings
instance instead of list of settings objects. - [Java]
AbstractPlatformExtension
class consisting ofsignPKCS1v15usingSHA256
andmakeRequest
methods is added in order to simplify customisation of Java platform. Also addedApiClient
constructor takingAbstractPlatformExtension
as a parameter. Transaction
data structure extended with fieldsbankTransactionCode
,creditor
anddebtor
andBankTransactionCode
data structure added.- Value
refresh_token
is supported forgrant_type
parameter ofmakeToken
method.
Changed
- [Java]
ApiClient
constructors accepting settings as a list of objects andJavaPlatform
class are changed toprotected
. - Changed order of connector settings. Parameters
consentId
,accessToken
andrefreshToken
are now always required (should be set tonull
if not present). - [Java] Standard Java SE 8 date-time classes are used instead of ThreeTen-Backport classes, thus Java SE 6 and 7 support is dropped.
- Field
remittanceInformation
ofTransaction
changed to not required (mainly to support credit card transactions, for which remittance info is usually not provided). Access
data structure changed:balances
andtransactions
fields contain details for requested access andaccounts
field contains list of accessed account IDs.
Fixed
- Field mapping for Open Banking UK standard is improved.
0.1.x
This version was created before the changelog has been introduced.
SDK reference
Select a language for code samples from the tabs above or the mobile navigation menu.
Currently enable:Banking SDK consists of authorization, account information and payment initiation APIs. The same calls and data structures are used for interacting with different banks. In order to use each of the APIs corresponding API instance needs to be created with bank specific settings.
enable:Banking SDK API is based on STET PSD2 specification.
This API intends to provide an interface for Third Party Providers (TPP) for accessing Account Servicing Payment Service Providers (ASPSP, i.e. banks).
TPP may act as Account Information Service Provider (AISP), Payment Initiation Service Providers (PISP) or both.
The Payment Service User (PSU) is the owner of the accounts held by the ASPSP and gives accreditations to the TPP in order to access his accounts information or initiates payment from these accounts.
License: LicenseRef-LICENSE
Meta API
getConnectors
Code samples
const enablebanking = require('enablebanking');
const metaApi = new enablebanking.MetaApi(new enablebanking.ApiClient());
const connectors = await metaApi.getConnectors({
country: 'FI' // requesting connectors for Finland
});
import enablebanking
meta_api = enablebanking.MetaApi(enablebanking.ApiClient())
connectors = meta_api.get_connectors(
country='FI') # requesting connectors for Finland
import com.enablebanking.*;
import com.enablebanking.model.*;
import com.enablebanking.api.MetaApi;
MetaApi metaApi = new MetaApi(new ApiClient());
HalConnectors connectors = metaApi.getConnectors("FI"); // connectors for Finland
Retrieval of the available connectors
Parameters
Name | Type | Required | Description |
---|---|---|---|
country | string | false | Country ISO code |
Returned value
Data type: HalConnectors
List of connectors
Auth API
getAuth
Code samples
const enablebanking = require('enablebanking');
const authApi = new enablebanking.AuthApi(
new enablebanking.ApiClient('Bank name', [ /* Bank settings */ ]));
const { url } = await authApi.getAuth(
'code', // using authorization code grant
'https://example.com/', // redirect URL
['aisp'], // API scope
{
state: 'test' // state to pass to redirect URL
});
import enablebanking
auth_api = enablebanking.AuthApi(enablebanking.ApiClient(
'Bank name',
{
# Bank settings
})
url = auth_api.get_auth(
'code', # using authorization code grant
'https://example.com/', # redirect URL
['aisp'], # API scope
state='test', # state to pass to redirect URL
).url
import java.util.List;
import java.util.ArrayList;
import java.util.Arrays;
import com.enablebanking.ApiClient;
import com.enablebanking.model.*;
import com.enablebanking.api.AuthApi;
List bankSettings = new ArrayList();
// Filling in bank settings here...
AuthApi authApi = new AuthApi(new ApiClient("Bank name", bankSettings));
String url = authApi.getAuth(
"code", // using authorization code grant
"https://example.com/", // redirect URL
new ArrayList(Arrays.asList("aisp")), // API scope
"test", // state to pass to redirect URL
null // not passing access request (bank's defaults will be used)
).url;
Request Authorization Data
Parameters
Name | Type | Required | Description |
---|---|---|---|
response_type | string | true | none |
redirect_uri | string | true | none |
scope | array[string] | true | none |
state | string | false | none |
access | Access | false | Contains request for access to account information. |
Detailed descriptions
access: Contains request for access to account information.
This parameter should be set to override defaults for the banks, which allow PSUs to give consent for account information sharing right after authentication.
Enumerated Values
response_type
Value | Description |
---|---|
code | — |
scope
Value | Description |
---|---|
aisp | Access AISP (account information) APIs |
pisp | Access PISP (payment initiation) APIs |
Returned value
Data type: Auth
Authorization Data
Exceptions
Data type | Description |
---|---|
HttpException | Raised when ASPSP API responses with unspecified error. |
makeToken
Code samples
const enablebanking = require('enablebanking');
const authApi = new enablebanking.AuthApi(
new enablebanking.ApiClient('Bank name', [ /* Bank settings */ ]));
const token = await authApi.makeToken(
'authorization_code', // grant type, MUST be set to "authorization_code"
'so43ls-3ldg03sd-hl4saa3l2sl5czfhl3'); // The code received in the query string when redirected from authorization
import enablebanking
auth_api = enablebanking.AuthApi(enablebanking.ApiClient(
'Bank name',
{
# Bank settings
})
token = auth_api.make_token(
'authorization_code', # grant type, MUST be set to "authorization_code"
'so43ls-3ldg03sd-hl4saa3l2sl5czfhl3') # The code received in the query string when redirected from authorization
import java.util.List;
import java.util.ArrayList;
import com.enablebanking.ApiClient;
import com.enablebanking.model.*;
import com.enablebanking.api.AuthApi;
List bankSettings = new ArrayList();
// Filling in bank settings here...
AuthApi authApi = new AuthApi(new ApiClient("Bank name", bankSettings));
Token token = authApi.makeToken(
"authorization_code", // grant type, MUST be set to "authorization_code"
"so43ls-3ldg03sd-hl4saa3l2sl5czfhl3" // The code received in the query string when redirected from authorization
);
Request Access Token
Parameters
Name | Type | Required | Description |
---|---|---|---|
grant_type | string | true | Value should be set to authorization_code or refresh_token depending on what |
code | string | true | Value of either the code received in the query string when redirected from |
redirect_uri | string | false | Redirect URI supplied to getAuth function for retreival of the |
Detailed descriptions
grant_type: Value should be set to authorization_code
or refresh_token
depending on what
passed to code
parameter.
code: Value of either the code received in the query string when redirected from authorization page or the refresh token used for renewing access token.
redirect_uri: Redirect URI supplied to getAuth
function for retreival of the
authorization URL. This parameter is only required for some connectors, but it is
a good practice to pass it in order to unify usage for between different connectors.
Enumerated Values
grant_type
Value | Description |
---|---|
authorization_code | Used to exchange an authorization code for an access token. After the user returns to the client via the redirect URL, the application will get the authorization code from the URL and use it to request an access token. |
refresh_token | Used to exchange a refresh token for an access token when the access token has expired. This allows clients to continue to have a valid access token without further interaction with the user. Please note that refresh token is likely to be changed when calling `makeToken` with `refresh_token` grant type. |
Returned value
Data type: Token
Authorisation token (Bearer)
Exceptions
Data type | Description |
---|---|
HttpException | Raised when ASPSP API responses with unspecified error. |
getCurrentToken
Code samples
const enablebanking = require('enablebanking');
const authApi = new enablebanking.AuthApi(
new enablebanking.ApiClient('Bank name', [ /* Bank settings */ ]));
const token = await authApi.getCurrentToken();
import enablebanking
auth_api = enablebanking.AuthApi(enablebanking.ApiClient(
'Bank name',
{
# Bank settings
})
token = auth_api.get_current_token()
import java.util.List;
import java.util.ArrayList;
import com.enablebanking.ApiClient;
import com.enablebanking.model.*;
import com.enablebanking.api.AuthApi;
List bankSettings = new ArrayList();
// Filling in bank settings here...
AuthApi authApi = new AuthApi(new ApiClient("Bank name", bankSettings));
Token token = authApi.getCurrentToken();
Get current token data
Returned value
Data type: Token
Current token. Values for some fields might be missing if not used.
AISP API
getAccounts
Code samples
const enablebanking = require('enablebanking');
const aispApi = new enablebanking.AISPApi(
new enablebanking.ApiClient('Bank name', [ /* Bank settings */ ]));
const accounts = await aispApi.getAccounts();
import enablebanking
aisp_api = enablebanking.AISPApi(enablebanking.ApiClient(
'Bank name',
{
# Bank settings
}))
accounts = aisp_api.get_accounts()
import com.enablebanking.ApiClient;
import com.enablebanking.api.AispApi;
import com.enablebanking.model.*;
// To be replaced with real connector settings class and set properties
ConnectorSettings connectorSettings = new SomeBankConnectorSettings();
AispApi aispApi = new AispApi(new ApiClient(connectorSettings));
HalAccounts accounts = aispApi.getAccounts();
Retrieval of the PSU accounts (AISP)
Description
This call returns all payment accounts that are relevant the PSU on behalf of whom the AISP is connected. Thanks to HYPERMEDIA, each account is returned with the links aiming to ease access to the relevant transactions and balances. The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the first, next, previous or last page of results.Prerequisites
- The TPP has been registered by the Registration Authority for the AISP role.
- The TPP and the PSU have a contract that has been enrolled by the ASPSP
- At this step, the ASPSP has delivered an OAUTH2 "Authorization Code" or "Resource Owner Password" access token to the TPP (cf. § 3.4.2).
- The TPP and the ASPSP have successfully processed a mutual check and authentication
- The TPP has presented its OAUTH2 "Authorization Code" or "Resource Owner Password" access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
- The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
Business Flow
The TPP sends a request to the ASPSP for retrieving the list of the PSU payment accounts. The ASPSP computes the relevant PSU accounts and builds the answer as an accounts list. The result may be subject to pagination in order to avoid an excessive result set. Each payment account will be provided with its characteristics.Returned value
Data type: HalAccounts
Returned value consists of the list of the accounts that have been made available to the AISP by the PSU and HYPERMEDIA links to the related resources provided by ASPSP through the API.
Exceptions
Data type | Description |
---|---|
HttpException | Raised when ASPSP API responses with unspecified error. |
DataRetrievalException | Raised when unable to retrieve data requested from ASPSP API. |
InsufficientScopeException | Raised when consent given by the PSU does not allow to retrieve requested data. |
getAccountBalances
Code samples
const enablebanking = require('enablebanking');
const aispApi = new enablebanking.AISPApi(
new enablebanking.ApiClient('Bank name', [ /* Bank settings */ ]));
const balances = await aispApi.getAccountBalances('203059694928560295396833');
import enablebanking
aisp_api = enablebanking.AISPApi(enablebanking.ApiClient(
'Bank name',
{
# Bank settings
}))
balances = aisp_api.get_account_balances('203059694928560295396833')
import com.enablebanking.ApiClient;
import com.enablebanking.api.AispApi;
import com.enablebanking.model.*;
// To be replaced with real connector settings class and set properties
ConnectorSettings connectorSettings = new SomeBankConnectorSettings();
AispApi aispApi = new AispApi(new ApiClient(connectorSettings));
HalBalances balances = aispApi.getAccountBalances("203059694928560295396833")
Retrieval of an account balances report (AISP)
Description
This call returns a set of balances for a given PSU account that is specified by the AISP through an account resource Identification- The ASPSP must provide at least the accounting balance on the account.
- The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible.
- Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.
Prerequisites
- The TPP has been registered by the Registration Authority for the AISP role
- The TPP and the PSU have a contract that has been enrolled by the ASPSP
- At this step, the ASPSP has delivered an OAUTH2 “Authorization Code” or “Resource Owner Password” access token to the TPP (cf. § 3.4.2).
- The TPP and the ASPSP have successfully processed a mutual check and authentication
- The TPP has presented its OAUTH2 “Authorization Code” or “Resource Owner Password” access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
- The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
- The TPP has previously retrieved the list of available accounts for the PSU
Business flow
The AISP requests the ASPSP on one of the PSU’s accounts.The ASPSP answers by providing a list of balances on this account.
- The ASPSP must provide at least the accounting balance on the account.
- The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible.
- Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.
Parameters
Name | Type | Required | Description |
---|---|---|---|
accountResourceId | string | true | Identification of account resource to fetch |
Returned value
Data type: HalBalances
Returned value consists of the list of account balances and HYPERMEDIA links to the related resources provided by ASPSP through the API.
Exceptions
Data type | Description |
---|---|
HttpException | Raised when ASPSP API responses with unspecified error. |
DataRetrievalException | Raised when unable to retrieve data requested from ASPSP API. |
InsufficientScopeException | Raised when consent given by the PSU does not allow to retrieve requested data. |
getAccountTransactions
Code samples
const enablebanking = require('enablebanking');
const aispApi = new enablebanking.AISPApi(
new enablebanking.ApiClient('Bank name', [ /* Bank settings */ ]));
const transactions = await aispApi.getAccountTransactions('203059694928560295396833');
import enablebanking
aisp_api = enablebanking.AISPApi(enablebanking.ApiClient(
'Bank name',
{
# Bank settings
}))
transactions = aisp_api.get_account_transactions('203059694928560295396833')
import com.enablebanking.ApiClient;
import com.enablebanking.api.AispApi;
import com.enablebanking.model.*;
// To be replaced with real connector settings class and set properties
ConnectorSettings connectorSettings = new SomeBankConnectorSettings();
AispApi aispApi = new AispApi(new ApiClient(connectorSettings));
HalTransactions transactions = aispApi.getAccountTransactions("203059694928560295396833");
Retrieval of an account transaction set (AISP)
Description
This call returns transactions for an account for a given PSU account that is specified by the AISP through an account resource identification. The request may use some filter parameter in order to restrict the query- on a given imputation date range
- past a given incremental technical identification
Prerequisites
- The TPP has been registered by the Registration Authority for the AISP role
- The TPP and the PSU have a contract that has been enrolled by the ASPSP
- At this step, the ASPSP has delivered an OAUTH2 "Authorization Code" or "Resource Owner Password" access token to the TPP (cf. § 3.4.2).
- The TPP and the ASPSP have successfully processed a mutual check and authentication
- The TPP has presented its OAUTH2 "Authorization Code" or "Resource Owner Password" access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) is any.
- The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
- The TPP has previously retrieved the list of available accounts for the PSU
Business flow
The AISP requests the ASPSP on one of the PSU’s accounts. It may specify some selection criteria. The ASPSP answers by a set of transactions that matches the query. The result may be subject to pagination in order to avoid an excessive result set.Parameters
Name | Type | Required | Description |
---|---|---|---|
accountResourceId | string | true | Identification of account resource to fetch |
dateFrom | string(date-time) | false | Inclusive minimal imputation date of the transactions. |
dateTo | string(date-time) | false | Exclusive maximal imputation date of the transactions. |
afterEntryReference | string | false | Specifies the value on which the result has to be computed. |
transactionStatus | TransactionStatus | false | Transactions having a transactionStatus equal to this parameter are included within the result. |
Detailed descriptions
dateFrom: Inclusive minimal imputation date of the transactions.
Transactions having an imputation date equal to this parameter are included within the result.
dateTo: Exclusive maximal imputation date of the transactions.
Transactions having an imputation date equal to this parameter are not included within the result.
afterEntryReference: Specifies the value on which the result has to be computed.
Only the transaction having a technical identification greater than this value must be included within the result
Enumerated Values
transactionStatus
Value | Description |
---|---|
BOOK | (ISO20022 ClosingBooked) Accounted transaction |
CNCL | Cancelled transaction |
HOLD | Account hold |
OTHR | Transaction with unknown status or not fitting the other options |
PDNG | (ISO20022 Expected) Instant Balance Transaction |
RJCT | Rejected transaction |
SCHD | Scheduled transaction |
Returned value
Data type: HalTransactions
Complete transactions response
Exceptions
Data type | Description |
---|---|
HttpException | Raised when ASPSP API responses with unspecified error. |
DataRetrievalException | Raised when unable to retrieve data requested from ASPSP API. |
InsufficientScopeException | Raised when consent given by the PSU does not allow to retrieve requested data. |
modifyConsents
Code samples
const enablebanking = require('enablebanking');
const aispApi = new enablebanking.AISPApi(
new enablebanking.ApiClient('Bank name', [ /* Bank settings */ ]));
const consent = await aispApi.modifyConsents({
access: {
balances: ['203059694928560295396833'],
transactions: [],
trustedBeneficiaries: false,
psuIdentity: true
}
});
import enablebanking
aisp_api = enablebanking.AISPApi(enablebanking.ApiClient(
'Bank name',
{
# Bank settings
}))
consent = aisp_api.modify_consents(
access=enablebanking.Access(
# default access to balances
balances=enablebanking.BalancesAccess(),
# default access to transactions
transactions=enablebanking.TransacrionsAccess(),
trusted_beneficiaries=False,
psu_identity=True,
),
)
import com.enablebanking.ApiClient;
import com.enablebanking.api.AispApi;
import com.enablebanking.model.*;
// To be replaced with real connector settings class and set properties
ConnectorSettings connectorSettings = new SomeBankConnectorSettings();
AispApi aispApi = new AispApi(new ApiClient(connectorSettings));
Consent consent = aispApi.modifyConsents(
new Access()
.balances(new BalancesAccess()) // default access to balances
.transactions(new TransactionsAccess()) // default access to transactions
.trustedBeneficiaries(false)
.psuIdentity(true));
Forwarding the PSU consent (AISP)
Description
In the mixed detailed consent on accounts- the AISP captures the consent of the PSU
- then it forwards this consent to the ASPSP
Prerequisites
- The TPP has been registered by the Registration Authority for the AISP role.
- The TPP and the PSU have a contract that has been enrolled by the ASPSP
- At this step, the ASPSP has delivered an OAUTH2 "Authorization Code" or "Resource Owner Password" access token to the TPP (cf. § 3.4.2).
- The TPP and the ASPSP have successfully processed a mutual check and authentication
- The TPP has presented its OAUTH2 "Authorization Code" or "Resource Owner Password" access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
- The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
Business Flow
The PSU specifies to the AISP which of his/her accounts will be accessible and which functionalities should be available. The AISP forwards these settings to the ASPSP. The ASPSP answers by HTTP201 return code.Parameters
Name | Type | Required | Description |
---|---|---|---|
redirect_uri | string | false | none |
access | Access | false | List of consents granted to the AISP by the PSU. |
Returned value
Data type: Consent
Created or modified consent
Exceptions
Data type | Description |
---|---|
HttpException | Raised when ASPSP API responses with unspecified error. |
getCurrentConsent
Code samples
const enablebanking = require('enablebanking');
const aispApi = new enablebanking.AISPApi(
new enablebanking.ApiClient('Bank name', [ /* Bank settings */ ]));
const consent = await aispApi.getCurrentConsent();
import enablebanking
aisp_api = enablebanking.AISPApi(enablebanking.ApiClient(
'Bank name',
{
# Bank settings
}))
consent = aisp_api.get_current_consent()
import com.enablebanking.ApiClient;
import com.enablebanking.api.AispApi;
import com.enablebanking.model.*;
// To be replaced with real connector settings class and set properties
ConnectorSettings connectorSettings = new SomeBankConnectorSettings();
AispApi aispApi = new AispApi(new ApiClient(connectorSettings));
Consent consent = aispApi.getCurrentConsent();
Returns current consent (AISP)
Description
Returned value
Data type: Consent
Current consent used for accessing AIS APIs.
PISP API
makePaymentRequest
Code samples
const enablebanking = require('enablebanking');
const pispApi = new enablebanking.PISPApi(
new enablebanking.ApiClient('Bank name', [ /* Bank settings */ ]));
// Making payment request with credit transafer transaction of one element
const requestCreation = await pispApi.makePaymentRequest({
creditTransferTransaction: [{
instructedAmount: {
amount: '12.25', // amount
currency: 'EUR' // currency code
},
beneficiary: {
creditor: {
name: 'Creditor Name' // payee (merchant) name
},
creditorAccount: {
iban: 'FI4966010005485495' // payee account number
}
}
}],
debtor: {
name: 'Debtor Name' // payer (account holder) name
},
debtorAccount: {
iban: 'FI3839390001384700' // payer account number
}
});
import enablebanking
pisp_api = enablebanking.PISPApi(enablebanking.ApiClient(
'Bank name',
{
# Bank settings
}))
# Making payment request with credit transafer transaction of one element
request_creation = pisp_api.make_payment_request(
enablebanking.PaymentRequestResource(
credit_transfer_transaction=[
enablebanking.CreditTransferTransaction(
instructed_amount=enablebanking.AmountType(
amount='12.25', # amount
currency='EUR'), # currency code
beneficiary=enablebanking.Beneficiary(
creditor=enablebanking.PartyIdentification(
name='Creditor Name'), # payee (merchant) name
creditor_account=enablebanking.AccountIdentification(
iban='FI4966010005485495'), # payee account number
),
),
],
debtor=enablebanking.PartyIdentification(
name='Debtor Name'), # payer (account holder) name
debtor_account=enablebanking.AccountIdentification(
iban='FI3839390001384700'), # payer account number
))
import java.math.BigDecimal;
import java.util.Arrays;
import com.enablebanking.ApiClient;
import com.enablebanking.api.PispApi;
import com.enablebanking.model.*;
// To be replaced with real connector settings class and set properties
ConnectorSettings connectorSettings = new SomeBankConnectorSettings();
PispApi pispApi = new PispApi(new ApiClient(connectorSettings));
// Making payment request with credit transafer transaction of one element
HalPaymentRequestCreation requestCreation = pispApi.makePaymentRequest(
new PaymentRequestResource()
.creditTransferTransaction(Arrays.asList(
new CreditTransferTransaction()
.instructedAmount(
new AmountType()
.currency("EUR")
.amount(new BigDecimal("12.25")))
.beneficiary(
new Beneficiary()
.creditor(
new PartyIdentification()
.name("Creditor Name"))
.creditorAccount(
new AccountIdentification()
.iban("FI4966010005485495")))))
.debtor(
new PartyIdentification()
.name("Debtor Name"))
.debtorAccount(
new AccountIdentification()
.iban("FI3839390001384700")));
Payment request initiation (PISP)
Description
The following use cases can be applied:- payment request on behalf of a merchant
- transfer request on behalf of the account's owner
- standing-order request on behalf of the account's owner
Data content
A payment request or a transfer request might embed several payment instructions having- one single execution date or multiple execution dates
- case of one single execution date, this date must be set at the payment level
- case of multiple execution dates, those dates must be set at each payment instruction level
- one single beneficiary or multiple beneficiaries
- case of one single beneficiary, this beneficiary must be set at the payment level
- case of multiple beneficiaries, those beneficiaries must be set at each payment instruction level
- The beneficiary must be set at the payment level
- The standing order specific characteristics (start date, periodicity...) must be set at the instruction level
Prerequisites for all use cases
- The TPP has been registered by the Registration Authority for the PISP role
- The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).
- The TPP and the ASPSP have successfully processed a mutual check and authentication
- The TPP has presented its "OAUTH2 Client Credential" access token
Business flow
Payment Request use case
The PISP forwards a payment request on behalf of a merchant.The PSU buys some goods or services on an e-commerce website held by a merchant. Among other payment method, the merchant suggests the use of a PISP service. As there is obviously a contract between the merchant and the PISP, there is no need of such a contract between the PSU and this PISP to initiate the process.
Case of the PSU that chooses to use the PISP service:
- The merchant forwards the requested payment characteristics to the PISP and redirects the PSU to the PISP portal.
- The PISP requests from the PSU which ASPSP will be used.
- The PISP prepares the Payment Request and sends this request to the ASPSP.
- The Request can embed several payment instructions having different requested execution date.
- The beneficiary, as being the merchant, is set at the payment level.
Transfer Request use case
The PISP forwards a transfer request on behalf of the owner of the account.- The PSU provides the PISP with all information needed for the transfer.
- The PISP prepares the Transfer Request and sends this request to the relevant ASPSP that holds the debtor account.
- The Request can embed several payment instructions having different beneficiaries.
- The requested execution date, as being the same for all instructions, is set at the payment level.
Standing Order Request use case
The PISP forwards a Standing Order request on behalf of the owner of the account.- The PSU provides the PISP with all information needed for the Standing Order.
- The PISP prepares the Standing Order Request and sends this request to the relevant ASPSP that holds the debtor account.
- The Request embeds one single payment instruction with
- The requested execution date of the first occurrence
- The requested execution frequency of the payment in order to compute further execution dates
- An execution rule to handle cases when the computed execution dates cannot be processed (e.g. bank holydays)
- An optional end date for closing the standing Order
Authentication flows for all use cases
As the request posted by the PISP to the ASPSP needs a PSU authentication before execution, this request will include:- The specification of the authentication approaches that are supported by the PISP (any combination of "REDIRECT", "EMBEDDED" and "DECOUPLED" values).
- In case of possible REDIRECT or DECOUPLED authentication approach, one or two call-back URLs to be used by the ASPSP at the finalisation of the authentication and consent process :
- The first call-back URL will be called by the ASPSP if the Payment Request is processed without any error or rejection by the PSU
- The second call-back URL is to be used by the ASPSP in case of processing error or rejection by the PSU. Since this second URL is optional, the PISP might not provide it. In this case, the ASPSP will use the same URL for any processing result.
- Both call-back URLS must be used in a TLS-secured request.
- In case of possible "EMBEDDED" or "DECOUPLED" approaches, the PSU identifier that can be processed by the ASPSP for PSU recognition must have been set within the request body [debtor] structure.
- A location link of the saved Request that will be further used to retrieve the Request and its status information.
- The specification of the chosen authentication approach taking into account both the PISP and the PSU capabilities.
- In case of chosen REDIRECT authentication approach, the URL to be used by the PISP for redirecting the PSU in order to perform a authentication.
Redirect authentication approach
When the chosen authentication approach within the ASPSP answers is set to "REDIRECT":- The PISP redirects the PSU to the ASPSP which authenticates the PSU
- The ASPSP asks the PSU to give (or deny) his/her consent to the Payment Request
- The PSU chooses or confirms which of his/her accounts shall be used by the ASPSP for the future Credit Transfer.
- The ASPSP is then able to initiate the subsequent Credit Transfer
- The ASPSP redirects the PSU to the PISP using one of the call-back URLs provided within the posted Payment Request
Decoupled authentication approach
When the chosen authentication approach is "DECOUPLED":- Based on the PSU identifier provided within the Payment Request by the PISP, the ASPSP gives the PSU with the Payment Request details and challenges the PSU for a Strong Customer Authentication on a decoupled device or application.
- The PSU chooses or confirms which of his/her accounts shall be used by the ASPSP for the future Credit Transfer.
- The ASPSP is then able to initiate the subsequent Credit Transfer
- The ASPSP notifies the PISP about the finalisation of the authentication and consent process by using one of the call-back URLs provided within the posted Payment Request
Embedded authentication approach
When the chosen authentication approach within the ASPSP answers is set to "EMBEDDED":- The TPP informs the PSU that a challenge is needed for completing the Payment Request processing. This challenge will be one of the following:
- A One-Time-Password sent by the ASPSP to the PSU on a separate device or application.
- A response computed by a specific device on base of a challenge sent by the ASPSP to the PSU on a separate device or application.
- The PSU unlock the device or application through a "knowledge factor" and/or an "inherence factor" (biometric), retrieves the Payment Request details and processes the data sent by the ASPSP;
- The PSU might choose or confirm which of his/her accounts shall be used by the ASPSP for the future Credit Transfer when the device or application allows it.
- When agreeing the Payment Request, the PSU enters the resulting authentication factor through the PISP interface which will forward it to the ASPSP through a confirmation request (cf. § 4.7)
Parameters
Name | Type | Required | Description |
---|---|---|---|
paymentRequest | PaymentRequestResource | true | ISO20022 based payment Initiation Request |
Returned value
Data type: HalPaymentRequestCreation
The request has been created as a resource. The ASPSP must authenticate the PSU.
Exceptions
Data type | Description |
---|---|
HttpException | Raised when ASPSP API responses with unspecified error. |
getPaymentRequest
Retrieval of a payment request (PISP)
Description
The following use cases can be applied:- retrieval of a payment request on behalf of a merchant
- retrieval of a transfer request on behalf of the account's owner
- retrieval of a standing-order request on behalf of the account's owner
The ASPSP has registered the Request, updated if necessary the relevant identifiers in order to avoid duplicates and returned the location of the updated Request.
The PISP gets the Request that might have been updated with the resource identifiers, the status of the Payment/Transfer Request and the status of the subsequent credit transfer.
Prerequisites
- The TPP has been registered by the Registration Authority for the PISP role
- The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).
- The TPP has previously posted a Request which has been saved by the ASPSP (cf. § 4.5.3)
- The ASPSP has answered with a location link to the saved Payment/Transfer Request (cf. § 4.5.4)
- The TPP and the ASPSP have successfully processed a mutual check and authentication
- The TPP has presented its "OAUTH2 Client Credential" access token
Business flow
The PISP asks to retrieve the Payment/Transfer Request that has been saved by the ASPSP. The PISP uses the location link provided by the ASPSP in response of the posting of this request.The ASPSP returns the previously posted Payment/Transfer Request which is enriched with:
- The resource identifiers given by the ASPSP
- The status information of the Payment Request and of the subsequent credit transfer
Parameters
Name | Type | Required | Description |
---|---|---|---|
paymentRequestResourceId | string | true | Identification of the Payment Request Resource |
Returned value
Data type: HalPaymentRequest
Retrieval of the previously posted Payment Request
Exceptions
Data type | Description |
---|---|
HttpException | Raised when ASPSP API responses with unspecified error. |
modifyPaymentRequest
Modification of a Payment/Transfer Request (PISP)
Description
The PISP sent a Payment/Transfer Request through a POST command.The ASPSP registered the Payment/Transfer Request, updated if necessary the relevant identifiers in order to avoid duplicates and returned the location of the updated Request.
The PISP got the Payment/Transfer Request that might have been updated with the resource identifiers, the status of the Payment/Transfer Request and the status of the subsequent credit transfer.
The PISP request for the payment cancellation or for some payment instructions cancellation
No other modification of the Payment/Transfer Request is allowed.
Prerequisites
- The TPP was registered by the Registration Authority for the PISP role
- The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).
- The TPP previously posted a Payment/Transfer Request which was saved by the ASPSP (cf. § 4.5.3)
- The ASPSP answered with a location link to the saved Payment/Transfer Request (cf. § 4.5.4)
- The PISP retrieved the saved Payment/Transfer Request (cf. § 4.5.4)
- The TPP and the ASPSP successfully processed a mutual check and authentication
- The TPP presented its "OAUTH2 Client Credential" access token.
- The TPP presented the payment/transfer request.
- The PSU was successfully authenticated.
Business flow
the following cases can be applied:- Case of a payment with multiple instructions or a standing order, the PISP asks to cancel the whole Payment/Transfer or Standing Order Request including all non-executed payment instructions by setting the [paymentInformationStatus] to "RJCT" and the relevant [statusReasonInformation] to "DS02" at payment level.
- Case of a payment with multiple instructions, the PISP asks to cancel one or several payment instructions by setting the [transactionStatus] to "RJCT" and the relevant [statusReasonInformation] to "DS02" at each relevant instruction level.
- The specification of the authentication approaches that are supported by the PISP (any combination of "REDIRECT", "EMBEDDED" and "DECOUPLED" values).
- In case of possible REDIRECT or DECOUPLED authentication approach, one or two call-back URLs to be used by the ASPSP at the finalisation of the authentication and consent process :
- The first call-back URL will be called by the ASPSP if the Transfer Request is processed without any error or rejection by the PSU
- The second call-back URL is to be used by the ASPSP in case of processing error or rejection by the PSU. Since this second URL is optional, the PISP might not provide it. In this case, the ASPSP will use the same URL for any processing result.
- Both call-back URLS must be used in a TLS-secured request, including mutual authentication based on each party’s TLS certificate.
- In case of possible "EMBEDDED" or "DECOUPLED" approaches, a PSU identifier that can be processed by the ASPSP for PSU recognition.
- The specification of the chosen authentication approach taking into account both the PISP and the PSU capabilities.
- In case of chosen REDIRECT authentication approach, the URL to be used by the PISP for redirecting the PSU in order to perform an authentication.
Authentication flows for both use cases
Redirect authentication approach
When the chosen authentication approach within the ASPSP answers is set to "REDIRECT":- The PISP redirects the PSU to the ASPSP which authenticates the PSU
- The ASPSP asks the PSU to give (or deny) his/her consent to the Payment Request
- The PSU chooses or confirms which of his/her accounts shall be used by the ASPSP for the future Credit Transfer.
- The ASPSP is then able to initiate the subsequent Credit Transfer
- The ASPSP redirects the PSU to the PISP using one of the call-back URLs provided within the posted Payment Request
Decoupled authentication approach
When the chosen authentication approach is "DECOUPLED":- Based on the PSU identifier provided within the Payment Request by the PISP, the ASPSP gives the PSU with the Payment Request details and challenges the PSU for a Strong Customer Authentication on a decoupled device or application.
- The PSU chooses or confirms which of his/her accounts shall be used by the ASPSP for the future Credit Transfer.
- The ASPSP is then able to initiate the subsequent Credit Transfer
- The ASPSP notifies the PISP about the finalisation of the authentication and consent process by using one of the call-back URLs provided within the posted Payment Request
Embedded authentication approach
When the chosen authentication approach within the ASPSP answers is set to "EMBEDDED":- The TPP informs the PSU that a challenge is needed for completing the Payment Request processing. This challenge will be one of the following:
- A One-Time-Password sent by the ASPSP to the PSU on a separate device or application.
- A response computed by a specific device on base of a challenge sent by the ASPSP to the PSU on a separate device or application.
- The PSU unlock the device or application through a "knowledge factor" and/or an "inherence factor" (biometric), retrieves the Payment Request details and processes the data sent by the ASPSP;
- The PSU might choose or confirm which of his/her accounts shall be used by the ASPSP for the future Credit Transfer when the device or application allows it.
- When agreeing the Payment Request, the PSU enters the resulting authentication factor through the PISP interface which will forward it to the ASPSP through a confirmation request (cf. § 4.7)
Parameters
Name | Type | Required | Description |
---|---|---|---|
paymentRequestResourceId | string | true | Identification of the Payment Request Resource |
paymentRequest | PaymentRequestResource | true | ISO20022 based payment Initiation Request |
Returned value
Data type: HalPaymentRequestCreation
The modification request has been saved. The ASPSP must authenticate the PSU before committing the update.
Exceptions
Data type | Description |
---|---|
HttpException | Raised when ASPSP API responses with unspecified error. |
makePaymentRequestConfirmation
Confirmation of a payment request or a modification request (PISP)
Description
The PISP confirms one of the following requests- payment request on behalf of a merchant
- transfer request on behalf of the account's owner
- standing-order request on behalf of the account's owner
Prerequisites
- The TPP has been registered by the Registration Authority for the PISP role
- The TPP was provided with an OAUTH2 "Client Credential" access token by the ASPSP (cf. § 3.4.3).
- The TPP has previously posted a Request which has been saved by the ASPSP (cf. § 4.5.3)
- The ASPSP has answered with a location link to the saved Payment Request (cf. § 4.5.4)
- The TPP has retrieved the saved request in order to get the relevant resource Ids (cf. § 4.6).
- The TPP and the ASPSP have successfully processed a mutual check and authentication
- The TPP has presented its "OAUTH2 Client Credential" access token
Business flow
Once the PSU has been authenticated, it is the due to the PISP to confirm the Request to the ASPSP in order to complete the process flow.In REDIRECT and DECOUPLED approach, this confirmation is not a prerequisite to the execution of the Credit Transfer.
Parameters
Name | Type | Required | Description |
---|---|---|---|
paymentRequestResourceId | string | true | Identification of the Payment Request Resource |
paymentRequestData | PaymentRequestResource | false | ISO20022 based payment Initiation Request |
confirmation | PaymentRequestConfirmation | false | parameters needed for confirmation of the Payment Request, especially in EMBEDDED approach |
Returned value
Data type: HalPaymentRequest
retrieval of the Payment Request enriched with the status report
Exceptions
Data type | Description |
---|---|
HttpException | Raised when ASPSP API responses with unspecified error. |
Data types
Auth
Fields
Name | Type | Required | Description |
---|---|---|---|
url |
string |
false |
URL for authorization |
Token
Fields
Name | Type | Required | Description |
---|---|---|---|
access_token |
string |
false |
The access token value |
token_type |
string |
false |
Type of the token is set to "Bearer" |
expires_in |
integer(int32) |
false |
The lifetime in seconds of the access token |
refresh_token |
string |
false |
The refresh token value |
scope |
string |
false |
Scopes of the token |
Enumerated Values
token_type
Value | Description |
---|---|
Bearer |
— |
HalConnectors
HYPERMEDIA structure used for returning the list of the connectors for given countries
Fields
Name | Type | Required | Description |
---|---|---|---|
connectors |
true |
List of connectors |
|
_links |
false |
links that can be used for further navigation when browsing connector information |
ConnectorsLinks
links that can be used for further navigation when browsing connector information
Fields
Name | Type | Required | Description |
---|---|---|---|
self |
true |
hypertext reference |
Connector
Information about connector used for interaction with a bank
Fields
Name | Type | Required | Description |
---|---|---|---|
name |
string |
false |
The name of connector |
countries |
[string] |
false |
The list of all countries supported by connector |
scopes |
[string] |
false |
The list of all scopes supported by connector |
AuthenticationApproach
The ASPSP, based on the authentication approaches proposed by the PISP, choose the one that it can processed, in respect with the preferences and constraints of the PSU and indicates in this field which approach has been chosen
Base type
string
Enumerated Values
Value | Description |
---|---|
REDIRECT |
the PSU is redirected by the TPP to the ASPSP which processes identification and authentication |
DECOUPLED |
the TPP identifies the PSU and forwards the identification to the ASPSP which processes the authentication through a decoupled device |
EMBEDDED |
the TPP identifies the PSU and forwards the identification to the ASPSP which starts the authentication. The TPP forwards one authentication factor of the PSU (e.g. OTP or response to a challenge) |
GenericIdentification
ISO20022: Unique identification of an account, a person or an organisation, as assigned by an issuer. API: The ASPSP will document which account reference type it will support.
Fields
Name | Type | Required | Description |
---|---|---|---|
identification |
string |
true |
API Identifier |
schemeName |
string |
true |
Name of the identification scheme. Partially based on ISO20022 external code list |
issuer |
string |
false |
ISO20022: Entity that assigns the identification. this could a country code or any organisation name or identifier that can be recognized by both parties |
Enumerated Values
schemeName
Value | Description |
---|---|
BANK |
BankPartyIdentification. Unique and unambiguous assignment made by a specific bank or similar financial institution to identify a relationship as defined between the bank and its client. |
COID |
CountryIdentificationCode. Country authority given organisation identification (e.g., corporate registration number) |
SREN |
The SIREN number is a 9 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation in France. |
SRET |
The SIRET number is a 14 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation unit in France. It consists of the SIREN number, followed by a five digit classification number, to identify the local geographical unit of that entity. |
NIDN |
NationalIdentityNumber. Number assigned by an authority to identify the national identity number of a person. |
OAUT |
OAUTH2 access token that is owned by the PISP being also an AISP and that can be used in order to identify the PSU |
CPAN |
Card PAN |
BBAN |
Basic Bank Account Number. Represents a country-specific bank account number. |
AccountIdentification
Unique and unambiguous identification for the account between the account owner and the account servicer.
Fields
Name | Type | Required | Description |
---|---|---|---|
iban |
string |
false |
ISO20022: International Bank Account Number (IBAN) - identification used internationally by financial institutions to uniquely identify the account of a customer. Further specifications of the format and content of the IBAN can be found in the standard ISO 13616 "Banking and related financial services - International Bank Account Number (IBAN)" version 1997-10-01, or later revisions. |
other |
false |
ISO20022: Unique identification of an account, a person or an organisation, as assigned by an issuer. |
AmountType
ISO20022: structure aiming to carry either an instructed amount or equivalent amount. Both structures embed the amount and the currency to be used.
API: only instructed amount can be used
Fields
Name | Type | Required | Description |
---|---|---|---|
currency |
string |
true |
Specifies the currency of the amount. A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds". |
amount |
string(number) |
true |
ISO20022: Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. |
BankTransactionCode
ISO20022: Allows the account servicer to correctly report a transaction, which in its turn will help account owners to perform their cash management and reconciliation operations.
Fields
Name | Type | Required | Description |
---|---|---|---|
code |
string |
false |
ISO20022: Specifies the family of a transaction within the domain |
subCode |
string |
false |
ISO20022: Specifies the sub-product family of a transaction within a specific family |
ClearingSystemMemberIdentification
ISO20022: Information used to identify a member within a clearing system. API: to be used for some specific international credit transfers in order to identify the beneficiary bank
Fields
Name | Type | Required | Description |
---|---|---|---|
clearingSystemId |
string |
false |
ISO20022: Specification of a pre-agreed offering between clearing agents or the channel through which the payment instruction is processed. |
memberId |
string |
false |
ISO20022: Identification of a member of a clearing system. |
FinancialInstitutionIdentification
ISO20022: Unique and unambiguous identification of a financial institution, as assigned under an internationally recognised or proprietary identification scheme.
Fields
Name | Type | Required | Description |
---|---|---|---|
bicFi |
string |
true |
ISO20022: Code allocated to a financial institution by the ISO 9362 Registration Authority as described in ISO 9362 "Banking - Banking telecommunication messages - Business identification code (BIC)". |
clearingSystemMemberId |
false |
ISO20022: Information used to identify a member within a clearing system. |
|
name |
string |
false |
Name of the financial institution |
postalAddress |
false |
ISO20022 : Information that locates and identifies a specific address, as defined by postal services. |
PostalAddress
ISO20022 : Information that locates and identifies a specific address, as defined by postal services.
Fields
Name | Type | Required | Description |
---|---|---|---|
country |
string |
true |
ISO20022: Country in which a person resides (the place of a person's home). In the case of a company, it is the country from which the affairs of that company are directed. |
addressLine |
[string] |
true |
Unstructured address. The two lines must embed zip code and town name |
PartyIdentification
API : Description of a Party which can be either a person or an organization.
Fields
Name | Type | Required | Description |
---|---|---|---|
name |
string |
true |
ISO20022: Name by which a party is known and which is usually used to identify that party. |
postalAddress |
false |
ISO20022 : Information that locates and identifies a specific address, as defined by postal services. |
|
organisationId |
false |
Unique and unambiguous way to identify an organisation. |
|
privateId |
false |
Unique and unambiguous identification of a person. |
ResourceId
Identifier assigned by the ASPSP for further use of the created resource through API calls
Base type
string
PaymentIdentification
ISO20022: Set of elements used to reference a payment instruction.
Fields
Name | Type | Required | Description |
---|---|---|---|
resourceId |
false |
Identifier assigned by the ASPSP for further use of the created resource through API calls |
|
instructionId |
string |
false |
ISO20022: Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction. API: Unique identification shared between the PISP and the ASPSP |
endToEndId |
string |
false |
ISO20022: Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. API: Unique identification shared between the merchant and the PSU |
PriorityCode
ISO20022: Indicator of the urgency or order of importance that the instructing party would like the instructed party to apply to the processing of the instruction.
Base type
string
Enumerated Values
Value | Description |
---|---|
HIGH |
High priority |
NORM |
Normal priority |
CategoryPurposeCode
ISO20022: Specifies the high level purpose of the instruction based on a set of pre-defined categories. This is used by the initiating party to provide information concerning the processing of the payment. It is likely to trigger special processing by any of the agents involved in the payment chain.
Base type
string
Enumerated Values
Value | Description |
---|---|
CASH |
Transaction is a general cash management instruction (CashManagementTransfer). |
DVPM |
Code used to pre-advise the account servicer of a forthcoming deliver against payment instruction (DeliverAgainstPayment). |
ServiceLevelCode
ISO20022: Agreement under which or rules under which the transaction should be processed. Specifies a pre-agreed service or level of service between the parties, as published in an external service level code list.
Base type
string
Enumerated Values
Value | Description |
---|---|
NURG |
Other Credit Transfer |
SEPA |
SEPA Credit Transfer |
LocalInstrumentCode
ISO20022: User community specific instrument. Usage: This element is used to specify a local instrument, local clearing option and/or further qualify the service or service level.
Base type
string
PaymentTypeInformation
ISO20022: Set of elements used to further specify the type of transaction.
Fields
Name | Type | Required | Description |
---|---|---|---|
instructionPriority |
false |
ISO20022: Indicator of the urgency or order of importance that the instructing party would like the instructed party to apply to the processing of the instruction. |
|
serviceLevel |
false |
ISO20022: Agreement under which or rules under which the transaction should be processed. Specifies a pre-agreed service or level of service between the parties, as published in an external service level code list. |
|
localInstrument |
false |
ISO20022: User community specific instrument. |
|
categoryPurpose |
false |
ISO20022: Specifies the high level purpose of the instruction based on a set of pre-defined categories. This is used by the initiating party to provide information concerning the processing of the payment. It is likely to trigger special processing by any of the agents involved in the payment chain. |
PurposeCode
ISO20022: Underlying reason for the payment transaction, as published in an external purpose code list.
Base type
string
Enumerated Values
Value | Description |
---|---|
ACCT |
Funds moved between 2 accounts of same account holder at the same bank. |
CASH |
general cash management instruction, may be used for Transfer Initiation. |
COMC |
Transaction is related to a payment of commercial credit or debit. |
CPKC |
General Carpark Charges Transaction is related to carpark charges. |
TRPT |
Transport RoadPricing Transaction is for the payment to top-up pre-paid card and electronic road pricing for the purpose of transportation. |
ChargeBearerCode
ISO20022: Specifies which party/parties will bear the charges associated with the processing of the payment transaction.
Base type
string
Enumerated Values
Value | Description |
---|---|
SLEV |
Service level. Charges are to be applied following the rules agreed in the service level and/or scheme. |
SHAR |
Shared. |
UnstructuredRemittanceInformation
ISO20022: Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system. API: Only one occurrence is allowed
Fields
Name | Type | Required | Description |
---|---|---|---|
remittanceLine |
string |
false |
Relevant information to the transaction |
PaymentInformationStatusCode
ISO20022: Specifies the status of the payment information.
Base type
string
Enumerated Values
Value | Description |
---|---|
ACCP |
AcceptedCustomerProfile. Preceding check of technical validation was successful. Customer profile check was also successful. |
ACSC |
AcceptedSettlementCompleted. Settlement on the debtor's account has been completed. |
ACSP |
AcceptedSettlementInProcess. All preceding checks such as technical validation and customer profile were successful. Dynamic risk assessment is now also successful and therefore the Payment Request has been accepted for execution. |
ACTC |
AcceptedTechnicalValidation. Authentication and syntactical and semantical validation are successful. |
ACWC |
AcceptedWithChange. Instruction is accepted but a change will be made, such as date or remittance not sent. |
ACWP |
AcceptedWithoutPosting. Payment instruction included in the credit transfer is accepted without being posted to the creditor customer’s account. |
PART |
PartiallyAccepted. A number of transactions have been accepted, whereas another number of transactions have not yet achieved 'accepted' status. |
RCVD |
Received. Payment initiation has been received by the receiving agent. |
PDNG |
Pending. Payment request or individual transaction included in the Payment Request is pending. Further checks and status update will be performed. |
RJCT |
Rejected. Payment request has been rejected. |
TransactionIndividualStatusCode
ISO20022: Specifies the status of the payment information group.
Base type
string
Enumerated Values
Value | Description |
---|---|
RCVD |
Payment request or individual transaction included in the Payment Request has been received by the receiving agent. |
RJCT |
Payment request or individual transaction included in the Payment Request has been rejected. |
PDNG |
Pending. Payment request or individual transaction included in the Payment Request is pending. Further checks and status update will be performed. |
ACSP |
All preceding checks such as technical validation and customer profile were successful and therefore the Payment Request has been accepted for execution. |
ACSC |
Settlement on the debtor's account has been completed. |
StatusReasonInformation
ISO20022: Provides detailed information on the status reason. Can only be used in status equal to "RJCT".
Base type
string
Enumerated Values
Value | Description |
---|---|
AC01 |
IncorectAccountNumber. the account number is either invalid or does not exist |
AC04 |
ClosedAccountNumber. the account is closed and cannot be used |
AC06 |
BlockedAccount. the account is blocked and cannot be used |
AG01 |
Transaction forbidden. Transaction forbidden on this type of account |
CH03 |
RequestedExecutionDateOrRequestedCollectionDateTooFarInFuture. The requested execution date is too far in the future |
CUST |
RequestedByCustomer. The reject is due to the debtor (refusal or lack of liquidity) |
DS02 |
OrderCancelled. An authorized user has cancelled the order |
FF01 |
InvalidFileFormat. The reject is due to the original Payment Request which is invalid (syntax, structure or values) |
FRAD |
FraudulentOriginated. the Payment Request is considered as fraudulent |
MS03 |
NotSpecifiedReasonAgentGenerated. No reason specified by the ASPSP |
NOAS |
NoAnswerFromCustomer. The PSU has neither accepted nor rejected the Payment Request and a time-out has occurred |
RR01 |
MissingDebtorAccountOrIdentification. The Debtor account and/or Identification are missing or inconsistent |
RR03 |
MissingCreditorNameOrAddress. Specification of the creditor’s name and/or address needed for regulatory requirements is insufficient or missing. |
RR04 |
RegulatoryReason. Reject from regulatory reason |
RR12 |
InvalidPartyID. Invalid or missing identification required within a particular country or payment type. |
RegulatoryReportingCode
Information needed due to regulatory and statutory requirements. Economical codes to be used are provided by the National Competent Authority
Base type
string
RegulatoryReportingCodes
List of needed regulatory reporting codes for international payments
Base type
RequestedExecutionDate
ISO20022: Date at which the initiating party requests the clearing agent to process the payment. API: This date can be used in the following cases:
- the single requested execution date for a payment having several instructions. In this case, this field must be set at the payment level.
- the requested execution date for a given instruction within a payment. In this case, this field must be set at each instruction level.
- The first date of execution for a standing order. When the payment cannot be processed at this date, the ASPSP is allowed to shift the applied execution date to the next possible execution date for non-standing orders. For standing orders, the [executionRule] parameter helps to compute the execution date to be applied.
Base type
string(date-time)
EndDate
The last applicable day of execution for a given standing order. If not given, the standing order is considered as endless.
Base type
string(date-time)
ExecutionRule
Execution date shifting rule for standing orders This data attribute defines the behaviour when recurring payment dates falls on a weekend or bank holiday. The payment is then executed either the "preceding" or "following" working day. ASPSP might reject the request due to the communicated value, if rules in Online-Banking are not supporting this execution rule.
Base type
string
Enumerated Values
Value | Description |
---|---|
FWNG |
following |
PREC |
preceding |
FrequencyCode
Frequency rule for standing orders. The following codes from the "EventFrequency7Code" of ISO 20022 are supported. However, each ASPSP might restrict these values into a subset.
Base type
string
Enumerated Values
Value | Description |
---|---|
DAIL |
Daily |
WEEK |
Weekly |
TOWK |
EveryTwoWeeks |
MNTH |
Monthly |
TOMN |
EveryTwoMonths |
QUTR |
Quarterly |
SEMI |
SemiAnnual |
YEAR |
Annual |
CreditTransferTransaction
ISO20022: Payment processes required to transfer cash from the debtor to the creditor. API:
Fields
Name | Type | Required | Description |
---|---|---|---|
paymentId |
false |
ISO20022: Set of elements used to reference a payment instruction. |
|
requestedExecutionDate |
false |
ISO20022: Date at which the initiating party requests the clearing agent to process the payment. |
|
endDate |
false |
The last applicable day of execution for a given standing order. |
|
executionRule |
false |
Execution date shifting rule for standing orders |
|
frequency |
false |
Frequency rule for standing orders. |
|
instructedAmount |
true |
ISO20022: structure aiming to carry either an instructed amount or equivalent amount. Both structures embed the amount and the currency to be used. |
|
beneficiary |
true |
Specification of a beneficiary |
|
ultimateCreditor |
false |
API : Description of a Party which can be either a person or an organization. |
|
regulatoryReportingCodes |
false |
List of needed regulatory reporting codes for international payments |
|
remittanceInformation |
false |
ISO20022: Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system. |
|
transactionStatus |
false |
ISO20022: Specifies the status of the payment information group. |
|
statusReasonInformation |
false |
ISO20022: Provides detailed information on the status reason. Can only be used in status equal to "RJCT". |
BalanceStatus
Type of balance
Base type
string
Enumerated Values
Value | Description |
---|---|
CLBD |
(ISO20022 ClosingBooked) Accounting Balance |
FWAV |
(ISO20022 ForwardAvailable) Balance of money that is at the disposal of the account owner on the date specified |
ITAV |
(ISO20022 InterimAvailable) Available balance calculated in the course of the day |
ITBD |
(ISO20022 InterimBooked) Booked balance calculated in the course of the day |
OTHR |
Other Balance |
VALU |
Value-date balance |
XPCD |
(ISO20022 Expected) Instant Balance |
TransactionStatus
Type of Transaction
Base type
string
Enumerated Values
Value | Description |
---|---|
BOOK |
(ISO20022 ClosingBooked) Accounted transaction |
CNCL |
Cancelled transaction |
HOLD |
Account hold |
OTHR |
Transaction with unknown status or not fitting the other options |
PDNG |
(ISO20022 Expected) Instant Balance Transaction |
RJCT |
Rejected transaction |
SCHD |
Scheduled transaction |
Transaction
structure of a transaction
Fields
Name | Type | Required | Description |
---|---|---|---|
resourceId |
false |
Identifier assigned by the ASPSP for further use of the created resource through API calls |
|
entryReference |
string |
false |
Technical incremental identification of the transaction. |
transactionAmount |
true |
ISO20022: structure aiming to carry either an instructed amount or equivalent amount. Both structures embed the amount and the currency to be used. |
|
creditor |
false |
API : Description of a Party which can be either a person or an organization. |
|
debtor |
false |
API : Description of a Party which can be either a person or an organization. |
|
bankTransactionCode |
false |
ISO20022: Allows the account servicer to correctly report a transaction, which in its turn will help account owners to perform their cash management and reconciliation operations. |
|
creditDebitIndicator |
string |
true |
Accounting flow of the transaction |
status |
true |
Type of Transaction |
|
bookingDate |
string(date) |
false |
Booking date of the transaction on the account |
valueDate |
string(date) |
false |
Value date of the transaction on the account |
transactionDate |
string(date) |
false |
Date used for specific purposes:
|
remittanceInformation |
false |
ISO20022: Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system. |
Enumerated Values
creditDebitIndicator
Value | Description |
---|---|
CRDT |
Credit type transaction |
DBIT |
Debit type transaction |
AccountResource
PSU account that is made available to the TPP
Fields
Name | Type | Required | Description |
---|---|---|---|
resourceId |
false |
Identifier assigned by the ASPSP for further use of the created resource through API calls |
|
bicFi |
string |
false |
ISO20022: Code allocated to a financial institution by the ISO 9362 Registration Authority as described in ISO 9362 "Banking - Banking telecommunication messages - Business identification code (BIC)". |
accountId |
false |
Unique and unambiguous identification for the account between the account owner and the account servicer. |
|
name |
string |
true |
Label of the PSU account In case of a delayed debit card transaction set, the name shall specify the holder name and the imputation date |
details |
string |
false |
Specifications that might be provided by the ASPSP
|
linkedAccount |
string |
false |
Case of a set of pending card transactions, the APSP will provide the relevant cash account the card is set up on. |
usage |
string |
false |
Specifies the usage of the account |
cashAccountType |
string |
true |
Specifies the type of the account |
product |
string |
false |
Product Name of the Bank for this account, proprietary definition |
currency |
string |
true |
Currency used for the account |
balances |
false |
list of balances provided by the ASPSP |
|
psuStatus |
string |
false |
Relationship between the PSU and the account - Account Holder - Co-account Holder - Attorney |
_links |
true |
links that can be used for further navigation when browsing Account Information at one |
Enumerated Values
usage
Value | Description |
---|---|
PRIV |
private personal account |
ORGA |
professional account |
cashAccountType
Value | Description |
---|---|
CACC |
Account used to post debits and credits when no specific account has been nominated |
CASH |
Account used for the payment of cash |
CARD |
List of card based transactions (non ISO 20022) |
LOAN |
Loan account |
BalanceResource
Structure of an account balance
Fields
Name | Type | Required | Description |
---|---|---|---|
name |
string |
true |
Label of the balance |
balanceAmount |
true |
ISO20022: structure aiming to carry either an instructed amount or equivalent amount. Both structures embed the amount and the currency to be used. |
|
balanceType |
true |
Type of balance |
|
lastChangeDateTime |
string(date-time) |
false |
Timestamp of the last change of the balance amount |
referenceDate |
string(date) |
false |
Reference date for the balance |
lastCommittedTransaction |
string |
false |
Identification of the last committed transaction. This is actually useful for instant balance. |
PaymentRequestConfirmation
Contains data for confirmation of payment request
Fields
Name | Type | Required | Description |
---|---|---|---|
psuAuthenticationFactor |
string |
false |
authentication factor forwarded by the TPP to the ASPSP in order to fulfil the strong customer authentication process |
Consent
User consent
Fields
Name | Type | Required | Description |
---|---|---|---|
consentStatus |
string |
false |
none |
consentId |
string |
false |
none |
_links |
false |
none |
PaymentInformationId
ISO20022 : Reference assigned by a sending party to unambiguously identify the payment information block within the message.
Base type
string
CreationDateTime
ISO20022: Date and time at which a (group of) payment instruction(s) was created by the instructing party.
Base type
string(date-time)
FundsAvailabilityInformation
indicator that the payment can be covered or not by the funds available on the relevant account
- true: payment is covered
- false: payment is not covered
Base type
boolean
BookingInformation
indicator that the payment can be immediately booked or not
- true: payment is booked
- false: payment is not booked
Base type
boolean
PaymentRequestResource
ISO20022: The PaymentRequestResource message is sent by the Creditor sending party to the Debtor receiving party, directly or through agents. It is used by a Creditor to request movement of funds from the debtor account to a creditor. API: Information about the creditor (Id, account and agent) might be placed either at payment level or at instruction level. Thus multi-beneficiary payments can be handled. The requested execution date can be placed either at payment level when all instructions are requested to be executed at the same date or at instruction level. The latest case includes:
- multiple instructions having different requested execution dates
- standing orders settings
Fields
Name | Type | Required | Description |
---|---|---|---|
resourceId |
false |
Identifier assigned by the ASPSP for further use of the created resource through API calls |
|
paymentInformationId |
false |
ISO20022 : Reference assigned by a sending party to unambiguously identify the payment information block within the message. |
|
creationDateTime |
false |
ISO20022: Date and time at which a (group of) payment instruction(s) was created by the instructing party. |
|
initiatingParty |
false |
API : Description of a Party which can be either a person or an organization. |
|
paymentTypeInformation |
false |
ISO20022: Set of elements used to further specify the type of transaction. |
|
debtor |
false |
API : Description of a Party which can be either a person or an organization. |
|
debtorAccount |
true |
Unique and unambiguous identification for the account between the account owner and the account servicer. |
|
debtorAgent |
false |
ISO20022: Unique and unambiguous identification of a financial institution, as assigned under an internationally recognised or proprietary identification scheme. |
|
beneficiary |
false |
Specification of a beneficiary |
|
purpose |
false |
ISO20022: Underlying reason for the payment transaction, as published in an external purpose code list. |
|
chargeBearer |
false |
ISO20022: Specifies which party/parties will bear the charges associated with the processing of the payment transaction. |
|
paymentInformationStatus |
false |
ISO20022: Specifies the status of the payment information. |
|
statusReasonInformation |
false |
ISO20022: Provides detailed information on the status reason. Can only be used in status equal to "RJCT". |
|
fundsAvailability |
false |
indicator that the payment can be covered or not by the funds available on the relevant account |
|
booking |
false |
indicator that the payment can be immediately booked or not |
|
requestedExecutionDate |
string(date-time) |
false |
ISO20022: Date at which the initiating party requests the clearing agent to process the payment. |
creditTransferTransaction |
true |
ISO20022: Payment processes required to transfer cash from the debtor to the creditor. API: Each ASPSP will specify a maxItems value for this field taking into accounts its specificities about payment request handling |
PaymentCoverageRequestResource
Payment coverage request structure. The request must rely either on a cash account or a payment card.
Fields
Name | Type | Required | Description |
---|---|---|---|
paymentCoverageRequestId |
string |
true |
Identification of the payment Coverage Request |
payee |
string |
false |
The merchant where the card is accepted as information to the PSU. |
instructedAmount |
true |
ISO20022: structure aiming to carry either an instructed amount or equivalent amount. Both structures embed the amount and the currency to be used. |
|
accountId |
true |
Unique and unambiguous identification for the account between the account owner and the account servicer. |
HalAccounts
HYPERMEDIA structure used for returning the list of the available accounts to the AISP
Fields
Name | Type | Required | Description |
---|---|---|---|
connectedPsu |
string |
false |
Last name and first name that has granted access to the AISP on the accounts data This information can be retrieved based on the PSU's authentication that occurred during the OAUTH2 access token initialisation. |
accounts |
true |
List of PSU account that are made available to the TPP |
|
_links |
true |
Links that can be used for further navigation when browsing Account Information at top |
HalBalances
HYPERMEDIA structure used for returning the list of the relevant balances for a given account to the AISP
Fields
Name | Type | Required | Description |
---|---|---|---|
balances |
true |
List of account balances |
|
_links |
true |
links that can be used for further navigation when browsing Account Information at one |
HalTransactions
HYPERMEDIA structure used for returning the list of the transactions for a given account to the AISP
Fields
Name | Type | Required | Description |
---|---|---|---|
transactions |
true |
List of transactions |
|
_links |
true |
links that can be used for further navigation when browsing Account Information at one |
HalPaymentRequest
HYPERMEDIA structure used for returning the original Payment Request to the PISP
Fields
Name | Type | Required | Description |
---|---|---|---|
paymentRequest |
true |
ISO20022: The PaymentRequestResource message is sent by the Creditor sending party to the Debtor receiving party, directly or through agents. It is used by a Creditor to request movement of funds from the debtor account to a creditor. |
|
_links |
true |
links that can be used for further navigation when having post a Payment Request in order |
HalPaymentRequestCreation
data forwarded by the ASPSP to the PISP after creation of the Payment Request resource creation
Fields
Name | Type | Required | Description |
---|---|---|---|
paymentRequestResourceId |
false |
Identifier assigned by the ASPSP for further use of the created resource through API calls |
|
appliedAuthenticationApproach |
false |
The ASPSP, based on the authentication approaches proposed by the PISP, choose the one that it can processed, in respect with the preferences and constraints of the PSU and indicates in this field which approach has been chosen |
|
_links |
false |
Links that can be used for further navigation, especially in REDIRECT approach |
HalPaymentCoverageReport
HYPERMEDIA structure used for returning the payment coverage report to the PIISP
Fields
Name | Type | Required | Description |
---|---|---|---|
request |
true |
Payment coverage request structure. The request must rely either on a cash account or a payment card. |
|
result |
boolean |
true |
Result of the coverage check :
|
_links |
true |
links that can be used for further navigation to post another coverage request. |
Beneficiary
Specification of a beneficiary
Fields
Name | Type | Required | Description |
---|---|---|---|
id |
string |
false |
Id of the beneficiary |
isTrusted |
boolean |
false |
The ASPSP having not implemented the trusted beneficiaries list must not set this flag. Otherwise, the ASPSP indicates whether or not the beneficiary has been registered by the PSU within the trusted beneficiaries list.
|
creditorAgent |
false |
ISO20022: Unique and unambiguous identification of a financial institution, as assigned under an internationally recognised or proprietary identification scheme. |
|
creditor |
false |
API : Description of a Party which can be either a person or an organization. |
|
creditorAccount |
true |
Unique and unambiguous identification for the account between the account owner and the account servicer. |
HalBeneficiaries
HYPERMEDIA structure used for returning the list of the whitelisted beneficiaries
Fields
Name | Type | Required | Description |
---|---|---|---|
beneficiaries |
true |
List of trusted beneficiaries |
|
_links |
true |
links that can be used for further navigation when browsing Account Information at one |
BalancesAccess
Defines what access to blanaces is requested
Fields
Name | Type | Required | Description |
---|---|---|---|
statuses |
false |
List of balance statuses, which are going to be accessed |
TransactionsAccess
Defines what access to transactions is requested
Fields
Name | Type | Required | Description |
---|---|---|---|
statuses |
false |
List of transaction statuses, which are going to be accessed |
|
details |
boolean |
false |
Indicator that access to transaction details is requested |
limitDays |
integer |
false |
Number of days in the past to access transactions |
Access
Requested access services.
Fields
Name | Type | Required | Description |
---|---|---|---|
accounts |
false |
List of accounts access to which is requested. If not set behaviour depends on the bank: some banks allow users to choose list of accessible accounts through their access consent UI, while other may provide access to all accounts or just access to the list of accounts. |
|
balances |
false |
Defines how balance information is going to be accessed. If not set balances are not explicitly requested |
|
transactions |
false |
Defines how transactions are going to be accessed. If not set transactions are not explicitly requested |
|
trustedBeneficiaries |
boolean |
false |
Indicator that access to the trusted beneficiaries list was granted or not to the AISP by the PSU
|
psuIdentity |
boolean |
false |
Indicator that access to the PSU identity, first name and last name, was granted or not to the AISP by the PSU
|
accountDetails |
boolean |
false |
Indicates if access to account details if explicitly requested |
recurringIndicator |
boolean |
false |
|
frequencyPerDay |
integer |
false |
This field indicates the requested maximum frequency for an access without PSU involvement per day. For a one-off access, this attribute is set to "1". The frequency needs to be greater equal to one. |
validUntil |
string(date) |
false |
This parameter is requesting a valid until date for the requested consent. The content is the local ASPSP date in ISO-Date Format, e.g. 2017-10-30. Future dates might get adjusted by ASPSP. |
HAL
GenericLink
hypertext reference
Fields
Name | Type | Required | Description |
---|---|---|---|
href |
string |
true |
URI to be used |
templated |
boolean |
false |
specifies "true" if href is a URI template, i.e. with parameters. Otherwise, this property is absent or set to false |
AccountsLinks
Links that can be used for further navigation when browsing Account Information at top level
Fields
Name | Type | Required | Description |
---|---|---|---|
self |
true |
link to the list of all available accounts |
|
beneficiaries |
false |
hypertext reference |
|
first |
false |
hypertext reference |
|
last |
false |
hypertext reference |
|
next |
false |
hypertext reference |
|
prev |
false |
hypertext reference |
AccountLinks
links that can be used for further navigation when browsing Account Information at one account level
Fields
Name | Type | Required | Description |
---|---|---|---|
balances |
false |
link to the balances of a given account |
|
transactions |
false |
link to the transactions of a given account |
BalancesLinks
links that can be used for further navigation when browsing Account Information at one account level
Fields
Name | Type | Required | Description |
---|---|---|---|
self |
true |
link to the balances of a given account |
|
parent-list |
false |
link to the list of all available accounts |
|
transactions |
false |
link to the transactions of a given account |
TransactionsLinks
links that can be used for further navigation when browsing Account Information at one account level
Fields
Name | Type | Required | Description |
---|---|---|---|
self |
true |
link to the transactions of a given account |
|
parent-list |
false |
link to the list of all available accounts |
|
balances |
false |
link to the balances of a given account |
|
first |
false |
link to the first page of the transactions result |
|
last |
false |
link to the last page of the transactions result |
|
next |
false |
link to the next page of the transactions result |
|
prev |
false |
link to the previous page of the transactions result |
BeneficiariesLinks
links that can be used for further navigation when browsing Account Information at one account level
Fields
Name | Type | Required | Description |
---|---|---|---|
self |
true |
link to the beneficiaries |
|
parent-list |
false |
link to the list of all available accounts |
|
first |
false |
link to the first page of the beneficiaries result |
|
last |
false |
link to the last page of the beneficiaries result |
|
next |
false |
link to the next page of the beneficiaries result |
|
prev |
false |
link to the previous page of the beneficiaries result |
PaymentRequestLinks
links that can be used for further navigation when having post a Payment Request in order to get the relevant status report.
Fields
Name | Type | Required | Description |
---|---|---|---|
self |
false |
hypertext reference |
|
confirmation |
false |
This link shall not been provided when the confirmation has already been posted. |
PaymentCoverageReportLinks
links that can be used for further navigation to post another coverage request.
Fields
Name | Type | Required | Description |
---|---|---|---|
self |
true |
hypertext reference |
PaymentRequestResourceCreationLinks
Links that can be used for further navigation, especially in REDIRECT approach
Fields
Name | Type | Required | Description |
---|---|---|---|
consentApproval |
false |
URL to be used by the PISP in order to start the ASPSP authentication and consent management process |
|
confirmation |
false |
Link to the payment confirmation API endpoint |
ConsentLinks
Fields
Name | Type | Required | Description |
---|---|---|---|
redirect |
false |
hypertext reference |
|
self |
false |
hypertext reference |
|
status |
false |
hypertext reference |
Exceptions
HttpException
Code samples
{}
This exception is raised when ASPSP API responses with unspecified error.
Fields
Name | Type | Required | Description |
---|---|---|---|
status |
integer(int32) |
true |
HTTP error code |
message |
string |
true |
HTTP textual reason phrase |
responseHeaders |
[object] |
true |
Headers of http response |
responseBody |
string |
true |
Body of http response |
DataRetrievalException
This exception is raised when unable to retrieve data requested from ASPSP API.
Base type
InsufficientScopeException
This exception is raised when consent given by the PSU does not allow to retrieve
requested data.
Base type
Connectors
ConnectorSettings
Base settings for all connectors
Fields
Name | Type | Required | Description |
---|---|---|---|
sandbox |
boolean |
true |
Defines whether connect to sandbox or production APIs |
consentId |
string |
true |
User consent identifier |
accessToken |
string |
true |
User access token |
refreshToken |
string |
true |
User refresh token |
connector |
string |
true |
Connector identifier (discriminator) |
AktiaConnectorSettings
Settings for initializing ApiClient for Aktia
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
API client ID (obtained from Aktia Developer Portal) |
clientSecret |
string |
true |
API client secret (obtained from Aktia Developer Portal) |
tppRedirectUri |
string |
false |
none |
sandboxPaymentId |
string |
false |
none |
sandboxSafeguard |
boolean |
false |
none |
AliorConnectorSettings
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
none |
clientSecret |
string |
true |
none |
certPath |
string |
true |
none |
keyPath |
string |
true |
none |
signKeyPath |
string |
true |
none |
signPubKeySerial |
string |
true |
none |
signFingerprint |
string |
true |
none |
signCertUrl |
string |
true |
none |
paymentAuthRedirectUri |
string |
false |
none |
paymentAuthState |
string |
false |
none |
BNPParibasPolandConnectorSettings
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
none |
clientSecret |
string |
true |
none |
certPath |
string |
true |
none |
keyPath |
string |
true |
none |
signKeyPath |
string |
true |
none |
signPubKeySerial |
string |
true |
none |
signFingerprint |
string |
true |
none |
signCertUrl |
string |
true |
none |
tppId |
string |
true |
none |
paymentAuthRedirectUri |
string |
false |
none |
paymentAuthState |
string |
false |
none |
INGPolandConnectorSettings
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
none |
certPath |
string |
true |
none |
keyPath |
string |
true |
none |
signKeyPath |
string |
true |
none |
signPubKeySerial |
string |
true |
none |
signFingerprint |
string |
true |
none |
signCertUrl |
string |
true |
none |
tppId |
string |
true |
none |
paymentAuthRedirectUri |
string |
false |
none |
paymentAuthState |
string |
false |
none |
LHVConnectorSettings
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
certPath |
string |
true |
none |
keyPath |
string |
true |
none |
caCertPath |
string |
true |
none |
clientId |
string |
true |
none |
psuIpAddress |
string |
false |
none |
tppRedirectUri |
string |
false |
none |
NordeaConnectorSettings
Code samples
package com.eb.sample;
import com.enablebanking.ApiClient;
import com.enablebanking.model.NordeaConnectorSettings;
ApiClient apiClient = new ApiClient(
new NordeaConnectorSettings()
.clientId("put-your-client-id-here")
.clientSecret("put-your-client-secret-here")
.certPath("path/to/qwac-crt.pem")
.keyPath("path/to/qwac-key.pem")
.country("FI")
.language("fi")
.sandbox(true));
Settings for initializing ApiClient for Nordea (all countries).
Credentials can obtained at Nordea Developer Portal
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
API client ID (obtained from Nordea Developer Portal) |
clientSecret |
string |
true |
API client secret (obtained from Nordea Developer Portal) |
certPath |
string |
true |
Path to Qseal certificate in PEM format. |
keyPath |
string |
true |
Path to Qseal certificate private key in PEM format. |
country |
string |
true |
Bank country (only clients from the specified will be able to authenticate). Possilbe values: |
sessionDuration |
integer |
false |
Duration of access authorization in minutes (up to 129600 minutes - 90 days). This value will be overriden with Access.validUntil if provided to getAuth call. |
language |
string |
false |
Language of authentication user interface. If country is |
OPConnectorSettings
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
apiKey |
string |
true |
none |
apiSecret |
string |
true |
none |
PekaoConnectorSettings
Code samples
package com.eb.sample;
import com.enablebanking.ApiClient;
import com.enablebanking.model.PekaoConnectorSettings;
ApiClient apiClient = new ApiClient(
new PekaoConnectorSettings()
.clientId("put-your-client-id-here")
.clientSecret("put-your-client-secret-here")
.certPath("path/to/qwac-crt.pem")
.keyPath("path/to/qwac-key.pem")
.signKeyPath("path/to/qseal-key.pem")
.signPubKeySerial("qseal-cert-serial")
.signFingerprint("qseal-cert-fingerprint")
.signCertUrl("qseal-cert-public-url")
.sandbox(true));
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
none |
clientSecret |
string |
true |
none |
certPath |
string |
true |
none |
keyPath |
string |
true |
none |
signKeyPath |
string |
true |
none |
signPubKeySerial |
string |
true |
none |
signFingerprint |
string |
true |
none |
signCertUrl |
string |
true |
none |
paymentAuthRedirectUri |
string |
false |
none |
paymentAuthState |
string |
false |
none |
PKOConnectorSettings
Code samples
package com.eb.sample;
import com.enablebanking.ApiClient;
import com.enablebanking.model.PKOConnectorSettings;
ApiClient apiClient = new ApiClient(
new PKOConnectorSettings()
.clientId("put-your-client-id-here")
.certPath("path/to/qwac-crt.pem")
.keyPath("path/to/qwac-key.pem")
.signKeyPath("path/to/qseal-key.pem")
.signPubKeySerial("qseal-cert-serial")
.signFingerprint("qseal-cert-fingerprint")
.signCertUrl("qseal-cert-public-url")
.tppId("your-tpp-id")
.sandbox(true));
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
none |
certPath |
string |
true |
none |
keyPath |
string |
true |
none |
signKeyPath |
string |
true |
none |
signPubKeySerial |
string |
true |
none |
signFingerprint |
string |
true |
none |
signCertUrl |
string |
true |
none |
tppId |
string |
true |
none |
paymentAuthRedirectUri |
string |
false |
none |
paymentAuthState |
string |
false |
none |
POPPankkiConnectorSettings
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
none |
clientSecret |
string |
true |
none |
ocpApimSubscriptionKey |
string |
true |
none |
primaryKey |
string |
true |
none |
secondaryKey |
string |
true |
none |
psuIpAddress |
string |
false |
none |
tppRedirectUri |
string |
false |
none |
SwedbankConnectorSettings
Code samples
package com.eb.sample;
import com.enablebanking.ApiClient;
import com.enablebanking.model.SwedbankConnectorSettings;
ApiClient apiClient = new ApiClient(
new SwedbankConnectorSettings()
.clientId("put-your-client-id-here")
.clientSecret("put-your-client-secret-here")
.country("SE")
.tppRedirectUri("scheme://uri/to/redirect/after/payment")
.psuIpAddress("end-user-ip-address")
.psuUserAgent("end-user-ua-string")
.sandbox(true));
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
none |
clientSecret |
string |
true |
none |
country |
string |
true |
none |
tppRedirectUri |
string |
false |
none |
psuIpAddress |
string |
false |
none |
psuUserAgent |
string |
false |
none |
SPankkiConnectorSettings
Code samples
package com.eb.sample;
import com.enablebanking.ApiClient;
import com.enablebanking.model.SPankkiConnectorSettings;
ApiClient apiClient = new ApiClient(
new SPankkiConnectorSettings()
.clientId("put-your-client-id-here")
.xApiKey("put-your-x-api-key-here")
.certPath("path/to/qwac-crt.pem")
.keyPath("path/to/qwac-key.pem")
.signKeyPath("path/to/qseal-crt.pem")
.signPubKeySerial("qseal-cert-public-serial-here")
.paymentAuthRedirectUri("scheme://uri/to/redirect/after/payment")
.paymentAuthState("payment-auth-state-value-here")
.sandbox(true));
Settings for initializing ApiClient for S-Pankki (Finland).
Credentials can obtained at Open Banking Market
operated by Crosskey Banking Solutions.
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
API client ID (obtained at Open Banking Market) |
xApiKey |
string |
true |
API client key (obtained at Open Banking Market) |
certPath |
string |
true |
Path to QWAC certificate in PEM format. |
keyPath |
string |
true |
Path to QWAC certificate private key in PEM format. |
signKeyPath |
string |
true |
Path to QSeal certificate in PEM format. |
signPubKeySerial |
string |
true |
Public serial key of the QSeal certificate located in signKeyPath. The serial must be |
paymentAuthRedirectUri |
string |
false |
URI where clients are redirected to after payment authorization. |
paymentAuthState |
string |
false |
This value returned to paymentAuthRedirectUri after payment authorization. |
AlandsbankenConnectorSettings
Code samples
package com.eb.sample;
import com.enablebanking.ApiClient;
import com.enablebanking.model.AlandsbankenConnectorSettings;
ApiClient apiClient = new ApiClient(
new AlandsbankenConnectorSettings()
.clientId("put-your-client-id-here")
.xApiKey("put-your-x-api-key-here")
.certPath("path/to/qwac-crt.pem")
.keyPath("path/to/qwac-key.pem")
.signKeyPath("path/to/qseal-crt.pem")
.signPubKeySerial("qseal-cert-public-serial-here")
.paymentAuthRedirectUri("scheme://uri/to/redirect/after/payment")
.paymentAuthState("payment-auth-state-value-here")
.sandbox(true));
Settings for initializing ApiClient for Ålandsbanken (Finland).
Credentials can obtained at Open Banking Market
operated by Crosskey Banking Solutions.
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
API client ID (obtained at Open Banking Market) |
xApiKey |
string |
true |
API client key (obtained at Open Banking Market) |
certPath |
string |
true |
Path to QWAC certificate in PEM format. |
keyPath |
string |
true |
Path to QWAC certificate private key in PEM format. |
signKeyPath |
string |
true |
Path to QSeal certificate in PEM format. |
signPubKeySerial |
string |
true |
Public serial key of the QSeal certificate located in signKeyPath. The serial must be |
country |
string |
false |
none |
paymentAuthRedirectUri |
string |
false |
URI where clients are redirected to after payment authorization. |
paymentAuthState |
string |
false |
This value returned to paymentAuthRedirectUri after payment authorization. |
ResursConnectorSettings
Code samples
package com.eb.sample;
import com.enablebanking.ApiClient;
import com.enablebanking.model.ResursConnectorSettings;
ApiClient apiClient = new ApiClient(
new ResursConnectorSettings()
.clientId("put-your-client-id-here")
.xApiKey("put-your-x-api-key-here")
.certPath("path/to/qwac-crt.pem")
.keyPath("path/to/qwac-key.pem")
.signKeyPath("path/to/qseal-crt.pem")
.signPubKeySerial("qseal-cert-public-serial-here")
.paymentAuthRedirectUri("scheme://uri/to/redirect/after/payment")
.paymentAuthState("payment-auth-state-value-here")
.sandbox(true));
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
none |
xApiKey |
string |
true |
none |
certPath |
string |
true |
none |
keyPath |
string |
true |
none |
signKeyPath |
string |
true |
none |
signPubKeySerial |
string |
true |
Public serial key of the QSeal certificate located in signKeyPath. The serial must be |
paymentAuthRedirectUri |
string |
false |
none |
paymentAuthState |
string |
false |
none |
KomplettConnectorSettings
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
none |
xApiKey |
string |
true |
none |
certPath |
string |
true |
none |
keyPath |
string |
true |
none |
signKeyPath |
string |
true |
none |
signPubKeySerial |
string |
true |
Public serial key of the QSeal certificate located in signKeyPath. The serial must be |
paymentAuthRedirectUri |
string |
false |
none |
paymentAuthState |
string |
false |
none |
YaConnectorSettings
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
none |
xApiKey |
string |
true |
none |
certPath |
string |
true |
none |
keyPath |
string |
true |
none |
signKeyPath |
string |
true |
none |
signPubKeySerial |
string |
true |
Public serial key of the QSeal certificate located in signKeyPath. The serial must be |
paymentAuthRedirectUri |
string |
false |
none |
paymentAuthState |
string |
false |
none |
SEBConnectorSettings
Code samples
package com.eb.sample;
import com.enablebanking.ApiClient;
import com.enablebanking.model.SEBConnectorSettings;
ApiClient apiClient = new ApiClient(
new SPankkiConnectorSettings()
.certPath("path/to/qwac-crt.pem")
.keyPath("path/to/qwac-key.pem")
.clientId("put-your-client-id-here")
.country("EE")
.psuIpAddress("end-user-IP-address")
.tppRedirectUri("scheme://uri/to/redirect/after/payment")
.sandbox(true));
Settings for initializing ApiClient for SEB Estonia, SEB Latvia and SEB Lithuania.
Credentials can obtained at SEB Developer Portal for Baltic countries.
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
certPath |
string |
true |
Path to QWAC certificate in PEM format. |
keyPath |
string |
true |
Path to QWAC certificate private key in PEM format. |
clientId |
string |
true |
API client ID (obtained from SEB Developer Portal) |
country |
string |
true |
Bank country (only clients from the specified will be able to authenticate). Possilbe values: |
psuIpAddress |
string |
false |
IP address of a client accessing bank data through TPP. |
tppRedirectUri |
string |
false |
URI where clients are redirected to after giving consent. |
SEBSwedenConnectorSettings
Code samples
package com.eb.sample;
import com.enablebanking.ApiClient;
import com.enablebanking.model.SEBSwedenConnectorSettings;
ApiClient apiClient = new ApiClient(
new SEBSwedenConnectorSettings()
.clientId("put-your-client-id-here")
.clientSecret("put-your-client-secret-here")
.certPath("path/to/qwac-crt.pem")
.keyPath("path/to/qwac-key.pem")
.sandbox(true));
Settings for initializing ApiClient for SEB Sweden.
Credentials can obtained at SEB Developer Portal.
Base type
Fields
Name | Type | Required | Description |
---|---|---|---|
clientId |
string |
true |
API client ID (obtained from SEB Developer Portal) |
clientSecret |
string |
true |
API client secret (obtained from SEB Developer Portal) |
certPath |
string |
true |
Path to QWAC certificate in PEM format. |
keyPath |
string |
true |
Path to QWAC certificate private key in PEM format. |
Platform
Java
public abstract class AbstractConnectorSettingsFactory
Base class for connector settings factory, which can be used for creating instances of connector-specific settings classes (derived from ConnectorSettings class)
Code sample
public class SampleConnectorSettingsFactory {
@Override
public String getConnectorName() {
// Returning connector identifier
return "Nordea";
}
@Override
public Boolean getSandbox() {
// Returning value of `sandbox` parameter (common for all connectors)
return true;
}
@Override
public String getAccessToken() {
// Returning "not set" for `accessToken` parameter (common for all connectors)
return null;
}
@Override
public String getRefreshToken() {
// Returning "not set" for `refershToken` parameter (common for all connectors)
return null;
}
@Override
public String getConsentId() {
// Returning "not set" for `consentId` parameter (common for all connectors)
return null;
}
public String getClientId() {
// Returning value of `clientId` parameter (Nordea specific)
return "api-client-id";
}
public String getClientSecret() {
// Returning value of `clientSecret` parameter (Nordea specific)
return "api-client-secret";
}
public String getCertPath() {
// Returning value of `certPath` parameter (Nordea specific)
return "/path/to/qwac/cert";
}
public String getKeyPath() {
// Returning value of `keyPath` parameter (Nordea specific)
return "/path/to/qwac/key";
}
}
abstract protected String getConnectorName()
- Returns: Connector identifier
abstract protected Boolean getSandbox()
- Returns:
true
- sandbox settings,false
- production settings
abstract protected String getConsentId()
- Returns: Consent identifier (
null
if consent is not set)
abstract protected String getAccessToken()
- Returns: User access token (
null
if access token is not set)
abstract protected String getRefreshToken()
- Returns: User refresh token (
null
if refresh token is not set)
public ConnectorSettings createConnectorSettings()
Creates connector settings for a connector with identifier returned from getConnectorName
method. The created connector settings instance will contain data returned by the
corresponding methods of the factory. For example, if getConnectorName
returns "Nordea"
instance of NordeaConnectorSettings
class will be created and data like client ID and
client secret will be set (corresponding methods including getClientId
and
getClientSecret
must be implemented in the factory, otherwise runtime exception will be
thrown).
- Returns: Instance of a connector settings class
public abstract class AbstractPlatformExtension
Base class for customazing low-level functionality to the requirements of a target platform
- Package: com.enablebanking
abstract protected PlatformApiResponse makeRequest(PlatformApiRequest request)
Executes API request and returns an object containing response details.
- Parameters:
request
— Request details including parameters for establishing (M)TLS connection - Returns: Object containing response details
abstract protected String signPKCS1v15usingSHA256(String value, String key, String keyPassword)
Generates PKCS #1 v1.5 RSA signature with SHA-256 mechanism.
- Parameters:
value
— String to be signedkey
— URI of the key used for signing {@code value} parameterkeyPassword
— Password used to get access to the key (optional)
- Returns: String containing signature
public class PlatformApiRequest
Internal representation of API request
- Package: com.enablebanking
public PlatformApiRequest(String method, String origin, String path, List<Map.Entry<String, String>> headers, List<Map.Entry<String, String>> query, String body, TlsSettings tls)
Creates instance of the class with all necessary parameters.
- Parameters:
method
— HTTP method: GET, POST, PUT, etcorigin
— HTTP origin (i.e.<scheme> "://" <hostname> [ ":" <port> ]
)path
— Path part of a requested URLheaders
— HTTP headers as a list of key-value pairsquery
— Query part of a requested URL as a list of key-value pairsbody
— HTTP bodytls
— Parameters for establishing (M)TLS connection
public PlatformApiRequest(String method, String origin, String path, List<Map.Entry<String, String>> headers, List<Map.Entry<String, String>> query, String body)
Creates instance of the class with all parameters except (M)TLS settings.
- Parameters:
method
— HTTP method: GET, POST, PUT, etcorigin
— HTTP origin (i.e.<scheme> "://" <hostname> [ ":" <port> ]
)path
— Path part of an URLheaders
— HTTP headers as a list of key-value pairsquery
— Query part of an URL as a list of key-value pairsbody
— HTTP body
public String getMethod()
- Returns: HTTP method of the request
public String getOrigin()
- Returns: HTTP origin of the request
public String getPath()
- Returns: Path part of the requested URL
public List<Map.Entry<String, String>> getHeaders()
- Returns: HTTP headers of the request
public List<Map.Entry<String, String>> getQuery()
- Returns: Query part of the requested URL
public String getBody()
- Returns: Body of the request
public TlsSettings getTls()
- Returns: Parameters for establishing (M)TLS connection for the request
public String findHeader(String header)
- Parameters:
header
— Name of an HTTP header - Returns: First entry of the HTTP header with a given name or null if not found
public class TlsSettings
Internal representation of the parameters used to establish (M)TLS connection
- Package: com.enablebanking
public TlsSettings(String certPath, String keyPath, String caCertPath, String keyPassword)
Creates instance of the class with all necessary parameters.
- Parameters:
certPath
— URI for identifying client certificate for MTLS connectionkeyPath
— URI for identifying private key for MTLS client certificatecaCertPath
— URI for identifying server certificatekeyPassword
— Password used to get access to the private key (optional)
public TlsSettings(String certPath, String keyPath, String caCertPath)
Creates instance of the class with all parameters except key password (set to null).
- Parameters:
certPath
— URI for identifying client certificate for MTLS connectionkeyPath
— URI for identifying private key for MTLS client certificatecaCertPath
— URI for identifying server certificate
public TlsSettings(String certPath, String keyPath)
Creates instance of the class with all parameters except key password and server certificate (set to null).
- Parameters:
certPath
— URI for identifying client certificate for MTLS connectionkeyPath
— URI for identifying private key for MTLS client certificate
public String getCertPath()
- Returns: URI for identifying client certificate for MTLS connection
public String getKeyPath()
- Returns: URI for identifying private key for MTLS client certificate
public String getCaCertPath()
- Returns: URI for identifying server certificate (null if not set)
public String getKeyPassword()
- Returns: Password used to get access to the private key (null if not set)
@Override public boolean equals(Object obj)
Checks if this object equals to another.
- Parameters:
obj
— Object to compare with - Returns: true when {@code obj} is considered equal to {@code this}, otherwise false
public class PlatformApiResponse
Internal representation of API response
- Package: com.enablebanking
public PlatformApiResponse(int statusCode, List<Map.Entry<String, String>> headers, String body)
Creates instance of the class with all necessary parameters.
- Parameters:
statusCode
— HTTP response codeheaders
— HTTP response headers as list of key-value pairsbody
— Body of HTTP response
public int getStatusCode()
- Returns: HTTP code of the response
public List<Map.Entry<String, String>> getHeaders()
- Returns: HTTP headers of the response
public String getBody()
- Returns: Body of the response
public String findHeader(String header)
- Parameters:
header
— Name of an HTTP header - Returns: First entry of the HTTP header with a given name or null if not found