NAV Navbar

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

  1. Application redirects user to OAuth server (authorization server).
  2. Authorization server displays to the user form with fields for login and password.
  3. Authorization server after successful logging in and password verification displays the confirmations required by the application to the user, which the user then confirms.
  4. Authorization server after successful verification of consents sends code to redirect_uri.
  5. Application sends code and client_secret to authorization server.
  6. Authorization server verifies code and client_secret and return access_token to application.
  7. 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].