Authentication

To manage the data via our API your application needs to gain access on behalf of the user. This is done through obtaining an access token via OAuth2. The access token must then be send in each request in the HTTP header like this: “Authorization: Bearer TOKEN”.

If you just want to explore the API you can use the Playground which will automatically create and insert such an access token to the HTTP header.

When you want to create your own application you need two kinds of credentials to get such a token: The first part is a fixed pair of client id and client secret. They identify your client application which connects to the API. Each application has its own pair of client id and secret, please use the API Client Management to create your own client credentials.

The second part is obtained through the user and can be done in several ways, here we describe the preferred way through the “Authorization Code” grant type. If you want to develop a pure web application you must use PKCE to not expose the client secret.

Authorization Code

In general, the process looks like this:

  1. You redirect the user in a browser to an url on our end.
  2. The user is required to login and needs to accept your application’s authorization request. The browser redirects back to your application with a code parameter.
  3. Your application can then exchange this code together with the client_secret into an access_token through a backend request to our API.

Let us go through the process step by step. At first we need to send the user to a special url in the browser:

https://api.kontist.com/api/oauth/authorize?scope=offline&response_type=code&client_id=78b5c170-a600-4193-978c-e6cb3018dba9&redirect_uri=https://your-application/callback&state=OPAQUE_VALUE

Adjust the parameters like this:

Parameter Description
scope Space delimited list of scopes your application is going to access. Please see the list below.
response_type Set fixed as “code”.
client_id This is your client id you got from us. Do not include the secret here.
redirect_uri This is your application’s callback url which is bound to your client id.
state Can be used to verify our response. You can put in anything here and we will send it back to your application later.

Response case 1: The user denied giving access to your application:

The browser is being redirected to your url with an error parameter attached.

https://your-application/callback?state=OPAQUE_VALUE&error=%7B%22type%22%3A%22AccessDeniedError%22%7D

Your application might then inform the user that you can not continue without granting access.

Response case 2: The user accepted giving access to your application:

The browser is being redirected to your url with a code parameter attached.

https://your-application/callback?code=59f53e7cfcf12f1d36e2fb56bb46b8d116fb8406&state=OPAQUE_VALUE

You can now create a request in the backend to exchange the code into an access token.

curl https://api.kontist.com/api/oauth/token \
  -X POST \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d grant_type=authorization_code \
  -d code=59f53e7cfcf12f1d36e2fb56bb46b8d116fb8406 \
  -d client_id=78b5c170-a600-4193-978c-e6cb3018dba9 \
  -d client_secret=my-secret \
  -d redirect_uri=https://your-application/callback

This request needs to contain the client secret and should be done from your backend and not in the frontend to keep the secret confidential.

The result is a JSON object which will look like this:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NzIyODljMy1hNDk4LTQzMDItYjk3My1hNDRlYzdjZDRmZTMiLCJzY29wZSI6Im9mZmxpbmUiLCJjbGllbnRfaWQiOiI3OGI1YzE3MC1hNjAwLTQxOTMtOTc4Yy1lNmNiMzAxOGRiYTkiLCJpYXQiOjE1NjkyMjY3MDksImV4cCI6MTU2OTIzMDMwOX0.XwkfN1jJ_0C5gSIlzvOHRovmbzbpOXRpZ6HCOg1I7j0",
  "token_type": "Bearer",
  "expires_in": 3599,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NzIyODljMy1hNDk4LTQzMDItYjk3My1hNDRlYzdjZDRmZTMiLCJzY29wZSI6InJlZnJlc2ggb2ZmbGluZSIsImNsaWVudF9pZCI6Ijc4YjVjMTcwLWE2MDAtNDE5My05NzhjLWU2Y2IzMDE4ZGJhOSIsImlhdCI6MTU2OTIyNjcwOSwiZXhwIjoxNTY5MjMzOTA5fQ.GggO8EQznEH70PTRvicEYxj40oF_RQdHZlJw0jf41xQ",
  "scope": "offline"
}

Extract the access_token and use it in your requests by adding the Authorization: Bearer access_token header to your requests. See this example:

curl --request POST \
  --url https://api.kontist.com/api/graphql \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NzIyODljMy1hNDk4LTQzMDItYjk3My1hNDRlYzdjZDRmZTMiLCJzY29wZSI6Im9mZmxpbmUiLCJjbGllbnRfaWQiOiI3OGI1YzE3MC1hNjAwLTQxOTMtOTc4Yy1lNmNiMzAxOGRiYTkiLCJpYXQiOjE1NjkyMjY3MDksImV4cCI6MTU2OTIzMDMwOX0.XwkfN1jJ_0C5gSIlzvOHRovmbzbpOXRpZ6HCOg1I7j0' \
  --header 'content-type: application/json' \
  --data '{ "query": "{viewer{id}}" }'

Refresh Token

The access token obtained in the previous section does expire after some time. If you did specify the “offline” scope you can use the refresh_token from the first response to create a new access token.

curl https://api.kontist.com/api/oauth/token \
  -X POST \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d grant_type=refresh_token \
  -d client_id=78b5c170-a600-4193-978c-e6cb3018dba9 \
  -d client_secret=my-secret \
  -d refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NzIyODljMy1hNDk4LTQzMDItYjk3My1hNDRlYzdjZDRmZTMiLCJzY29wZSI6InJlZnJlc2ggb2ZmbGluZSIsImNsaWVudF9pZCI6Ijc4YjVjMTcwLWE2MDAtNDE5My05NzhjLWU2Y2IzMDE4ZGJhOSIsImlhdCI6MTU2OTIyNjcwOSwiZXhwIjoxNTY5MjMzOTA5fQ.GggO8EQznEH70PTRvicEYxj40oF_RQdHZlJw0jf41xQ

Response is again a JSON object, similar to the original one:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NzIyODljMy1hNDk4LTQzMDItYjk3My1hNDRlYzdjZDRmZTMiLCJzY29wZSI6Im9mZmxpbmUiLCJjbGllbnRfaWQiOiI3OGI1YzE3MC1hNjAwLTQxOTMtOTc4Yy1lNmNiMzAxOGRiYTkiLCJpYXQiOjE1NjkyMjY5MTksImV4cCI6MTU2OTIzMDUxOX0.CkxIJ2OmXMovqhJhNjQJvI7FMlSMdFTRgheWYTcLMUQ",
  "token_type": "Bearer",
  "expires_in": 3599,
  "scope": "offline"
}

You can use the refresh token multiple times until the refresh token expires itself and you need to go through the process again.

PKCE Extension for Authorization Code

The standarad Authorization Code flow uses client secrets to grant access tokens, however this is not always practical: some environments can’t securely store such a secret (e.g. a single page web application).

For these environments, we can use the Proof Key for Code Exchange (PKCE) extension for the Authorization Code flow.

The PKCE-enhanced Authorization Code flow is very similar to the standard Authorization Code flow and uses a concept of Code Verifier which we will have to generate client side. This code verifier will be hashed and sent as a code_challenge parameter to the /authorize endpoint, and then sent in plain along with the authorization code when requesting the access token.

To generate the code verifier, it is recommended to use the output of a random number generator.

Once the code verifier has been generated, we will need to transform it to a code challenge:

  • First hash it using the SHA256 hash function
  • Then encode it to a base64 string
  • And finally, remove padding from the base64 encoded string (as defined in: https://tools.ietf.org/html/rfc7636#appendix-A)

Here is sample javascript code to perform the transformation:

const code_challenge = base64encode(sha256(code_verifier))
  .split("=")[0]
  .replace("+", "-")
  .replace("/", "_");

We will then take users to the authorization url, providing code_challenge and code_challenge_method:

https://api.kontist.com/api/oauth/authorize?scope=transactions&response_type=code&client_id=78b5c170-a600-4193-978c-e6cb3018dba9&redirect_uri=https://your-application/callback&state=OPAQUE_VALUE&code_challenge_method=S256&code_challenge=xc3uY4-XMuobNWXzzfEqbYx3rUYBH69_zu4EFQIJH8w

The parameters are the same as for the standard Authorization Code flow, with these additional parameters:

Parameter Description
code_challenge Code challenge generated from the code verifier.
code_challenge_method Code challenge method, only “S256” is supported.

After the user has accepted the access request, you will be able to obtain an access token with the code you received and the code verifier you used to generate the code challenge (without specifying the client_secret):

curl https://api.kontist.com/api/oauth/token \
  -X POST \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d grant_type=authorization_code \
  -d code=59f53e7cfcf12f1d36e2fb56bb46b8d116fb8406 \
  -d client_id=78b5c170-a600-4193-978c-e6cb3018dba9 \
  -d redirect_uri=https://your-application/callback \
  -d code_verifier=7963393253896189

Note: Using the PKCE flow will not grant you refresh tokens, even if you specify the offline scope. In order to renew an access token when using this authorization flow, you can use the method described below. The above restriction does not apply if you are using a custom scheme for your application (and thus for your redirect_uri, e.g. my-app://callback-uri).

Renewing access tokens with PKCE

As you will not get refresh tokens when using the PKCE authorization method, you can use an alternative method leveraging session cookies.

If a user has granted access with the PKCE authorization flow, the successful authorization will be saved to this user’s session, and you will be able to obtain a new access token without prompting the user by specifying prompt=none when accessing the authorization url:

https://api.kontist.com/api/oauth/authorize?scope=transactions&response_type=code&client_id=78b5c170-a600-4193-978c-e6cb3018dba9&redirect_uri=https://your-application/callback&state=OPAQUE_VALUE&code_challenge_method=S256&code_challenge=xc3uY4-XMuobNWXzzfEqbYx3rUYBH69_zu4EFQIJH8w&prompt=none

The user will be redirected directly to your application with a new authorization code that you can use to request a new access token.

Renewing access token with Web Message Response Mode

While the above method will work for Single Page Applications (SPA), it has the downside of doing redirects, and SPA client application state will be lost.

To work around this issue, we can use the web message response type by following these steps:

  1. Setup a web message listener to get the authorization code:
      window.addEventListener("message", event => {
     if (event.origin === "https://api.kontist.com") {
       const { code } = event.data.response;
     }
      });
    
  2. Create an iframe and set its source to the authorization url, specifying response_mode=web_message:
      const iframe = document.createElement("iframe");
      iframe.style.display = "none";
      document.body.appendChild(iframe);
      iframe.src = "https://api.kontist.com/api/oauth/authorize?scope=transactions&response_type=code&client_id=78b5c170-a600-4193-978c-e6cb3018dba9&redirect_uri=https://your-application/callback&state=OPAQUE_VALUE&code_challenge_method=S256&code_challenge=xc3uY4-XMuobNWXzzfEqbYx3rUYBH69_zu4EFQIJH8w&prompt=none&response_mode=web_message"
    
  3. The server will then send a web message with the new authorization code that we can use to get a new access token

Multi-Factor Authentication

To have access to Kontist API endpoints that require strong customer authentication, you need to pass Multi-Factor Authentication (MFA).

We provide a simplified push notification MFA flow for users who have installed the Kontist Application and paired their device in it.

Creating a challenge

To initiate the MFA procedure, you will need to create an MFA Challenge:

curl "https://api.kontist.com/api/user/mfa/challenges" \
  -H "Authorization: Bearer ey..." \
  -X POST

The above command returns JSON structured like this:

{
  "id": "5f7c36e2-e0bf-4755-8376-ac6d0711192e",
  "status": "PENDING",
  "expiresAt": "2019-12-02T16:25:15.933+00:00"
}
HTTP Request

POST https://api.kontist.com/api/user/mfa/challenges

Response
Field Description
id ID of the challenge.
status Status of the challenge. One of PENDING, VERIFIED, DENIED. When created, it will be “PENDING”.
expiresAt Time at which the challenge will expire.

Verifying a challenge

The next step to pass MFA is to verify the challenge that was just created.

The Kontist user will receive a push notification on his device prompting him to “Confirm login”. After logging into the application and confirming, the challenge will be verified (its status will be updated to VERIFIED).

Polling for challenge verification

Once a challenge has been created and you are waiting for its verification, you can periodically access the below endpoint until the status changes to VERIFIED or DENIED:

curl "https://api.kontist.com/api/user/mfa/challenges/5f7c36e2-e0bf-4755-8376-ac6d0711192e" \
  -H "Authorization: Bearer ey..." \
  -X GET

The above command returns JSON structured like this:

{
  "id": "5f7c36e2-e0bf-4755-8376-ac6d0711192e",
  "status": "VERIFIED",
  "expiresAt": "2019-12-02T16:25:15.933+00:00"
}
HTTP Request

GET https://api.kontist.com/api/user/mfa/challenges/{challenge_id}

Response
Field Description
id ID of the challenge.
status Status of the challenge. One of PENDING, VERIFIED, DENIED.
expiresAt Time at which the challenge will expire.

Getting a confirmed token

Once the challenge has been verified (status updated to VERIFIED), you can obtain one (and only one) confirmed access token.

If the OAuth2 client involved uses refresh tokens, you will also obtain a confirmed refresh token with the response. Such a refresh token can be used to renew confirmed access tokens. This will allow you to perform the MFA procedure only once for the whole lifetime of your refresh token.

curl "https://api.kontist.com/api/user/mfa/challenges/5f7c36e2-e0bf-4755-8376-ac6d0711192e/token" \
  -H "Authorization: Bearer ey..." \
  -X POST

The above command returns JSON structured like this:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI4ODNjNTc4ZS01M2QwLTRhYmEtOTBiNC02MmRmZmFkNTE5NTMiLCJzY29wZSI6ImF1dGgiLCJjbmYiOnsia2lkIjoiMmExNjRlYzYtZTJkNC00OTI4LTk5NDItZDU5YWI2Yzc4ZDU5In0sImlhdCI6MTU2NzQwOTExNSwiZXhwIjoxNTY3NDEyNzE1fQ.m35NDpQMAB5DMebXUxEzWupP3i-iAwoyVy2sGF1zp_8",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwMTIwMmUwZi0yOWE4LTRlNDgtODcyNi01OGFiMDAxNDBiNTgiLCJzY29wZSI6InJlZnJlc2ggYWNjb3VudHMgb2ZmbGluZSIsImNsaWVudF9pZCI6IjU4NjcwYmRhLWQxZDEtNGJlOC1hZGEyLTcwNjFkZWVhYjMxNyIsImNuZiI6eyJraWQiOiJlNTA3NTQ5NC1iNWM0LTRjYTEtYjE4MC01ZjNjNTBhNjA2OWMifSwiaWF0IjoxNTc2ODM2MDU5LCJleHAiOjE1NzY4NDMyNTl9.DydSAzxAFncGlWQMNZZp4q48EjAoz6FR6IboxTPx2j4"
}
HTTP Request

POST https://api.kontist.com/api/user/mfa/challenges/{challenge_id}/token

Response
Field Description
token Auth token with confirmation claim that should be used for endpoints that require strong customer authentication.
refresh_token Refresh token with confirmation claim that can be used to renew confirmed access tokens.

Scopes

  • accounts
  • clients (manage OAuth2 clients, usually not required)
  • offline (required for refresh token)
  • statements
  • subscriptions
  • transactions
  • transfers
  • users

Advanced Topics

Some clients might use device binding with certificates as MFA or make use of other OAuth2 grant types. This depends on the environment where this application will run. Please see our advanced topics on authentication.

Using the GraphQL API

Fetch transactions

Transactions are returned using the Connection pattern to allow pagination. A simple query showing the first 3 transactions may look like this:

{
  viewer {
    mainAccount {
      transactions(first: 3) {
        edges {
          node {
            name
            amount
            iban
          }
        }
      }
    }
  }
}

Just send the query inside of a POST request to /api/graphl and wrap it into a query property.

curl --request POST \
  --url https://api.kontist.com/api/graphql \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NzIyODljMy1hNDk4LTQzMDItYjk3My1hNDRlYzdjZDRmZTMiLCJzY29wZSI6Im9mZmxpbmUiLCJjbGllbnRfaWQiOiI3OGI1YzE3MC1hNjAwLTQxOTMtOTc4Yy1lNmNiMzAxOGRiYTkiLCJpYXQiOjE1NjkyMjY3MDksImV4cCI6MTU2OTIzMDMwOX0.XwkfN1jJ_0C5gSIlzvOHRovmbzbpOXRpZ6HCOg1I7j0' \
  --header 'content-type: application/json' \
  --data '{ "query": "{viewer{mainAccount{...}}}" }'

Result:

{
  "data": {
    "viewer": {
      "mainAccount": {
        "transactions": {
          "edges": [
            {
              "node": {
                "name": "Autoservice Gmbh",
                "amount": -16700,
                "iban": "DE89370400440532013000"
              }
            },
            {
              "node": {
                "name": "John Doe",
                "amount": 84609,
                "iban": "DE89370400440532013000"
              }
            },
            {
              "node": {
                "name": "John Doe",
                "amount": 13900,
                "iban": "DE89370400440532013000"
              }
            }
          ]
        }
      }
    }
  }
}

Create a new transfer

Creating transfers consist of two steps. First the transfer is created with createTransfer which will return the confirmationId of the new transfer. Then we send a SMS to the user that contains a code and we need to call confirmTransfer.

1. Step - add a new transfer

mutation {
  createTransfer(
    transfer: { iban: "DE1234....", recipient: "Johnny Cash", amount: 1234 }
  ) {
    id
  }
}

2. Step - verify the transfer

mutation {
  confirmTransfer(transferId: "1234", authorizationToken: "4567") {
    id
    recipient
  }
}

GraphQL Models

Query

Field Argument Type Description
viewer User! The current user information

Mutation

Field Argument Type Description
cancelTransfer ConfirmationRequestOrTransfer! Cancel an existing Timed Order or Standing Order
id String!
type TransferType!
confirmCancelTransfer Transfer! Confirm a Standing Order cancelation
authorizationToken String! The confirmation token received by SMS on the user's phone
confirmationId String!
type TransferType!
createClient Client! Create an OAuth2 client
client CreateClientInput!
updateClient Client! Update an OAuth2 client
client UpdateClientInput!
deleteClient Client! Delete an OAuth2 client
id String!
createTransfer ConfirmationRequest! Create a transfer. The transfer's type will be determined based on the provided input
transfer CreateTransferInput!
updateTransfer ConfirmationRequest!
transfer UpdateTransferInput!
confirmTransfer Transfer! Confirm a transfer creation
authorizationToken String! The confirmation token received by SMS on the user's phone
confirmationId String!
createTransfers ConfirmationRequest! Create multiple transfers at once. Only regular SEPA Transfers are supported
transfers [CreateSepaTransferInput!]!
confirmTransfers BatchTransfer! Confirm the transfers creation
authorizationToken String! The confirmation token received by SMS on the user's phone
confirmationId String!
whitelistCard WhitelistCardResponse!
fraudCaseId String!
id String!
confirmFraud ConfirmFraudResponse!
fraudCaseId String!
id String!
createCard Card! Create a new card
type CardType!
activateCard Card! Activate a card
verificationToken String!
id String!
updateCardSettings CardSettings! Update settings (e.g. limits)
settings CardSettingsInput!
id String!
changeCardStatus Card! Block or unblock or close a card
id String!
action CardAction!
changeCardPIN ConfirmationRequest! Set a new PIN, needs to be confirmed
pin String!
id String!
confirmChangeCardPIN ConfirmationStatus! Confirm a PIN change request
authorizationToken String!
confirmationId String!
id String!
replaceCard Card! Call when customer's card is lost or stolen
id String!
reorderCard Card! Close and order new card. Call when customer's card is damaged
id String!
categorizeTransaction Transaction! Categorize a transaction with an optional custom booking date for VAT or Tax categories
id String!
category TransactionCategory
userSelectedBookingDate DateTime When a transaction corresponds to a tax or vat payment, the user may specify at which date it should be considered booked

Objects

Account

The bank account of the current user

Field Argument Type Description
iban String!
cardHolderRepresentation String
balance Int!
cardHolderRepresentations [String!]!
transfers TransfersConnection!
where TransfersConnectionFilter
type TransferType!
first Int The number of items to return after the provided cursor up to 50
last Int The number of items to return before the provided cursor up to 50
after String The cursor of the item to start from. Use in conjunction with 'first'
before String The cursor of the item to start from. Use in conjunction with 'last'
transaction Transaction
id ID!
transactions TransactionsConnection!
first Int The number of items to return after the provided cursor up to 50
last Int The number of items to return before the provided cursor up to 50
after String The cursor of the item to start from. Use in conjunction with 'first'
before String The cursor of the item to start from. Use in conjunction with 'last'
transfer Transfer
id ID!
type TransferType!
transferSuggestions [TransferSuggestion!] A list of iban/name combinations based on existing user's transactions, provided to assist users when creating new transfers
cards [Card!]!
card Card
filter CardFilter

BatchTransfer

Field Argument Type Description
id String!
status BatchTransferStatus!
transfers [SepaTransfer!]!

Card

Field Argument Type Description
id String!
status CardStatus!
type CardType!
pinSet Boolean!
holder String
formattedExpirationDate String
maskedPan String
settings CardSettings!

CardLimit

Field Argument Type Description
maxAmountCents Float!
maxTransactions Float!

CardLimits

Field Argument Type Description
daily CardLimit!
monthly CardLimit!

CardSettings

Field Argument Type Description
contactlessEnabled Boolean!
cardPresentLimits CardLimits
cardNotPresentLimits CardLimits

Client

Field Argument Type Description
id ID!
redirectUri String The URL to redirect to after authentication
name String! The name of the OAuth2 client displayed when users log in
grantTypes [GrantType!] The grant types (i.e. ways to obtain access tokens) allowed for the client
scopes [ScopeType!] The scopes the client has access to, limiting access to the corresponding parts of the API

ConfirmFraudResponse

Field Argument Type Description
id String!
resolution String!

ConfirmationRequest

Field Argument Type Description
confirmationId String!

ConfirmationStatus

Field Argument Type Description
status String!

DirectDebitFee

Field Argument Type Description
id Int!
type TransactionFeeType!
amount Int!
usedAt DateTime
invoiceStatus InvoiceStatus!

PageInfo

Field Argument Type Description
startCursor String
endCursor String
hasNextPage Boolean!
hasPreviousPage Boolean!

SepaTransfer

Field Argument Type Description
status SepaTransferStatus! The status of the SEPA Transfer
amount Int! The amount of the SEPA Transfer in cents
purpose String The purpose of the SEPA Transfer - 140 max characters
id String!
recipient String! The name of the SEPA Transfer recipient
iban String! The IBAN of the SEPA Transfer recipient
e2eId String The end to end ID of the SEPA Transfer

StandingOrder

Field Argument Type Description
id String!
status StandingOrderStatus! The status of the Standing Order
iban String! The IBAN of the Standing Order payments recipient
recipient String! The name of the Standing Order payments recipient
purpose String The purpose of the Standing Order - 140 max characters
amount Int! The amount of each Standing Order payment in cents
executeAt DateTime! The date at which the first payment will be executed
lastExecutionDate DateTime The date at which the last payment will be executed
e2eId String The end to end ID of the Standing Order
reoccurrence StandingOrderReoccurenceType! The reoccurrence type of the Standing Order payments
nextOccurrence DateTime The date at which the next payment will be executed

Subscription

Field Argument Type Description
newTransaction Transaction!

TimedOrder

Field Argument Type Description
id ID!
executeAt String! The date at which the payment will be executed
status TimedOrderStatus! The status of the Timed Order
purpose String The purpose of the Timed Order - 140 max characters
iban String! The IBAN of the Timed Order recipient
recipient String! The name of the Timed Order recipient
e2eId String The end to end ID of the Timed Order
amount Int! The amount of the Timed Order in cents

Transaction

Field Argument Type Description
id ID!
amount Int! The amount of the transaction in cents
iban String
type TransactionProjectionType!
valutaDate DateTime The date at which the transaction was processed and the amount deducted from the user's account
e2eId String
mandateNumber String
fees [TransactionFee!]!
bookingDate DateTime! The date at which the transaction was booked (created)
directDebitFees [DirectDebitFee!]!
name String
paymentMethod String!
category TransactionCategory
userSelectedBookingDate DateTime When a transaction corresponds to a tax or vat payment, the user may specify at which date it should be considered booked
purpose String
documentNumber String
documentPreviewUrl String
documentDownloadUrl String
documentType DocumentType
foreignCurrency String
originalAmount Int

TransactionFee

Field Argument Type Description
type TransactionFeeType!
status TransactionFeeStatus!
unitAmount Int
usedAt DateTime

TransactionsConnection

Field Argument Type Description
edges [TransactionsConnectionEdge!]!
pageInfo PageInfo!

TransactionsConnectionEdge

Field Argument Type Description
node Transaction!
cursor String!

Transfer

Field Argument Type Description
id String!
recipient String! The name of the transfer recipient
iban String! The IBAN of the transfer recipient
amount Int! The amount of the transfer in cents
status TransferStatus The status of the transfer
executeAt DateTime The date at which the payment will be executed for Timed Orders or Standing Orders
lastExecutionDate DateTime The date at which the last payment will be executed for Standing Orders
purpose String The purpose of the transfer - 140 max characters
e2eId String The end to end ID of the transfer
reoccurrence StandingOrderReoccurenceType The reoccurrence type of the payments for Standing Orders
nextOccurrence DateTime The date at which the next payment will be executed for Standing Orders

TransferSuggestion

Field Argument Type Description
iban String!
name String!

TransfersConnection

Field Argument Type Description
edges [TransfersConnectionEdge!]!
pageInfo PageInfo!

TransfersConnectionEdge

Field Argument Type Description
node Transfer!
cursor String!

User

Field Argument Type Description
email String!
createdAt DateTime!
vatCutoffLine DateTime
taxCutoffLine DateTime
vatPaymentFrequency PaymentFrequency
taxPaymentFrequency PaymentFrequency
taxRate Int
vatRate Int
identificationStatus IdentificationStatus The user's IDNow identification status
identificationLink String The user's IDNow identification status
gender Gender
firstName String
lastName String
birthPlace String
birthDate DateTime
nationality Nationality
street String
postCode String
city String
mobileNumber String
untrustedPhoneNumber String
isUSPerson Boolean Indicates whether the user pays taxes in the US
companyType CompanyType
publicId ID!
language String
country String
businessPurpose String Business description provided by the user
economicSector String The economic sector of the user's business
otherEconomicSector String Business economic sector provided by the user
vatNumber String
referralCode String The user's referral code to use for promotional purposes
clients [Client!]! The list of all OAuth2 clients for the current user
client Client The details of an existing OAuth2 client
id String!
mainAccount Account

WhitelistCardResponse

Field Argument Type Description
id String!
resolution String!
whitelisted_until String!

Inputs

CardFilter

Field Type Description
id String
type CardType

CardLimitInput

Field Type Description
maxAmountCents Float!
maxTransactions Float!

CardLimitsInput

Field Type Description
daily CardLimitInput!
monthly CardLimitInput!

CardSettingsInput

Field Type Description
cardPresentLimits CardLimitsInput
cardNotPresentLimits CardLimitsInput
contactlessEnabled Boolean

CreateClientInput

The available fields to create an OAuth2 client

Field Type Description
name String! The name of the OAuth2 client displayed when users log in
secret String The OAuth2 client secret
redirectUri String The URL to redirect to after authentication
grantTypes [GrantType!]! The grant types (i.e. ways to obtain access tokens) allowed for the client
scopes [ScopeType!]! The scopes the client has access to, limiting access to the corresponding parts of the API

CreateSepaTransferInput

The available fields to create a SEPA Transfer

Field Type Description
recipient String! The name of the SEPA Transfer recipient
iban String! The IBAN of the SEPA Transfer recipient
amount Int! The amount of the SEPA Transfer in cents
purpose String The purpose of the SEPA Transfer - 140 max characters
e2eId String The end to end ID of the SEPA Transfer

CreateStandingOrderInput

The available fields to create a Standing Order

Field Type Description
recipient String! The name of the Standing Order payments recipient
iban String! The IBAN of the Standing Order payments recipient
amount Int! The amount of each Standing Order payment in cents
executeAt DateTime! The date at which the first payment will be executed
lastExecutionDate DateTime The date at which the last payment will be executed
purpose String The purpose of the Standing Order - 140 max characters
e2eId String The end to end ID of the Standing Order
reoccurrence StandingOrderReoccurenceType! The reoccurrence type of the Standing Order payments

CreateTimedOrderInput

The available fields to create a Timed Order

Field Type Description
recipient String! The name of the Timed Order recipient
iban String! The IBAN of the Timed Order recipient
amount Int! The amount of the Timed Order in cents
executeAt DateTime! The date at which the payment will be executed
purpose String The purpose of the Timed Order - 140 max characters
e2eId String The end to end ID of the Timed Order

CreateTransferInput

The available fields to create a transfer

Field Type Description
recipient String! The name of the transfer recipient
iban String! The IBAN of the transfer recipient
amount Int! The amount of the transfer in cents
executeAt DateTime The date at which the payment will be executed for Timed Orders or Standing Orders
lastExecutionDate DateTime The date at which the last payment will be executed for Standing Orders
purpose String The purpose of the transfer - 140 max characters
e2eId String The end to end ID of the transfer
reoccurrence StandingOrderReoccurenceType The reoccurrence type of the payments for Standing Orders

TransfersConnectionFilter

Field Type Description
status TransferStatus

UpdateClientInput

The available fields to update an OAuth2 client

Field Type Description
name String The name of the OAuth2 client displayed when users log in
secret String The OAuth2 client secret
redirectUri String The URL to redirect to after authentication
grantTypes [GrantType!] The grant types (i.e. ways to obtain access tokens) allowed for the client
scopes [ScopeType!] The scopes the client has access to, limiting access to the corresponding parts of the API
id String! The id of the OAuth2 client to update

UpdateTransferInput

The available fields to update a Standing Order

Field Type Description
id String! The ID of the Standing Order to update
type TransferType! The type of transfer to update, currently only Standing Orders are supported
amount Int! The amount of each Standing Order payment in cents
lastExecutionDate DateTime The date at which the last payment will be executed
purpose String The purpose of the Standing Order - 140 max characters, if not specified with the update, it will be set to null
e2eId String The end to end ID of the Standing Order, if not specified with the update, it will be set to null
reoccurrence StandingOrderReoccurenceType The reoccurrence type of the payments for Standing Orders

Enums

BatchTransferStatus

Value Description
AUTHORIZATION_REQUIRED
CONFIRMATION_REQUIRED
ACCEPTED
FAILED
SUCCESSFUL

CardAction

Value Description
CLOSE
BLOCK
UNBLOCK

CardStatus

Value Description
PROCESSING
INACTIVE
ACTIVE
BLOCKED
BLOCKED_BY_SOLARIS
ACTIVATION_BLOCKED_BY_SOLARIS
CLOSED
CLOSED_BY_SOLARIS

CardType

Value Description
VIRTUAL_VISA_BUSINESS_DEBIT
VISA_BUSINESS_DEBIT
MASTERCARD_BUSINESS_DEBIT
VIRTUAL_MASTERCARD_BUSINESS_DEBIT
VIRTUAL_VISA_FREELANCE_DEBIT

CompanyType

Value Description
SELBSTAENDIG
EINZELUNTERNEHMER
FREIBERUFLER
GEWERBETREIBENDER
LIMITED
E_K
PARTGG
GBR
OHG
KG
KGAA
GMBH
GMBH_UND_CO_KG
UG

DocumentType

Value Description
VOUCHER
INVOICE

Gender

Value Description
MALE
FEMALE

GrantType

Value Description
PASSWORD
AUTHORIZATION_CODE
REFRESH_TOKEN
CLIENT_CREDENTIALS

IdentificationStatus

Value Description
PENDING
PENDING_SUCCESSFUL
PENDING_FAILED
SUCCESSFUL
FAILED
EXPIRED
CREATED
ABORTED
CANCELED

InvoiceStatus

Value Description
OPEN
CLOSED
REJECTED
PENDING

Nationality

Value Description
DE
AD
AE
AF
AG
AI
AL
AM
AO
AQ
AR
AS
AT
AU
AW
AX
AZ
BA
BB
BD
BE
BF
BG
BH
BI
BJ
BL
BM
BN
BO
BR
BS
BT
BV
BW
BY
BZ
CA
CC
CD
CF
CG
CH
CI
CK
CL
CM
CN
CO
CR
CU
CV
CW
CX
CY
CZ
DJ
DK
DM
DO
DZ
EC
EE
EG
EH
ER
ES
ET
FI
FJ
FK
FM
FO
FR
GA
GB
GD
GE
GF
GG
GH
GI
GL
GM
GN
GP
GQ
GR
GS
GT
GU
GW
GY
HK
HM
HN
HR
HT
HU
ID
IE
IL
IM
IN
IO
IQ
IR
IS
IT
JE
JM
JO
JP
KE
KG
KH
KI
KM
KN
KP
KR
KW
KY
KZ
LA
LB
LC
LI
LK
LR
LS
LT
LU
LV
LY
MA
MC
MD
ME
MF
MG
MH
MK
ML
MM
MN
MO
MP
MQ
MR
MS
MT
MU
MV
MW
MX
MY
MZ
NA
NC
NE
NF
NG
NI
NL
NO
NP
NR
NU
NZ
OM
PA
PE
PF
PG
PH
PK
PL
PM
PN
PR
PS
PT
PW
PY
QA
RE
RO
RS
RU
RW
SA
SB
SC
SD
SE
SG
SI
SJ
SK
SL
SM
SN
SO
SR
SS
ST
SV
SX
SY
SZ
TC
TD
TF
TG
TH
TJ
TK
TL
TM
TN
TO
TR
TT
TV
TW
TZ
UA
UG
UM
US
UY
UZ
VA
VC
VE
VG
VI
VN
VU
WF
WS
XK
YE
YT
ZA
ZM
ZW

PaymentFrequency

Value Description
MONTHLY
QUARTERLY
YEARLY
NONE

ScopeType

Value Description
OFFLINE
ACCOUNTS
USERS
TRANSACTIONS
TRANSFERS
SUBSCRIPTIONS
STATEMENTS
ADMIN
CLIENTS

SepaTransferStatus

Value Description
CREATED
AUTHORIZED
CONFIRMED
BOOKED

StandingOrderReoccurenceType

Value Description
MONTHLY
QUARTERLY
EVERY_SIX_MONTHS
ANNUALLY

StandingOrderStatus

Value Description
CREATED
ACTIVE
INACTIVE
CANCELED

TimedOrderStatus

Value Description
CREATED
AUTHORIZATION_REQUIRED
CONFIRMATION_REQUIRED
SCHEDULED
EXECUTED
CANCELED
FAILED

TransactionCategory

Value Description
PRIVATE
VAT
VAT_0
VAT_7
VAT_19
TAX_PAYMENT
VAT_PAYMENT
TAX_REFUND
VAT_REFUND

TransactionFeeStatus

Value Description
CREATED
CHARGED
REFUNDED
CANCELLED
REFUND_INITIATED

TransactionFeeType

Value Description
ATM
FOREIGN_TRANSACTION
DIRECT_DEBIT_RETURN
SECOND_REMINDER_EMAIL
CARD_REPLACEMENT

TransactionProjectionType

Value Description
CREDIT_PRESENTMENT
CASH_MANUAL
ATM
CANCEL_MANUAL_LOAD
CARD_USAGE
DIRECT_DEBIT_AUTOMATIC_TOPUP
DIRECT_DEBIT_RETURN
DISPUTE_CLEARING
MANUAL_LOAD
WIRE_TRANSFER_TOPUP
TRANSFER_TO_BANK_ACCOUNT
CANCELLATION_BOOKING
CANCELLATION_DOUBLE_BOOKING
CREDIT_TRANSFER_CANCELLATION
CURRENCY_TRANSACTION_CANCELLATION
DIRECT_DEBIT
FOREIGN_PAYMENT
OTHER
SEPA_CREDIT_TRANSFER_RETURN
SEPA_CREDIT_TRANSFER
SEPA_DIRECT_DEBIT_RETURN
SEPA_DIRECT_DEBIT
TRANSFER
INTERNATIONAL_CREDIT_TRANSFER
CANCELLATION_SEPA_DIRECT_DEBIT_RETURN
REBOOKING
CANCELLATION_DIRECT_DEBIT
CANCELLATION_SEPA_CREDIT_TRANSFER_RETURN
CARD_TRANSACTION

TransferStatus

Value Description
CREATED
AUTHORIZED
CONFIRMED
BOOKED
ACTIVE
INACTIVE
CANCELED
AUTHORIZATION_REQUIRED
CONFIRMATION_REQUIRED
SCHEDULED
EXECUTED
FAILED

TransferType

Value Description
SEPA_TRANSFER
STANDING_ORDER
TIMED_ORDER

Scalars

Boolean

The Boolean scalar type represents true or false.

DateTime

The javascript Date as string. Type represents date and time as the ISO Date string.

Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.