Introduction

Open Banking Standard at Conotoxia.com

Within the European Union, the PSD II directive regulates access to bank customer data. The regulations, which define the conditions for the operations of payment institutions, allow customers to freely choose their financial service provider. In turn, banks and non-banking payment institutions are obliged to make customers' payment accounts available online via an API (Application Programming Interface).

Product description

Conotoxia Sp. z o.o., which provides services at Conotoxia.com, reacting to the requirements, makes available a dedicated API for payment accounts to financial institutions with a qualified certificate (i.e. TPP). The access interface is built on the basis of the following specifications NextGenPSD2 API and enables access to the payment accounts of the portal's customers with regard to: initiating new payment transactions, downloading the history of transactions on the account and their details. Use of the functionalities offered by the interface is possible only if the customer (payment account owner) agrees to it.

By sharing API, we enable other institutions to use the solutions created by us in their business. Together, we will develop new, innovative financial products, and our customers will be able to freely choose their financial service provider.

Initiation of a payment transaction enables the use of fast money transfers from 30 countries, in 28 currencies. Countries en

Our API is continuously being developed. The established base of acquired knowledge and documentation will facilitate the integration process with our services. We are in constant contact and will help you at every stage of implementation.

Certificates

In accordance with the PSD2 regulation, TPP and ASPSP must have a valid qualified certificate, for mutual identification in the XS2A interface, received from a qualified trust service provider meeting the regulatory requirements in the area of trust service and electronic identification. This certificate should additionally comply with the requirements defined in RTS and ETSI technical specification (TS 119495). Qualified trust service centres within the European Union are responsible for issuing certificates.

Obtaining access to the API and the authentication method

In order to gain access to the API, it is necessary to assign a user, who will be given the required authorization data (the corresponding client_id and client_secret). As part of the customer registration process, it is necessary to specify an email address to which the confirmation and authorization data will be sent, as well as a link (redirect_uri) to which code will be returned.

Access to the API is protected by the OAuth 2.0 standard and requires the generated access_token received after user authentication. The entire access process is executed with AuthorizationCodeFlow. It looks like this: Authentication en

Particular requests are then authorized using the obtained access_token, which is forwarded in the request header: "Authorization".

Additional information

The API developed by us is based on NextGenPSD2 created by the Berlin Group.

Modules descriptions

PIS

Payment Initiation Service (PIS) - a service enabling TPP to initiate a payment transaction on behalf of a customer.

AIS

Account Information Service (AIS) - a service enabling TPP to access information about the customer's payment accounts, balances of these accounts, history of transactions and their details.

CAF

Confirmation of the Availability of Funds (CAF) - a service enabling TPP to verify whether the user's payment account contains a specified amount of funds. In this way it is possible to determine whether a given user is able to make payments for a specified amount, protecting them at the same time against sending detailed information about the payment account. This service is dedicated to payment card providers.

Endpoints details

Initialise payment

Request:

{
    "debtorAccount":
    {
        "paymentAccountId": "12345667",
        "currency": "USD",
        "amount": 10
    },
    "creditorAccount":
    {
        "type": "IBAN",
        "recipientId": "2335454",
        "currency": "USD"
    },
    "message": "Example message"
}

Response 201 - Created:

{
    "transactionStatus": "RCVD",
    "paymentId": "1234-wertiq-983",
    "_links":
    {
        "scaOAuth":
        {
            "href": "string"
        },
        "scaStatus":
        {
            "href": "string"
        },
        "self":
        {
            "href": "/psd2/v1/payments/money-transfer/1234-wertiq-983"
        },
        "status":
        {
            "href": "/psd2/v1/payments/money-transfer/1234-wertiq-983/status"
        }
    },
    "transactionFee": 0.3
}

Request:

POST /psd2/v1.0/payments/money-transfer

Parameters:

Attribute	Format	Condition	Type	Description
Content-Type	String	Mandatory	Header	application/json
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Body:

Attribute	Format	Condition	Description
debtorAccount	Object	Mandatory	Debtor account
paymentAccountId	String	Mandatory	Account ID
currency	String	Mandatory	Currency of debtor's account
Amount	Number	Mandatory	Amount of currency
creditorAccount	Object	Mandatory	Creditor account
type	String	Mandatory	Type of account
recipientId	String	Mandatory	Recipient ID
currency	String	Mandatory	Currency
message	String	Optional	Message for recipient

Get recipients

Response 200 - OK:

{
    "accounts":
    [
        {
            "id": "1234567",
            "alias": "Konto",
            "type": "IBAN",
            "currency": "USD"
        }
    ]
}

Request:

GET /psd2/v1.0/accounts/recipients

Parameters:

Attribute	Format	Condition	Description
X-Request-ID	String	Mandatory	Header
Consent-ID	String	Mandatory	Header

Get recipient details

Response 200 - OK:

{
    "account":
    {
        "id": "123456",
        "alias": "Account",
        "type": "iBAN",
        "name": "John",
        "lastName": "Smith",
        "iban": "AL35202111090000000001234567",
        "currency": "USD",
        "bankName": "Bank of Albania",
        "phone": "+355 00000000000",
        "email": "[email protected]",
        "_links":
        {
            "balances":
            {
                "href":  "/psd2/v1/accounts/123456/balances"
            },
            "transactions":
            {
                "href": "/psd2/v1/accounts/123456/transactions"
            }
        }
    }
}

Request:

GET /psd2/v1.0/accounts/recipients/{recipientId}

Parameters:

Attribute	Format	Condition	Type	Description
recipientId	String	Mandatory	Path	Recipient ID
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
Consent-ID	String	Mandatory	Header	Details will be returned for consent with that ID

Get payment information

Request:

GET /psd2/v1.0/payments/money-transfer/{paymentId}

Parameters:

Attribute	Format	Condition	Type	Description
paymentId	String	Mandatory	Path	Payment ID
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Response 200 - OK:

Payment initiation status request

Request:

GET /psd2/v1.0/payments/money-transfer/{paymentId}/status

Parameters:

Attribute	Format	Condition	Type	Description
paymentId	String	Mandatory	Path	Payment ID
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Response 200 - OK:

{
    "transactionStatus": "ACCP",
    "fundsAvailable": true
}

Payment acceptation

Request:

POST /psd2/v1.0/payments/money-transfer/{paymentId}/commit

Parameters:

Attribute	Format	Condition	Type	Description
paymentId	String	Mandatory	Path	Payment ID
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Response 200 - OK:

{
    "paymentId": "123465",
}

Account details

Provides detailed information about an account

Response:

{
    "account": {
        "resourceId": "EXAMPLE560966344078535",
        "paymentAccountId": "EXAMPLE560966344078535",
        "currency": "XXX",
        "_links":
        {
            "balances":
            {
                "href": "/psd2/v1.0/accounts/EXAMPLE560966344078535/balances"
            },
            "transations":
            {
                "href": "/psd2/v1.0/accounts/EXAMPLE560966344078535/transactions"
            }
        },
        "balances":
        [ //if request contains flag withBalance = true
            {
                "balanceType": "interimBooked",
                "balanceAmount":
                {
                    "currency": "PLN",
                    "amount": "12345.12"
                }
            },
            {
                "balanceType": "interimAvailable",
                "balanceAmount":
                {
                    "currency": "PLN",
                    "amount": "4555.00"
                }
            },
            {
                "balanceType": "interimBooked",
                "balanceAmount":
                {
                    "currency": "EUR",
                    "amount": "44452.00"
                }
            },
            {
                "balanceType": "interimAvailable",
                "balanceAmount":
                {
                    "currency": "EUR",
                    "amount": "123.45"
                }
            }
        ]
    }
}

Request:

GET /psd2/v1.0/accounts/{paymentAccountId}

Parameters:

Attribute	Format	Condition	Type	Description
paymentAccountId	String	Mandatory	Path	User account ID which details are requested
withBalance	Boolean	Optional	Query	Should information about balances be included
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
Consent-ID	String	Mandatory	Header	Consent ID for using specific functionality
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Currency: “XXX” means multicurrency

Accounts list

Provides accounts list

Response:

{
    "accounts":
    [
        {
            "resourceId": "EXAMPLE560966344078535",
            "paymentAccountId": "EXAMPLE560966344078535",
            "currency": "XXX",
            "_links":
            {
                "balances":
                {
                    "href": "/psd2/v1.0/accounts/EXAMPLE560966344078535/balances"
                },
                "transations":
                {
                    "href": "/psd2/v1.0/accounts/EXAMPLE560966344078535/transactions"
                }
            },
            "balances":
            [ // if request contains flag withBalance = true
                {
                    "balanceType": "interimBooked",
                    "balanceAmount":
                    {
                        "currency": "PLN",
                        "amount": "12345.12"
                    }
                },
                {
                    "balanceType": "interimAvailable",
                    "balanceAmount":
                    {
                        "currency": "PLN",
                        "amount": "4555.00"
                    }
                },
                {
                    "balanceType": "interimBooked",
                    "balanceAmount":
                    {
                        "currency": "EUR",
                        "amount": "44452.00"
                    }
                },
                {
                    "balanceType": "interimAvailable",
                    "balanceAmount":
                    {
                        "currency": "EUR",
                        "amount": "123.45"
                    }
                }
            ]
        }
    ]
}

Request:

GET /psd2/v1.0/accounts

Parameters:

Attribute	Format	Condition	Type	Description
withBalance	Boolean	Optional	Query	Should information about balances be included
X-Request-ID	String	Mandatory	Header	Unique request Id. Uniqueness should be assured by user
Consent-ID	String	Mandatory	Header	Consent for using specific functionality
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Currency: “XXX” means multicurrency

Balance

Provides balance list of requested account

Response:

{
    "account":
    {
        "paymentAccountId": "123456789"
    },
    "balance":
    [
        {
            "balanceType": "interimBooked",
            "balanceAmount":
            {
                "currency": "PLN",
                "amount": "12345.12"
            }
        },
        {
            "balanceType": "interimAvailable",
            "balanceAmount":
            {
                "currency": "PLN",
                "amount": "4555.00"
            }
        },
        {
            "balanceType": "interimBooked",
            "balanceAmount":
            {
                "currency": "EUR",
                "amount": "44452.00"
            }
        },
        {
            "balanceType": "interimAvailable",
            "balanceAmount":
            {
                "currency": "EUR",
                "amount": "123.45"
            }
        }
    ]
}

Request:

GET /psd2/v1.0/accounts/{paymentAccountId}/balances

Parameters:

Attribute	Format	Condition	Type	Description
paymentAccountId	String	Mandatory	Path	User account ID which details are requested
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
Consent-ID	String	Mandatory	Header	Consent for using specific functionality
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Transaction list

Provides a list of transactions for the requested account

Response:

{
    "account":
    {
        "currencyAccountId":"id1243"
    },
    "transactions":
    {
        "booked":
        [
            {
                "transactionId": "CXT1072395432531381",
                "transactionType": "TRANSFER",
                "amount":
                {
                    "currency": "USD",
                    "value": "234.12"
                }
                "bookingDate": "2018-03-09T11:50:49.525Z",
                "valueDate": "2018-03-09T11:50:49.525Z"
            }
        ],
        "pending":
        [
            {
                "transactionId": "CXT1072395432531381",
                "transactionType": "CK_DEPOSIT",
                "amount":
                {
                    "currency": "PLN",
                    "value": "234.12"
                }
                "date": "2018-03-09T11:50:49.525Z"
            }
        ],
        "_links":
        {
            "account":
            {
                "href":"/psd2/v1.3/accounts/id1243"
            }
        }
    }
}

Request:

GET /psd2/v1.0/accounts/{paymentAccountId}/transactions

Parameters:

Attribute	Format	Condition	Type	Description
paymentAccountId	String	Mandatory	Path	User account ID which details are requested
bookingStatus	String	Optional	Query	Which statuses are to be returned (“BOOKED”, “PENDING” lub “BOTH”). Default "BOTH"
dateFrom	DateTime	Optional	Query	Transactions are to be returned if field is filled. Field cannot be used if entryReferenceFrom was used
dateTo	DateTime	Optional	Query	Until this date transactions are to be returned if field is filled. Field cannot be used if entryReferenceFrom was used
entryReferenceFrom	String	Optional	Query	Transactions will be returned since date when transaction with this ID was executed. Field cannot be used if dateFrom or dateTo was used
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
Consent-ID	String	Mandatory	Header	Consent ID for using specific functionality
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Transaction details

Provides details about a specific transaction for specific account

Response:

{
    "transactionsDetails":
    {
         "transactionId": "EXAMPLE1072395432531381",
         "transactionType": "FEE",
         "status": "BOOKED",
         "amount":
         {
             "currency": "PLN",
             "value": "234.12"
         }
         "bookingDate": "2018-03-09T11:50:49.525Z",
         "valueDate": "2018-03-09T11:50:49.525Z"
     }
}

Request:

GET /psd2/v1.0/accounts/{paymentAccountId}/transactions/{resourceId}

Parameters:

Attribute	Format	Condition	Type	Description
paymentAccountId	String	Mandatory	Path	User account ID which details are requested
resourceId	String	Mandatory	Path	Transaction ID which details are requested
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
Consent-ID	String	Mandatory	Header	Consent for using specific functionality
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Request:

{
    "access":
        {
            "accounts":
            [
                {
                    "paymentAccountId": "DE40100100103307118608",
                    "currency": "USD"
                }
            ],
            "balances":
            [
                {
                    "paymentAccountId": "DE40100100103307118608",
                    "currency": "USD"
                }
            ],
            "transactions":
            [
                {
                    "paymentAccountId": "DE40100100103307118608",
                    "currency": "USD"
                }
            ],
            "allPsd2": "allAccounts",
        },
    "recurringIndicator": true,
    "validUntil": "2020-10-07T11:25:07.427237Z",
    "frequencyPerDay": "4",
    "combinedServiceIndicator": false
}

Response 201 - Created:

{
    "consentStatus": "received",
    "consentId": "1a43fa8b-92ef-4704-b6a9-16256656beb6",
    "_links":
    {
        "self": "/psd2/v1.0/consents/1a43fa8b-92ef-4704-b6a9-16256656beb6",
        "status": "/psd2/v1.0/consents/1a43fa8b-92ef-4704-b6a9-16256656beb6/status"
    }
}

Request:

POST /psd2/v1.0/consents

Parameters:

Attribute	Format	Condition	Type	Description
Content-Type	String	Mandatory	Header	application/json
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Body:

Attribute	Format	Condition	Description
access	Object	Mandatory	Which data access is requested
accounts	List of objects	Optional	Access to these accounts will be permitted
paymentAccountId	String	Mandatory	Access will be permitted to account with this ID
currency	String	Mandatory	Access to this account currency will be permitted
balances	List of objects	Optional	Access to these accounts balances will be permitted
transactions	List of objects	Optional	Access to these accounts’ transactions will be permitted
allPsd2	String	Optional	If value is "allAccounts", all available accounts will be requested
recurringIndicator	Boolean	Mandatory	If value is true - consent will be valid for multiple operations. Otherwise consent can be used only once
validUntil	DateTime	Mandatory	Until this date of consent is valid
frequencyPerDay	Int	Mandatory	How many times per day consent can be used
combinedServiceIndicator	Boolean	Mandatory	If true transaction initialising will be done in the same session

Gets details of specific consent

Response:

{
    "access":
    {
        "accounts":
        [
            {
                "paymentAccountId": "DE40100100103307118608",
                "currency": "usd"
            }
        ],
      "balances":
      [
            {
                "paymentAccountId": "DE40100100103307118608",
                "currency": "usd"
            }
      ],
      "transactions":
       [
            {
                "paymentAccountId": "DE40100100103307118608",
                "currency": "usd"
            }
        ]
    },
    "recurringIndicator": true,
    "validUntil": "2020-10-07T11:25:07.427237",
    "frequencyPerDay": 4,
    "lastActionDate": "2019-03-11T09:45:43.656144",
    "consentStatus": "received"
}

Request:

GET /psd2/v1.0/consents/{consentId}

Parameters:

Attribute	Format	Condition	Type	Description
consentId	String	Mandatory	Path	Details will be returned for consent with that ID
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Gets status of specific consent

Request:

GET /psd2/v1.0/consents/{consentId}/status

Parameters:

Attribute	Format	Condition	Type	Description
consentId	String	Mandatory	Path	Status will be returned for consent with that ID
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Response:

{
    "consentStatus": "received"
}

Delete consent with specific ID

Request:

DELETE /psd2/v1.0/consents/{consentId}

Parameters:

Attribute	Format	Condition	Type	Description
consentId	String	Mandatory	Path	Status will be returned for consent with that ID
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user
PSU-IP-Address	String	Optional	Header	User IP address
PSU-IP-Port	String	Optional	Header	User IP port

Response 204 - No Content:

Confirmation of Funds Request

Checks if account has required funds

Request:

POST /psd2/v1.0/funds-confirmations

Parameters:

Request Body:

{
    "account":
    {
        "paymentAccountId": "12345678998542"
    },
    "instructedAmount":
    {
        "currency": "USD",
        "amount": 15.33
    }
}

Attribute	Format	Condition	Type	Description
X-Request-ID	String	Mandatory	Header	Unique request ID. Uniqueness should be assured by user

Body:

Response 200 - OK:

{
    "fundsAvailable": true
}

Attribute	Format	Condition	Description
account	Object	Mandatory	Check this account funds
paymentAccountId	String	Mandatory	Funds of account with this ID will be checked
instructedAmount	Object	Mandatory	Currency pair and amount
Currency	String	Mandatory	This currency will be checked
Amount	Number	Mandatory	This amount will be checked

OAuth 2.0

User authorization with OAuth 2.0

Authorization procedure

Application redirects user to OAuth server (authorization server).
Authorization server displays to the user form with fields for login and password.
Authorization server after successful logging in and password verification displays the confirmations required by the application to the user, which the user then confirms.
Authorization server after successful verification of consents sends code to redirect_uri.
Application sends code and client_secret to authorization server.
Authorization server verifies code and client_secret and return access_token to application.
Application is authorized and can send requests to provider using access_token.

Description of authorization endpoints

Get authorization code

Request:

GET /connect/authorize

Parameters:

Name	Format	Condition	Type	Description
client_id	String	Mandatory	Query	Unique customer identifier (TPP).
redirect_uri	String	Mandatory	Query	Client's URI to which code is sent.
response_type	String	Mandatory	Query	Response type [code].
scope	String	Mandatory	Query	Resources that the application needs to access.
ui_locales	String	Optional	Query	User interface language.

Exchange Authorization Code for the Access Token

Request

{
    "client_id": "TTPid",
    "client_secret": "TTPsecret",
    "grant_type": "authorization_code",
    "redirect_uri": "https://youdomain.com/openbanking/code",
    "code": "fdaee1c28dcd246bb4649ab76fd8099fc51e8c34f622175836ea2260d708b4d2"
}

Response 200 - OK

{
    "access_token": "46b5572af88c95a6462871dd6fe6459a6336e3fedc2a06616dabbff3b5a64dbe",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Request:

POST /connect/token

Parameters:

Name	Format	Condition	Type	Description
client_id	String	Mandatory	Body	Unique customer identifier (TPP).
client_secret	String	Mandatory	Body	Secret key used to authenticate the customer.
code	String	Mandatory	Body	One-time code interchangeable for the access_token.
grant_type	String	Mandatory	Body	Type of code interchangeable for the access_token [authorization_code].
redirect_uri	String	Mandatory	Body	Client's URI to which user will be redirected after authorization, must be the same as in /connect/authorize.

Consents used in field scope

Name	Description
ais	Account Information Service. Download information about user payment accounts, balances of of these accounts, history of transactions and their details.
piis	Confirmation of the Availability of Funds. Application confirms that the user has a sufficient amount of funds on the payment account.
pis	Payment Initiation Service. Application orders the transfer of cash from user account.

Error Responses

All returned API errors are in the same schema.

Error model

Response:

{
    "type": "https://berlingroup.com/error-codes/FORMAT_ERROR",
    "title": "Bad Request",
    "code": "FORMAT_ERROR"
}

Name	Description
type	A URI reference that identifies the problem type.
title	Short description of error type.
detail	Detailed description of error.
code	Code to explain the nature of the underlying error.

Supported status codes

HTTP Status Code	Name	Description
400	Bad Request	The request cannot be handled due to incorrect query syntax.
401	Unauthorized	Access to the requested resource requires authentication.
403	Forbidden	User does not have the required permission to the requested resource.
404	Not Found	The requested resource was not found.
405	Method Not Allowed	The method contained in the request is not allowed for the indicated resource.
408	Request Timeout	User did not send the request to the server within the specified time.
500	Internal Server Error	Internal server error.
503	Service Unavailable	The server is not able to execute the client's request at the moment.

Testing on sandbox

The communication between the TPP and the ASPSP is always secured by using a TLSconnection using TLS version 1.2 or higher. The TLS-connection has to be established always including client (i.e. TPP) authentication. For this authentication the TPP has to use a qualified certificate for website authentication. This qualified certificate has to be issued by a qualified trust service provider according to the eIDAS regulation. The content of the certificate has to be compliant with the requirements of EBA-RTS. The certificate of the TPP has to indicate all roles the TPP is authorised to use.

Testing user:

Login: psuser Password: psupass

Glossary

Attribute	Description
access_token	Temporary token used to access data on behalf of a user.
client_id	Unique customer identifier (TPP).
client_secret	Secret key used to authenticate the customer.
code	One-time code interchangeable with access_token.

Support

In case of any doubts, please contact our consultants by sending an email to [email protected].

Introduction

Product description

Certificates

Obtaining access to the API and the authentication method

Additional information

Modules descriptions

PIS

AIS

CAF

Endpoints details

Initialise payment

Get recipients

Get recipient details

Get payment information

Payment initiation status request

Payment acceptation

Account details

Accounts list

Balance

Transaction list

Transaction details

Create consent

Get consent details

Get consent status

Delete consent

Confirmation of Funds Request

OAuth 2.0

User authorization with OAuth 2.0

Authorization procedure

Description of authorization endpoints

Get authorization code

Exchange Authorization Code for the Access Token

Consent types

Error Responses

Error model

Supported status codes

Testing on sandbox

Glossary

Support