Documentation

Ready Immediately with the API Hub

Our API documentation is designed to help you develop your own Apps.

Register your developer account

Registering in the API Hub will give you access to the complete catalogue of all available Commerzbank APIs. You can register for free whenever you like: just click on “Register”.

Enter your fore- and surname, email address and telephone number (optional) and enter a password of your choice, which must be at least 8 characters long.

We’ll then email you an activation link. Once you’ve activated your account, you’ll be able to log in to our API Hub, browse the API Catalogue and register your App.

You can view and change your account details at any time simply by logging and clicking on “My Account”.



API catalogue

You’ll find all available Commerzbank APIs in the API Catalogue with its built-in search and filter function for easy navigation.

The key search criteria, such as API Category (e.g., credit or personal data), which you can also use for filtering are already shown in the overview. All APIs have a “Details” section where you can access further information as well as all technical details necessary for integration in your application.

Haven't found what you were looking for in our catalogue? Then simply contact us and let us know your specific requirements.



Register your app

  1. Register with Commerzbank API Hub by entering your personal registration details (name, email address) and specify a password.
  2. If you've already registered, you can log in directly by entering your email address and password.
  3. Click “Apps” in the navigation bar.
  4. Click on the “Create Application” button to register your App for sandbox trials.
  5. Give your App a name. You will also have the option to enter your email address, and telephone number as well as a short description of your App
  6. To successfully create your App, please ensure that you check the “Enable Authentication” box.
  7. Select the specific APIs you want for your App. To make it easier to assign them to your App, you can search for your favourite APIs. Your chosen APIs will be marked with a cross in the “Selected” column.
  8. Click “Save Application”. Your App is now registered: It is not necessary to resubmit the information you entered,
  9. as these will appear in the App Overview section, where you will now be able to find your registered App.
  10. Click on your App to access the “Details” section,
  11. where you can enter your credentials for later authentication for the sandbox under “API Key” or “OAuth Credentials”. To generate a credential, click “Edit the Application” and select your preferred authentication method (API Key or OAuth) and click on the “Generate” button to create your new credential.
  12. The new credential will now be displayed. To display the respective Secret Key, click the “Actions” button and select “View Secret”.
  13. Your App is now ready for development.
  14. To help with the development process, you can test your App in our sandbox using mock data. To use the sandbox, you will need to integrate the API Key or OAuth Credential you generated as well as the respective Secret Key into your App.

You can manage your registered Apps at any time after logging in by selecting “Apps” in the navigation bar after which you will be able to view the “Details” section, modify the App via the “Edit Application” button or delete it via the “Delete Application” button.



Test your app

To aid your development process, you can test the assigned APIs in the sandbox. Calling the API with the generated and valid authentication data will return mock data.



Using the API with real data

To use APIs with real data a Commerzbank transportation certificate (Client certificate signed by Commerzbank) is needed for security reasons. Our Support is looking forward to help you.

As things develop, you can view your App's utilisation statistics whenever you like simply by accessing your account.



Security

API Authorization Introduction

Before you can access a Commerzbank API in your client application, the client application needs to be authorized for the access. In case the API is delivering sensitive data from a customer, the access must be authorized by the costumer who is owning the data. In this case you must use the OAUTH 2.0 protocol for authorization. If no personal data is delivered by an API, the API can be accessed with an API key.

The information about OAUTH 2.0 or API key usage is documented for each API in the API catalogue.

OAuth 2.0

OAuth 2.0 is an industry-standard protocol for API authorization. OAuth 2.0 defines four logical roles:




OAuth Role Description
Resource Owner A person (e.g. Commerzbank customer) who grants your application access to personal data (e.g. account information). The resource owner is the user of your application.
Client The client is the application you are developing and that is attempting to get access to the resource owners Commerzbank data. In order to access the data, it needs to get permission from the resource owner.
Resource Server The resource server is the server hosting APIs, that you integrate in to your application to access the resource owner's data. The resource server is provided and controlled by Commerzbank.
Authorization Server The server is providing interfaces for requesting access tokens. The authorization server issues access tokens to the client application in order to access APIs. The authorization server is provided and controlled by Commerzbank.

API-Key

If no personal data is delivered from an API it can be accessed with an API Key.




Credential Registration

The image below shows how to register API Key and OAuth 2.0 Credentials in the developer portal:




API-Key Attributes

Attribute Description
API Key API-Key ID
Javascript Origin (Javascript Ursprünge) Not relevant
Created Date of creation
Actions/View Secret Displays the secret for the API Key


OAUTH Credentials Attributes

Attribute Description
Client ID Client Identifier
Type Confidential or public Client
Javascript Origin (Javascript Ursprünge) Not relevant
Redirect URLs A comma separated list with allowed redirect URLs
Created Date of creation
Actions/View Secret Displays the OAUTH secret for the client ID


OAUTH 2.0 Authorization Grant Types

OAuth 2.0 supports different methods in retrieving an Access Token from an authorization server. In OAUTH terms these different ways are called grant types. The following 3grant types are supported by Commerzbank Banking APIs.

Authorization Code Grant Type

This is the standard grant type if you want to access Commerzbank APIs. This type requires that a client should be able to keep a client secret confidential. In OAUTH terms such a client is called confidential. This grant type involves interaction with the resource owner.

Client Credentials Grant Type

The Client Credentials Grant type involves no resource owner authentication and interaction. Therefore, the client only sends the client ID and the corresponding secret to the authorization server in order to get an access token.

Refresh Token Grant Type

The Refresh Token Grant type is used to substitute a refresh token for an access token.

OAUTH Authorization Details

Authorization Code Grant Type



1. The customer Initiates the API call.

2. Authorization request from client application to Commerzbank.

                
HTTP/1.1 302 Moved Temporarily

Location: https://api.commerzbank.com/auth/realms/external/protocol/openid-connect/auth?

client_id={{Client_ID}}

&response_type=code&redirect_uri={{RedirectUri}}
                
            
Parameter Description
Client_ID Client Identifier
Redirect URLs A comma separated list with allowed redirect URLs

3. The customer logs in with his credentials (login).

4. The customer grants the client application the requested scope (consent).

5. The application receives the authorization code within the response of Commerzbank.

                
HTTP 302 Found??

Location: https://{{RedirectUri}}?code={{AuthorizationCode}} 
                
            

6. Substitution of authorization code for an access token. The client credentials are included (base 64 encoded) in the authorization header.

                
POST https://api.commerzbank.com/auth/realms/external/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id={{Client_ID}}&client_secret={{Secret}}&code=

{{AuthorizationCode}}
&redirect_uri={{RedirectURI}}
                
            

6.1 If you want to get the authorization code of a Sandbox-API you have to use the following URL:

                
https://api-sandbox.commerzbank.com/auth/realms/sandbox/protocol/openid-connect/token
                
            

7. An access token is delivered in the response from Commerzbank.

                
HTTP 200 OK

Content-type: application/json?
{?
    “access_token”: “1723ghhjkiu6trfref57thgjhg”,?
    “token_type”: “Bearer”,?
    "expires_in":900?
}
                
            

8. Access token (base 64 encoded in authorization header) allow to access a Commerzbank API.

                
GET https://api.commerzbank.com/api_operation 

Authorization: Bearer 1723ghhjkiu6trfref57thgjhg
                
            

Client Credentials Grant Type



1. The customer Initiates the API call.

2. Authorization request from client application to Commerzbank.

                
POST https://api.commerzbank.com/auth/realms/external/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={{Client_ID}}&client_secret={{Secret}}
                
            

3. An access token is delivered in the response from Commerzbank.

                
HTTP 200 OK

Content-type: application/json?
{?

    “access_token”: “1723ghhjkiu6trfref57thgjhg”,?
    “token_type”: “Bearer”,?
    "expires_in":900?
    "refresh_token":" fdb8 ... 209c "?
}
                
            

4. Access token (base 64 encoded in authorization header) allow to access a Commerzbank API.

                
GET https://api.commerzbank.com/api_operation 

Authorization: Bearer 1723ghhjkiu6trfref57thgjhg
                
            

Refresh Token Grant Type



1. Substitution of a refresh token for an access token.

                
POST https://api.commerzbank.com/auth/realms/external/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

refresh_token=fdb8 ... 209c&grant_type=refresh_token
                
            

2. An access token is delivered in the response from Commerzbank.

                
HTTP 200 OK

Content-type: application/json?
{?
    “access_token”: “1723ghhjkiu6trfref57thgjhg”,?
    “token_type”: “Bearer”,?
    "expires_in":900?,
    "refresh_token":" dfb8 ... 5784x "?
}
                
            

3. Access token (base 64 encoded in authorization header) allow to access a Commerzbank API.

Sandbox Security

We offer you for testing the selected APIs a dedicated sandbox in order to support your development. An API request with the generated and valid authentication method leads to response based on test values (i.e. mock-data).

The security mechanisms of the sandbox are the same of the productive environment. The In contrast to productive environment, the sandbox has no consent page for the authorization code grant flow. The consent is here implicitly realized and allows you to test the productive security pattern already in sandbox environment.

Therefore, the following test credentials can be applied:

ID: 1234567890

Password: 12345

With these credentials a user login can be operated.