Getting started

A “how-to” guide to use our banking APIs

As a third party app provider, go through the following steps in order to use our APIs :

1. Explore 
   Navigate through our API products catalogue and leverage the wide range of opportunities given 
   Group API Products catalog
2. Sign-up 
   Create your account Sign up
3. Try the APIs 
   Try the APIs using the built-in testing functionality to get an understanding of how it works.
4. Create and register your Sandbox Application 
   Register an Application in your Account Profile to get your Client ID and Secret. Subscribe to one or more of our sandbox products that fit your needs in order to receive your subscription keys.
5. Test 
   Use the sandbox environment to get familiar with the Alpha Bank products, explore their features and test your applications with the provided sample data. The sandbox features the same functionality as the production APIs, so you can be sure that your applications will integrate smoothly with the production APIs.
6. Create and register your Production Application
   When you’re finished testing, submit your application for the production data, upload any certificate required (e.g. eIDAS for PSD2 API Products), subscribe to our Production APIs, get authorized and go live!

Download Open API Specification Documentation

Download Open API Specification (YAML)

API endpoints

The APIs are accessible at the following URLs. Refer to the API documentation above for details on the endpoints.

 

Authentication and Authorisation

The use of the offered APIs is protected by an authentication/authorisation server (Auth server). The server is compliant with the OAuth2 standard and accessible at the following endpoints.

 

The use of specific grant types and/or scopes is required at specific cases during the flow of using the offered functionality.

The basic concept behind the main usage scenarios is based on a two-phase execution. The first phase is related to the creation of an intent object by the client application. The second phase is about the authorisation of this intent object by the end user and the use of the required API operations.

Message Signing

 

All inbound HTTP requests to the Alpha Bank's API endpoints must be digitally signed using an eIDAS certificate with QSealC profile (as defined in ETSI TS 119 495) for all cases that the request carries a payload.

When a client application is registered to the portal, the developer is responsible to submit at least one certificate in Base-64 format, which will be used to sign the client application payloads. The signature must be attached to every client application request. The API will validate this signature against the uploaded application certificate. In case of a missing/invalid signature header, or invalid (expired or revoked) certificate, the request is ignored and the client application that made the calls receives an Http 400 (Bad request) error.

A similar to the aforementioned process applies to the responses sent from the bank’s servers. All the returned payloads are signed using Alpha Bank’s certificates and the client applications have to validate the signature header. Depending on the bank, bellow is the list of active Alpha Bank’s certificates.

Required Certificate

In order to sign your requests, an appropriate certificate must first be uploaded for your client in the developers' portal. The upload of a new certificate is not automatically active and must be manually approved by an internal process in the Bank.

The requirements for the certificate are as follows:

• must be an eIDAS certificate (Directive 1999/93/EC)
• must be of type QSealC
• must conform with ETSI TS 119 495 and contain one of the following policies:

QCP-l: certificate policy for EU qualified certificates issued to legal persons;
itu-t(0) identified-organization(4) etsi(0) qualified-certificate-policies(194112) policy-identifiers(1) qcp-legal (1)
0.4.0.194112.1.1

QCP-l-qscd: certificate policy for EU qualified certificates issued to legal persons with private key related to the certified public key in a QSCD;
itu-t(0) identified-organization(4) etsi(0) qualified-certificate-policies(194112) policy-identifiers(1) qcp-legal-qscd (3)
0.4.0.194112.1.3

The certificate you submit must be in Base-64 format. After uploading the certificate, a number of 'API Products' will be unlocked according to the roles (AISP, PISP, CBIIP) defined within your certificate. You can subscribe to one or more of these products.

The signature must be attached to every client application request. The API will validate this signature against the uploaded application certificate. In case of a missing/invalid signature header, or invalid (expired or revoked) certificate, the request is ignored and the client application that made the calls receives an Http 400 (Bad request) error.

JSON Web Signature

JSON Web Signature (JWS) represents content secured with digital signatures using JSON-based data structures. Based on the RFC 7515 – Appendix F, the signing is performed using a JWS with detached content, and the HTTP body contains the un-encoded payload as defined in RFC 7797. The JWS must be signed using the algorithm RS256 that supports asymmetric keys. The TPP’s private key is used to sign the requests to the ASPSP, and the ASPSP’s private key is used to sign the responses to the TPPs.

Process for Signing Payloads

1. The signer must use the private key of the certificate. At the time of the singing, the following requirements must be met.
   1. The certificate is valid
   2. The certificate has already been provided to the Alpha Bank Group API Portal, under the client application that will make the request.
2. As described in the following table, the JOSE header must contain the subsequent fields.
   

   Claim	Description
   alg	The algorithm used for signing. It must be set to RS256.
   typ	This is an optional claim. If it is specified, it must be set to the value "JOSE"
   cty	This is an optional claim. If it is specified, it must be set to the value "application/json".
   kid	This must match the thumbprint value of the certificate. Possible spaces within the value must be removed.
   iat	This must be a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in GMT until the date/time.

3. The signature must be computed as defined in RFC 7515 – Appendix F.
4. The HTTP header called x-jws-signature must be included, along with the computed during the previous step, value.

Example of JWS signature

x-jws-signature : eyJhbGciOiJSUzI1NiIsInR5cCI6IkpPU0UiLCJjdHkiOiJhcHBsaWNhdGlvbi9qc29uIiwia2lkIjoiZDZiZmM0NzFkY2IyMmUyMDk1NGRlZWEwNWVmY2M1NzU4YWE0MmJkYyIsImlhdCI6MTYxNTI4OTIwNX0..-6JcsL7aRYfkKB81EQcGH_TEsZ2tsqQoLHZVVPW-vE6pXTelExVmAH7AcpOCeCaStyh0bN-aK9LelU9lKER_Q1lHTHfhmnX6vByDXlkxEFfw0WqXQgznTpMdmvKPz7U8ID2UE_Hf5z805xHgZTDYmsePu5pMXdUuS-BHTxPtfYItohHD6DElzP4efjoCxUk-n5zboCUOSLkDVFbTix6gQhhhKLcs7UJ9IaWMwnbg5vPAauu9fxSgT1QcZ1kkH0LRbXsj_uDB3XtQi-FupxRPM2Zhzb7bmHlpM7OQUdOowv_WyLReI1GBftSwmJWZz2CPc3EC3G2dgbxFSDVnTVvdVw

Learn more about How to sign your request payload

Process for verifying signatures

1. The verifier must extract the claims from the HTPP header named x-jws-signature.
2. The JOSE header must be validated according to the values described in the previous table
3. The verifier must retrieve the certificate with the specified kid value. The kid value is equivalent to the certificate thumbprint.
4. The verifier must ensure that the retrieved certificate is valid.
5. The verifier must verify the signature as defined in RFC 7515, Appendix F.

Sample of decoded Jose header

{
    "alg": "RS256",
    "typ": "JOSE",
    "cty": "application/json",
    "kid": "d6bfc471dcb22e20954deea05efcc5758aa42bdc",
    "iat": 1615289205
}

Creation of an intent object

The creation of the intent object is performed by the client application alone without an intervention by the end user. This phase includes two steps. The first step is the acquisition of an access token from the authorization server token endpoint using client credentials. The credentials are provided to the requests using HTTP basic authentication.

Supplying this access token to the appropriate intent object generation API operation (using the Authorisation header), the client application asks for the generation of an intent object (account information or payment intent object). The API operation responds with an intent identifier.

Authorisation of the intent object

This second phase is about authorising the intent object created during the first phase described above. This authorisation is performed as an authorisation code three-legged OAuth2 flow.

The end-user is redirected by the client application to the authorisation endpoint of the Auth server and the UI is presented to the end-user using the default operating system web browser. The parameters to the authorisation request are:

A successful request to the authorisation endpoint with the parameters above results in the rendering of an authentication interface. The end user is asked for his username, password in the Alpha Bank e-Banking. The authentication is performed at the Alpha Bank e-Banking backend systems.

After authenticated (logging-in) the end-user is presented with a consent screen, which reflects a representation of the intent object created during the first phase. In case of account-information request intent object the end user is asked for giving authorisation to the client application to make calls to the account information and transactions only API operations on behalf of the end user for a given duration.

In the case of a Payment intent, the end user is presented with the details of the intended payment, such as creditor information, amount, expenses, etc. The user is asked for selecting his account to be used for the payment (if not preselected) and a second-factor authentication if necessary.

Upon acknowledging the authorisation of the client application, the authorisation server responds with and authorisation code. This authorisation code is subsequently used by the client application in order to acquire an intent object bound access token. The access token is acquired with a request to the token endpoint using the following parameters.

The result of the call to the token endpoint is a new access-token which is bound to the specific intent object. This access token is then used (as value to the Authorisation header) by the client application with any request related to the execution of the intent object.

Sandbox

Use the sandbox environment to get familiar with the Alpha Bank products, explore their features and test your applications with the provided sample data. For the scope of the sandbox we have created a set of non-real accounts that you can use to develop your applications. To get access to these sample accounts, use one of the following test users when you get redirected to the Alpha bank login screen.

Remember to review the documentation of each API and test them before you start using them.

The sandbox features the same functionality as the production APIs, so you can be sure that your applications will integrate smoothly with the production APIs.

Here is a more detailed explanation of the required steps in order to get Account Details for the first time.

1. Get access token with client credentials in order to create an account request

To retrieve your client credentials and subscription keys, navigate to your Profile > Client Apps section. 

    > curl -X POST -i https://gw.api.alphabank.eu/sandbox/auth/token \

    -u "{{client_id}}:{{client_secret}}" \

    -d "grant_type=client_credentials&scope=account-info-setup"

In exchange for these credentials, the authorization server returns an access token in the access_token field.

2. Create an account request

Include your subscription_key in the Ocp-Apim-Subscription-Key header and the access_token in the Authorization header with the Bearer authentication scheme.

    > curl -X POST -i https://gw.api.alphabank.eu/api/sandbox/accounts/v1/account-requests \

    -H "Content-Type: application/json" \

    -H "Authorization: Bearer {{access_token}}" \

    -H "Ocp-Apim-Subscription-Key: {{subscription_key}}" \

    -H "x-jws-signature: {{jws_signature}}" \

    -d "{\"Risk\": {},\"ProductIdentifiers\":null}"

3. Authorize the account request

    Example URL

    https://gw.api.alphabank.eu/sandbox/auth/authorize?client_id={{client_id}}&response_type=code&scope=account-info&redirect_uri={{redirect_uri}}&request={{account_request_id}}

Once you have received the authorisation code, you can exchange it for an access token.

4. Exchange the authorization code for access token

    > curl -X POST -i https://gw.api.alphabank.eu/sandbox/auth/token \

    -H "Content-Type: application/x-www-form-urlencoded" \

    -d "grant_type=authorization_code&code={{code}}&client_id={{client_id}}&client_secret={{client_secret}}&redirect_uri={{redirect_uri}}"

Once you get your access token, you can call any of the API endpoints.

5. Get Account Details

    > curl -X GET -i https://gw.api.alphabank.eu/api/sandbox/accounts/v1/details \

    -H "Authorization: Bearer {{access_token}}" \

    -H "Content-Type: application/x-www-form-urlencoded" \

    -H "Ocp-Apim-Subscription-Key: {{subscription_key}}"

Date filtering and Pagination

A number of operations support date filtering for the records returned. In these cases the optional parameters fromDate, toDate can be used to limit the time period of the results. Both of those fields expect a value to be provided in ISO 8601 Date Time format. If no value is provided for these parameters, default values are being assigned instead, depending on the operation. There are also limitations regarding how far in the past can the query be requested, also dependent upon the type of operation.

A number of operations also support results pagination. In these cases an optional header "x-ab-locator" is being used. If no value is provided for the header, the most recent records are being returned. The locator header is always being returned at the http response of the API call, along with the results, regardless of whether or not it was provided at the request. In order to retrieve the entirety of the results, you should keep making additional requests, with the same parameters, while also adding the previously retrieved locator header and its value to the request. If the header value is anything other than the default (0000000000000000000), then more records are available for the specified request.