Documentation

1. INTRO

The following guide is meant to introduce the prospect developer to the Cooperative Bank of Epirus Open Banking Sandbox APIs environment including scenarios where the endpoints as AIS,PIS and PIIS TPPs can be tested. This guide includes two sample scenarios intended to give an overview of the Open APIs functionality and help implement your own custom scenarios

2. SETUP

2.1 Get started with Postman

Postman is perhaps the most popular helper application to test APIs. Using Postman is of course not mandatory, but if you opt to use it you can take advantage of our own ready built collection for testing our APIs.

Please visit https://www.getpostman.com/ to download and install Postman according to the provided instructions.

 

Once you have finished with the installation, you are ready to download and import our Open API collections that will enable you to test the Sandbox APIs with minimum effort.

 

Please download the Postman Collections files from here

The files included in the archive you downloaded include:

  1. Open API calls collection, organized in categories for PISP/AISP/PIISP as well as 2 pre-configured scenarios that will be covered in Section 3

  2. Environment variables, so that will save you time in copying/pasting parameter values across calls and potentially enable the smooth transition to the Production API.

Please follow the steps bellow to import the files to your Postman workspace:

  1. Select “Import” at the top left corner in Postman. Click “Choose files” and select all the files that you downloaded and extracted previously.

  2. After your confirmation, you should be able to see the Collection to the left side of your postman, and the environment variables at the topright corner as displayed bellow:

Now you are ready to make some API calls and test the included scenarios!

2.2 Developer Sign-Up and Product Subscription

In order to use the Cooperative Bank of Epirus Open APIs you need to register an account at the Developer Portal

Cooperative Bank of Epirus Developer Portal: https://developers.epirusbank.openbank.gr

  1. Select “Sign in” in the Developer portal. If you don’t have an account yet, select “Sign up

 

  1. Fill in the application form and validate your account via the confirmation mail sent to your email address

  2. Once logged in, navigate to the “Apps” page. You have to register a developer application to subscribe to the API Products. Fill in the form and submit your application

  1. Once your application is created, you need to save your Client Secret and Client ID. Keep in mind that the Client Secret is only displayed once (after you have created your application) and if you lose it, you'll have to reset it manually via your profile. These parameters have to be included in your PSD2 request headers for authorization, which will be explained in the next section

  1. In order to subscribe to an API, navigate to the “API Products” page and select the API that you wish to test.

  1. Click "Subscribe" under the API Plans section, and you will be prompted to select an application to associate to this API Product. Select the application that you registered in the previous steps and proceed. If you visit your Application page, you can see your active subscriptions at the bottom of the page as displayed below. You are now ready to test the APIs with Postman!

3. API USAGE SCENARIOS

3.1 How to use Postman environment variables for your invocations

Postman environment variables for your invocations

Postman environment variables allow you to set them once and use them in every subsequent call. As you can see in a sample request below, the parameters within {{brackets}} are included in the environment variables.

  1. Select “Manage Environments” (the gearbox) on the topright corner.

  2. Select the “Sandbox Cooperative Bank of Epirus" environment as active.

In order to finish setting upyour Postman variables, please fill in the values bellow:

  • Client ID: The Client ID of your application (saved when creating the app, as explained in previous section). The Client ID value is attached to the X-IBM-Client-ID request header for authorization

    Client Secret: The Client Secret of your application (saved when creating the app, as explained in previous section). The Client Secret value is attached to the X-IBM-Client-Secret request header for authorization

  • X-Request-ID: You can use a randomly generated UUID.

You are now ready to run AISp& PISP scenarios.

3.2 Strong Customer Authentication (SCA)

Strong Customer Authentication is mandated for the initiation of payments as well as for the creation of consents for account access. There are multiple approaches for banking clients to grant TPPs safe and secure (authenticated and authorised) access to their bank accounts and financial data. The Cooperative Bank of Epirus Open API Sandbox utilizes a Redirect SCA Approach.

To simulate the SCA procedure for the purposes of the Sandbox, fake Customer Ids and corresponding IBANs are already defined within the Sandbox environment. In the table below, you can see the faked Sandbox IBANs.

User

IBANS

Credentials

Mock User 1

GR8107501009801770588393957

u: giorgos@epirusbank.com
p: 123456!

Mock User 2

GR9007501007753093378432248

u: ioannis@epirusbank.com
p: 123456@

Mock User 3

GR5607501004521225273494352

u: christina@epirusbank.com
p: 123456$

Mock User 4

GR8507501005521187326335827

u: maria@epirusbank.com
p: 123456#

When the IBAN within the request does not match the PSU-ID (as passed within a request), the SCA does not have an effect on the transaction or consent status. Not passing any PSU-ID will lead to a Format Error.

For the purposes of this guide, you will implement two common scenarios to demonstrate the functionality of the APIs. These scenarios include:

  • (AIS functionality) --> Get consent as TPP from a Cooperative Bank of Epirus customer and access his/her account balance.

  • (PIS functionality) --> Initiate a payment as a TPP, get consent from the customer and execute the payment.

3.3 AISP

This basic AISP scenario includes:

  1. Creation of a consent to access a PSU's account information

  2. Check that the consent request has been created by reading its status

  3. Since the SCA Redirect method is used, following the redirect link provided by the API to validate the TPP's request through SCA (emulated)

  4. Validation of the consent by mimicking the PSU SCA process

  5. Getting the list of all available accounts for the created consent

  6. Getting the account’s balance

In Postman, navigate to the EPIRUS_SANDBOX folder (the one you imported earlier). For the AIS scenario, open the AIS Consent folder. In addition, please make sure that the Sandbox Cooperative Bank of Epirus environment is selected. For information on the API calls and required parameters, please check the extensive API Documentation in the Developer Portal.

  1. Choose the createConsent POST call. This call creates a consent request to access a specific PSU's account data.

The PSU-ID header parameter is required. For the purposes of the Sandbox API, you can use a test username value as the PSU-ID within the Sandbox is mocked.

The X-IBM-Client-ID header parameter is required. This parameter refers to the Client ID value that you copied earlier from your Developer Portal Applications page.

The X-IBM-Client-Secret header parameter is required. This parameter refers to the Client Secret value you copied earlier from your Developer Portal Applications page.

The request Body is required. Specify the PSU account (use IBAN) and the type of account access (details, balances, transactions) using values from the IBAN table in the Strong Customer Authentication section of this guide. For the purposes of testing, a pre-defined body is included in the call (within the Postman collection) that requests access to account details, balances and transactions of a mock user’s account

Press “Send” and you should get a response indicating that the consent has been created, as well as the consentId and a scaRedirect link to validate the request.

2. Select the getConsentStatus GET call. The consentId is already included in the request path via a Postman script. Press “Send” and you should be able to see that the consent status is set to “Received” (RCVD).

3. You now need to authorize the consent that will be provided to the TPP by mimicking the PSU Authentication process to the Cooperative Bank of Epirus environment. Open the scaRedirect link from the initiatePayment call response in your browser. Normally this is the stepwhere the PSU enters his Cooperative Bank of Epirus credentials to login, but for the purposes of the Sandbox API a mocked authentication and SMS notification SCA is employed. In order to log in, provide the credentials listed in the table above.

4. Since the SMS OTP functionality is mocked for the purposes of the Sandbox, you can enter any number of digits to finish the authorization. Once the consent authorization is finished, you can now close your browser window.

5. Choose the getAccountList GET invocation and press “Send”. A successful response returns all the accounts that the user provided access to via the previous step.

6. Choose the getBalances GET invocation. In the query parameters, you need to fill the account-id parameter with one of the available IBANS that the user has provided access to. Please hit “Send” to get the account’s balance information.

(Optional) If you want to revoke a consent, you can Choose the deleteConsent DELETE invocation and press “Send”. The consentId included in the call will be revoked and access to the user’s accounts is no longer viable.


3.4 PISP

This basic PIS scenario includes:

  1. Sending a payment initiation request

  2. Checking that the payment request has been created

  3. Since SCA Redirect method is used, following the redirect link provided by the API to validate the request (emulated)

  4. Authorizing the payment by mimicking the PSU Authentication Process

  5. Verifying that the payment has been executed by checking its status

In Postman, navigate to the EPIRUS_SANDBOX folder (the one you imported earlier). For the PIS scenario, open the PIS Consent folder. Also, make sure the Sandbox Cooperative Bank of Epirus environment is selected. For information on the API calls and required parameters, please check the extensive API Documentation in the Developer Portal.

  1. Select the initiatePayment call.

The PSU-IP-Address header parameter is required. For the purposes of testing please use a mock value like “192.168.1.1”.

The X-IBM-Client-ID header parameter is required. This parameter refers to the Client ID value that you copied earlier from your Developer Portal Applications page.

The X-IBM-Client-Secret header parameter is required. This parameter refers to the Client Secret value you copied earlier from your Developer Portal Applications page.

The request Body is required. Please specify the Debtor’s account IBAN, the Creditor’s account IBAN and the amount to be transferred, as well as the address of the Creditor. You can use values from the IBAN table in the Strong Customer Authentication section of this guide. For the purposes of testing a pre-defined body is included in the invocation for your convenience.

Press “Send” and you should get a response indicating that the request has been received, as well as the paymentId of the payment and a scaRedirect link to validate the request.

2. Select the getPaymentInitiatonStatus GET invocation. Τhe paymentId is already included in the request path which is fetched automatically from the Postman test scripts. Press “Send” and you should be able to see that the payment status is set to “Received” (RCVD).

3. You now need to authorize the payment consent by mimicking the PSU Authentication Process in the Cooperative Bank of Epirus environment. Open the scaRedirect link from the initiatePayment invocation response in your browser. Normally this is the stepwhere the PSU enters his Cooperative Bank of Epirus credentials to login, but for the purposes of the Sandbox API a mocked authentication and SMS notification SCA is employed. In order to proceed with the SMS OTP verification, enter any number of digits and proceed, as the SMS functionality is mocked.

4. Click “Next”. Once you see the success message you can close your browser window.

5. Choose the getPaymentInitiationStatus GET invocation. You can verify that the payment status has been changed to Finalized (ACCC).

(Optional) If you want to cancel a payment, you can Choose the cancelPayment DELETE invocation and press “Send”, as this will cancel the payment referenced by the previous paymentId. Please keepin mind that you can only cancel payments that have not been authorized.

3.5 PIISP

For the purposes of the Sandbox, you can execute a confirmation of funds request without consent, as per the Berlin Groupspecification.

In Postman, navigate to the EPIRUS_SANDBOX folder (that you imported earlier). For the PIIS scenario and open the PIIS Consent folder. In addition, please make sure that the Sandbox Cooperative Bank of Epirus environment is selected. For information on the API calls and required parameters, please check the extensive API Documentation in the Developer Portal.

Choose the checkAvailabilityOfFunds POST call.

The X-IBM-Client-ID header parameter is required. This parameter refers to the Client ID value that you copied earlier from your Developer Portal Applications page.

The X-IBM-Client-Secret header parameter is required. This parameter refers to the Client Secret value you copied earlier from your Developer Portal Applications page.

The request Body is required. Specify the account that you wish to perform a funds availability check as well as the desired amount. You can use one of the IBANs provided in the SCA section of this guide.

Press “Send” and you should get a true/false response depending on whether the account has sufficient funds.