NAV Navbar
  • Introduction
  • How it works
  • API Explorer
  • APIs

    Authentication
  • APIs

    Resources
  • APIs

    AIS
  • APIs

    PIS
  • Errors
  • Introduction

    Welcome

    Welcome to the Fintecture API documentation.

    Fintecture is a licensed and one-stop shop gateway to Open Banking.

    Our APIs allow easy and secure access to bank account data and payment initiation. The account data accessible are account holder's personal information, account balances, transaction history and much more. The available payment methods depend on the banks implementation but typically are domestic transfers, SEPA credit transfer, instant SEPA credit transfer, fast payment scheme, and SWIFT international payments.

    Fintecture APIs enable to connect to both Production and Sandbox environments of banks. Our Sandbox has the particularity of being connected to other banks' Sandbox. This will give you a flavour of what you can expect in production in terms of user experience and data sets.

    JSON:API Specification

    The APIs are based on the JSON:API Specification. We believe that following a shared convention promotes consistency and enhances the productivity of development. Furthermore, JSON:API offers enough flexibility to the API queries to optimize the calls for specific use cases such as mobile apps which can be sensitive to the size of data returned.

    At your service

    We are here to best serve your needs, so please contact us to request a specific feature, to report a bug or just a general enquiry.

    Definitions

    Getting Started

    1. Create an account

    Get started by subscribing to a free developer account. Join today to get access to our sandbox by registering on the developer console. When creating an account, specify your are an Open Banking type of user as this will enable you to access to all our APIs.

    2. Store your credentials

    In the developer console, create an application by providing the necessary fields such as your application name, logo and redirect URL, and take note of your app_id, app_secret and app_private_key. These are your keys to access our APIs.

    3. Authenticate and connect to real banks!

    Using your keys, start by querying our Sandbox about all the banks which you can connect to. Then, request all the test accounts from the bank of your choice and receive the credentials necessary to connect to the banks' Sandbox. To learn more, read the next chapter How it works.

    4. Go into Production

    Once you have successfuly integrated the Sandbox environment, you are now ready to go Live. Start by filling out the Account Activation form in the Console and once you have been activated by our team, just change the following domain names to the API calls: - Sandbox: https://api-sandbox.fintecture.com - Production: https://api.fintecture.com

    Note that in production the signature header is mandatory for all AIS & PIS API calls.

    5. How HTTP payload signature work

    Example of Signature

    GET ais/v1/customer/123/accounts HTTP/1.1
    Accept: application/json
    app_id: [app_id]
    signature: keyId=0354d213-d8d3-462a-8926-4f3f1822c412,algorithm=rsa-sha256,signature=AlOOA0d7na2VSw0EbKRaONhTulToAFK8V/u/2PUffRKbHuwe59npbozcetpDXE1HrxLvrIA/fgAQYk4A==
    

    In production, all our AIS and PIS APIs need to be signed with your app_private_key for obivous security reasons. The HTTP header follows the signing HTTP Messages IETF standard, with the following particularities: - The kid value is your app_id - The only algorithm currently supported is rsa-sha256 - The mandatory parameters are kid, algorithm and signature

    How it works

    This guide explains how to get started and the different levels of Authentication needed depending on what you are trying to achieve. Depending whether you want to know which banks the Fintecture APIs are connected to or to initiate a payment on behalf of a customer, this requires different flows and levels of authentication. This guide is divided into 4 sections:

    1. Resources - How to access Fintecture resources such as knowing which providers ( ASPSP ) are available for Instant SEPA transfers
    2. AIS - How to access a customer's ( PSU ) bank account data such as balances and transaction history
    3. PIS - How to initiate a payment from a customer's bank account
    4. AIS & PIS - How to access a customer's bank account to retreive data and then initiate a payment

    Furthermore, each category of API have a different level of authentication.

    Each documented API will have the authentication level specified. Look for Auth Level to know what to expect.

    01 Get Available Banks

    GET res/v1/providers HTTP/1.1
    Accept: application/json
    app_id: [app_id]
    

    02 Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "data" : [{
            "type": "provider",
            "id": "bbvaes",
            "attributes": {
                "provider": "bbvaes",
                "name": "BBVA",
                "country": "ES",
                "country_full": "Spain",
                "ais": [
                    "Accountholders",
                    "Accounts",
                    "Transactions"
                ],
                "pis": [
                    "SEPA"
                ],
                "authentication_models": [
                        "decoupled",
                        "redirect"
                ]
            }
        }]
    }
    

    1. Resources

    The first endpoints you will want to access are the Fintecture resources. These endpoints will tell you which banks are available and to what services, which countries these banks cover and get detailed information regarding your Fintecture application. As they are not providing any customer data, these resources can be accessed simply by providing your app_id.

    The first step is to list all available banks to let your customer choose which bank to connect to, this can be done with the API request as shown in the example. Notice the app_id parameter in the request header.

    Once you have successfully selected a bank, remember the bank id as you will need it later (a.k.a. provider_id).

    Finally, in the sandbox environment, you will be able to access other banks sandbox environment. To authenticate to these banks sandbox environments, you will need test accounts. To get a sample of test accounts, query the /testaccounts API to receive one or more test accounts for the selected banks.

    2. AIS

    In order to access the AIS endpoints of a bank, you must go through a three-legged authentication flow using the authorization_code grant type. You must first authenticate your Fintecture App to the Fintecture Authentication Server (Step 1 & 2) and then authenticate your customer to the bank (Step 3).

    Step 1: Get code

    The first step is to provide your app_id and a valid redirect_uri to the authentication service as shown in the example. Notice the 3 query parameters:

    03 App Authentication (Step 1)

    GET oauth/token/authorize?app_id=[app_id]&redirect_uri=[redirect_uri]&response_type=code HTTP/1.1
    

    If the authentication service recognizes your app_id and the redirect_uri you have provided when creating the application, it will redirect you to :

    Step 2: Retrieve tokens

    05 App Authentication (Step 2)

    POST oauth/accesstoken HTTP/1.1
    Authorization: Basic [basic_token]
    Accept: application/json
    Content-Type: application/x-www-form-urlencoded
    
    {
      "grant_type": "authorization_code",
      "code": [code],
      "scope": "AIS"
    }
    

    06 Deliver access token

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "token_type": "Bearer",
      "access_token": "eyJhbGciOiJub25lIn0.eyJleHAiOjE1MTQwODA0MjQsI...",
      "expires_in":599,
      "refresh_token": "4n7WgFIi1Pq5texGOza4tMGBZbnIfd5vrQXPs7E7hg3L..."
    }
    

    Once the code received, you will need to create your basic_token to finalize the authentication. To do so, encode the following string using a base64 encoder:

    Notice the following parameters in the body:

    Then, you will need to POST the code back to the server along with your basic_token , authorization_code and grant type in order to receive you access_token which will grant you access to our API services.

    Once you successfully received the access_token, you are now able to access all AIS and PIS endpoints. Note that the access_token is only valid for a certain amount of time specified by the expires_in parameter. Once the access_token is expired, you have the possibility to either go through the authentication process again or use the /refreshtoken endpoint to generate a new access_token. The particularity of using the /refreshtoken endpoint enables you to refresh the token at any given time without having to go through the redirection flow, enabling a flawless user experience. (in the context of authorization_code grant type)

    Step 3: Customer Authentication

    07 Get Bank Authentication URL (Step 3)

    GET provider/[provider_id]/auth?auth_model=redirect HTTP/1.1
    Authorization: Bearer [access_token]
    Accept: application/json
    

    08 Response with Bank Authentication URL

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "provider": "deutde",
        "model": "redirect",
        "url": "https://simulator-api.db.com/gw/oidc/authorize?client_id=abcd&response_type=code&redirect_uri=https://api-sandbox.fintecture.com/provider/deutde/auth/callback&state=169"
    
    }
    

    To complete this three legged authentication flow, the customer must authenticate himself to his bank. By definition, a three-legged authentication is used when an authorized third party (your app via Fintecture) acts on behalf of the resource owner (Customer) to access his data. In order to delegate the access of his data to a third party, the resource owner must first authenticate himself to the resource server (the Bank) and formally give consent to the disclosure of this data within the agreed scope to the resource server.

    In other words, your customer must authenticate to his bank to have access to this date. To do so, you need to choose which authentication model you want to provide (redirect or decoupled). If you choose redirect, you will need to redirect your customer to his bank's authentication page URL given by the Fintecture /[provider_id]/auth API as shown in the example. Note the provider_id which was identified at the very beginning.

    In the redirect model, after that the resource owner (customer) successfully logs into the resource server (his bank), the resource owner will be redirected to the redirect_uri with the resource owner's id defined by customer_id found as query parameter.

    If you've managed this far, well done! You can now access all of the customer AIS data. However, if you're stuck somewhere and can't figure it out, don't hesitate to reach out and contact us via our console.

    11 Request Resource A

    GET ais/v1/customer/32d3ddd3f3r323d3/accounts/ HTTP/1.1
    Authorization: Bearer [access_token]
    Accept: application/json
    

    The customer's authentication is only valid for a certain amount of time and can be revoked by the customer at any given moment. In case the token is expired, Fintecture will do its best to refresh the token on your behalf. However, if the customer has revoked the access or the bank has not provided a refresh_token, you will have to authenticate the customer once more. Both scenarios are shown in the examples on the side.

    12 Response Resource A (if token valid)

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "customer_id": "abdeefreg43t434"
        },
        "data" {
        ...
        }
    }
    

    If the token is expired, simply start the authentication process from step 03 again.

    Below is a summary of each step of the authentication and the flows between each parties:

    3. PIS

    In order to access the PIS endpoints of a bank, you must go through a two legged authentication flow using the client_credentials grant type. You must first authenticate your Fintecture App to the Fintecture Authentication Server (Step 1) and then authenticate your customer to the bank (Step 2).

    Step 1: Retrieve tokens

    14 Get Access Token (Step 2)

    POST oauth/accesstoken HTTP/1.1
    Authorization: Basic [basic_token]
    Accept: application/json
    Content-Type: application/x-www-form-urlencoded
    
    {
      "grant_type":     "client_credentials",
      "app_id":         [app_id],
      "scope":          "PIS"
    }
    

    15 Deliver access token

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "token_type": "Bearer",
      "access_token": "eyJhbGciOiJub25lIn0.eyJleHAiOjE1MTQwODA0MjQsI...",
      "expires_in":599,
      "refresh_token": "4n7WgFIi1Pq5texGOza4tMGBZbnIfd5vrQXPs7E7hg3L..."
    }
    

    To retrieve the access_token, similarly to the AIS token request, you have to build your basic_token the following way:

    Notice the following parameters in the body:

    If successful, you now have the access_token that your Fintecture App will use to issue request against the Fintecture PIS API enpoints that are to be used on behalf of the customer.

    Step 2: Initiate Payment & Customer Authentication

    Th next step is to initiate the payment and then authenticate the customer in order to give his consent for the payment.

    To initiate the payment, you will have to POST a request to the /initiate endpoint using your access_token from Step 1.

    Once the payment is initiated, the debtor ( Customer ) still needs to confirm the payment. The response of the initiate is a URL to either redirect the Customer to his bank ( redirect model ) or a polling URL to retrieve the status of the mobile authentication ( decoupled model ).

    16 Initiate Payment

    POST pis/v1/provider/[provider_id]/initiate HTTP/1.1
    Authorization: Bearer [access_token]
    Accept: application/json
    Content-Type: application/json
    
    { 
        "data": {
            "type" : "SEPA", 
            "attributes" : {
                "debited_account_id" : "0d508bb024c97d3d4f69d9bcfc84d350",
                "amount" : "149.30", 
                "currency": "EUR", 
                "communication" : "March Household expenses",
                "beneficiary" : {
                    "name" : "Bob Smith",
                    "address" : "8 road of somewhere, 80330 Lisboa",
                    "country" : "Lisboa",
                    "iban" : "PT07BARC20325388680799",
                    "swift_bic": "DEUTPTFF"
                },
                "end_to_end_id": "7544248608784409db1a7006c25a39f"
            }
        }
    }
    

    17 Initiation Response

    HTTP/1.1 201 Created
    Accept: application/json
    Content-Type: application/json
    
    {
        "meta": {
            "status": 200,
            "code": "sca_required",
            "title": "Authentication Required",
            "message": "The payment requires customer authentication to complete.",
            "model": "redirect",
            "provider": "bnpafr",
            "customer_id": "xcgf54zji904c3t89zu4rt2c98z042r5cd0",
            "url": "https://sandbox.auth.bnpparibasfortis.com/authorize?response_type=code&client_id=..."
        }
    }
    

    Redirect your customer to the authentication URL provided in the response payload so that he can complete the payment. Whether the payment is successful or not, the customer will be redirected back to your app with a code ( redirect model ) or you can get the payment code directly from polling the URL ( decoupled model ). This code enables you to know what is the next step to complete the payment if an next step is necessary.

    The following codes can be returned: * payment_pending: the bank has accepted the payment but has not yet processed it. * payment_created: the bank has accepted and succesfully created the payment * payment_unsuccessful: the bank has not accepted or could not create the payment * sca_required: the customer is required to authenticate to this bank * debited_account_required: the debtor bank account of the Customer needs to be specified. The bank does not have an interface to let the customer choose himself the payment debtor account.

    For each of the above codes, an URL (redirect) or polling_id (decoupled) will be provided to complete the next step (if required) until payment completion.

    4. AIS & PIS

    The AIS & PIS section are for all use cases which require first the access to the account data and then provide payment services. (ex: use AIS to retreive the accounts on which provide a payment request). As some banks provide a method to use the AIS authentication session for PIS services, which mean avoid a double authentication, we try to leverage on those methods to provide a more seamless experience to the customer, subject to bank implementation.

    To get your access_token to access both AIS & PIS functionalities, use the three-leggeed authentication flow as defined in the AIS section. Note that in Step 2 instead of only specifying AIS as scope, use AIS & PIS:

    05 App Authentication

    POST oauth/accesstoken HTTP/1.1
    Authorization: Basic [basic_token]
    Accept: application/json
    Content-Type: application/x-www-form-urlencoded
    
    {
      "grant_type": "authorization_code",
      "code": [code],
      "scope": "AIS PIS"
    }
    

    Now once you receive you access_token, you can use it when initiating a payment without going through the client_credentials authentication method stated in step 1 of the PIS authentication flow. By doing so, we will do our best to avoid the customer to have to authenticate a second time to his bank. However, in some cases the bank does not enable this functionality, or requires an extra second factor authentication (code: sca_required) to complete the payment.

    API Explorer

    The APIs are split into 4 categories, accessable according to the scopes defined by your app:

    Resources Scope Description
    Authentication - Authentication endpoints required to authenticate to the Fintecture AIS and PIS APIs, and to authenticate the customer to his provider.
    Resources - These endpoints only interact with our servers and are used to support your interaction with the AIS and PIS APIs.
    AIS AIS The AIS endpoints are to access data from customer accounts such as account balances, transactions and account holder information.
    PIS PIS The PIS endpoints are used to initiate payments from a customer's bank account.

    Authentication

    GET /oauth/token/authorize

    The authorize endpoint is used to validate your app_id and redirect_uri as indicated in the console. If successful, the endpoint redirects the user to the redirect_uri and provides a code to be exchanged for the access_token.

    Authentication Level

    -

    HTTP Request

    GET https://api-sandbox.fintecture.com/oauth/token/authorize?response_type=code&app_id=[app_id]&redirect_uri=[redirect_uri]&state=[state]

    Header Parameters

    Parameter Value Usage

    -

    URL Parameters

    Parameter Description Type Usage

    -

    Query Parameters

    Parameter Description Type Usage
    response_type must be set to code string required
    app_id the app id as provided following the creation of an application on the console string required
    redirect_uri must correspond to one of the URLs provided when creating an application on the console URL required
    state an optional state parameter which will be provided back on redirection string optional

    POST /oauth/accesstoken

    The accesstoken API is used to exchange the code received in the /authorize API for an access_token.

    Request

    POST oauth/accesstoken HTTP/1.1
    Authorization: Basic [basic_token]
    Accept: application/json
    Content-Type: application/x-www-form-urlencoded
    
    {
      "grant_type": "authorization_code",
      "code": [code]
    }
    

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "token_type": "Bearer",
      "access_token": "eyJhbGciOiJub25lIn0.eyJleHAiOjE1MTQwODA0MjQsI...",
      "expires_in":599,
      "refresh_token": "4n7WgFIi1Pq5texGOza4tMGBZbnIfd5vrQXPs7E7hg3L..."
    }
    

    Authentication Level

    -

    HTTP Request

    POST https://api-sandbox.fintecture.com/oauth/accesstoken

    Header Parameters

    Parameter Value Usage
    Authorization Basic [basic_token] required
    Accept application/json required
    Content-Type application/x-www-form-urlencoded required

    URL Parameters

    Parameter Description Type Usage

    -

    Query Parameters

    Parameter Description Type Usage

    -

    Body Parameters

    Parameter Description Type Usage
    grant_type must be set to authorization_code string required
    code the code as received from the authorize API string required

    POST /oauth/refreshtoken

    The refresh API is used to generate a new access_token and invalidate the previous one. This is used to avoid going through the whole authentication flow again if granted and refreshing tokens regularly avoids potential leaked tokens to be used.

    Request

    POST oauth/refreshtoken HTTP/1.1
    Authorization: Basic [basic_token]
    Accept: application/json
    Content-Type: application/x-www-form-urlencoded
    
    {
      "grant_type": "refresh_token",
      "refresh_token": [refresh_token]
    }
    

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "token_type": "Bearer",
      "access_token": "eyJhbGciOiJub25lIn0.eyJleHAiOjE1MTQwODA0MjQsI...",
      "expires_in":599,
      "refresh_token": "4n7WgFIi1Pq5texGOza4tMGBZbnIfd5vrQXPs7E7hg3L..."
    }
    

    Authentication Level

    -

    HTTP Request

    POST https://api-sandbox.fintecture.com/oauth/refreshtoken

    Header Parameters

    Parameter Value Usage
    Authorization Basic [basic_token] required
    Accept application/json required
    Content-Type application/x-www-form-urlencoded required

    URL Parameters

    Parameter Description Type Usage

    -

    Query Parameters

    Parameter Description Type Usage

    -

    Body Parameters

    Parameter Description Type Usage
    grant_type must be set to refresh_token string required
    refresh_token the refresh_token as received from the accesstoken API string required

    GET /provider/[provider_id]/auth

    This API is used to authenticate your customer to his Bank. Banks can provide different ways of authentication, we implement both the redirection model and the decoupled model (using the customers smartphone), subject to the whether the bank has implemented them. By calling this API and defining the authentication model, you will receive an API to call which either redirects the customer to his bank or triggers an authentication request on his smartphone's bank app.

    Request

    GET /provider/[provider_id]/auth HTTP/1.1
    Authorization: Bearer [access_token]
    Accept: application/json
    

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "provider": "deutde",
        "model": "redirect",
        "url": "https://simulator-api.db.com/gw/oidc/authorize?client_id=abcd&response_type=code&redirect_uri=https://api-sandbox.fintecture.com/provider/deutde/auth/callback&state=169"
    }
    

    Authentication Level

    authorization_code

    HTTP Request

    GET https://api-sandbox.fintecture.com/provider/[provider_id]/auth

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Accept application/json required

    URL Parameters

    Parameter Description Type Usage
    provider_id the id of the financial institution string optional

    Query Parameters

    Parameter Description Type Usage
    state an optional state parameter which will be provided back on redirection string optional
    redirect_uri must correspond to one of the URLs provided when creating an application on the console URL optional
    model either "redirect" (default) or "decoupled". URL optional

    Body Parameters

    -

    Resources

    GET /providers

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "data" : [{
            "type": "provider",
            "id": "bbvaes",
            "attributes": {
                "provider": "bbvaes",
                "name": "BBVA",
                "country": "ES",
                "country_full": "Spain",
                "ais": [
                    "Accountholders",
                    "Accounts",
                    "Transactions"
                ],
                "pis": [
                    "SEPA"
                ],
                "authentication_models": [
                        "decoupled",
                        "redirect"
                ]
            }
        }
    }
    

    This endpoint retrieves all banks to which you can access account data and initiate payments.

    The services provided by the banks which are currently available through the Fintecture APIs are the following:

    Authentication Level

    app_id

    HTTP Request

    GET https://api-sandbox.fintecture.com/res/v1/providers/[provider_id]

    Header Parameters

    Parameter Value Usage
    app_id the app id as provided following the creation of an application on the console required
    Accept application/json required

    URL Parameters

    Parameter Description Type Usage
    provider_id the id of the financial institution string optional

    Query Parameters

    Parameter Description Type Usage
    filter[country] filter providers by country string optional
    filter[ais] filter providers by AIS services available string optional
    filter[pis] filter providers by PIS services available string optional
    sort[name] sorts the providers by name ASC / DESC optional
    sort[full_name] sorts the providers by full name ASC / DESC optional
    sort[country] sorts the providers by country ASC / DESC optional
    sort[provider] sorts the providers by provider code ASC / DESC optional

    GET /testaccounts

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "data" : [{
            "type": "testaccounts",
            "id": "1",
            "attributes": {
                "provider": "bbvaes",
                "username": "020000B",
                "credentials": {
                    "user" : "020000B",
                    "pass" : "123456"
                }
            }
        },
        {
            "type": "testaccounts",
            "id": "2",
            "attributes": {
                "username": "100000001692",
                "provider": "deutde",
                "credentials": {
                    "pin" : "53345",
                    "branch" : "100",
                    "account" : "124564"
                }
            }
        }
        ]
    }
    

    This endpoint retrieves a set of test accounts by bank to be used in the sandbox environment only. These accounts are actual test accounts in the corresponding bank.

    Authentication Level

    app_id

    HTTP Request

    GET https://api-sandbox.fintecture.com/res/v1/testaccounts

    Header Parameters

    Parameter Value Usage
    app_id the app id as provided following the creation of an application on the console required
    Accept application/json required

    URL Parameters

    null

    Query Parameters

    Parameter Description Type Usage
    filter[provider] filter testaccounts by provider string optional

    AIS

    GET /accounts

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "customer_id": "a8dd747459a761f"
        },
        "data": [
            {
                "id": "b71722204d1a3f5ecd895",
                "type": "accounts",
                "attributes": {
                    "iban": "ES9401824000680201862164",
                    "balance": 1.19,
                    "account_name": "Euro Account",
                    "account_id": "ES0182002000000000000000000042075349XXXXXXXXX",
                    "account_type": "CHECKING",
                    "currency": "EUR",
                    "product": "BBVA CHECKING ACCOUNT"
                },
                "relationships": {
                    "transactions": {
                        "links": {
                            "related": "https://api-sandbox.fintecture.com/ais/v1/customer/a8dd747459a761f/accounts/b71722204d1a3f5ecd895/transactions"
                        }
                    }
                }
            },
            {
                "id": "e8993e4e7027bb600",
                "type": "accounts",
                "attributes": {
                    "iban": "ES3801824000690201882814",
                    "balance": 0.64,
                    "account_id": "ES0182002000000000500000000315017926XXXXXXXXX",
                    "account_type": "CHECKING",
                    "currency": "EUR",
                    "product": "BBVA CHECKING ACCOUNT"
                },
                "relationships": {
                    "transactions": {
                        "links": {
                            "related": "https://api-sandbox.fintecture.com/ais/v1/customer/a8dd747459a761f/accounts/e8993e4e7027bb600/transactions"
                        }
                    }
                }
            }
        ]
    }
    

    This endpoint returns all information regarding the customer's account(s)

    Authentication Level

    authorization_code

    HTTP Request

    GET https://api-sandbox.fintecture.com/ais/v1/customer/[customer_id]/accounts/[accounts_id]

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Accept application/json required

    URL Parameters

    Parameter Description Type Usage
    customer_id the customer id of the requested account holder's personal information string required
    account_id the account id of the requested account information. If no account id is provider, all accounts are returned string optional

    Query Parameters

    Parameter Description Type Usage
    remove_nulls remove all fields with null value boolean optional

    GET /transactions

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "customer_id": "0cf2ebf7e73c8144d51e60aea454add9"
        },
        "data": [
            {
                "id": "1c09eb2ebb41dc72b70ad",
                "type": "transactions",
                "attributes": {
                    "transaction_id": "RB-4567813",
                    "booking_date": "2017-01-31T00:00:00.000+01",
                    "value_date": "2017-01-31T00:00:00.000+01",
                    "amount": 10000,
                    "currency": "CZK",
                    "communication": "Domácí platba - S24/IB,záloha plyn Bohemia Energy",
                    "beneficiary": {
                        "name": "Spokojený Jiří",
                        "account_id": "CZ0827000000002108589434"
                    },
                    "transaction_type": "DBIT",
                    "status": "BOOK"
                }
            },
            {
                "id": "31f48d3ae770630348",
                "type": "transactions",
                "attributes": {
                    "transaction_id": "FP-4156489123",
                    "booking_date": "2017-01-31T00:00:00.000+01",
                    "value_date": "2017-01-31T00:00:00.000+01",
                    "amount": 2328262,
                    "currency": "CZK",
                    "communication": "8201701069595 BIC: GIBACZPXXXX; #71A# SHA ZALOHA DLE SMLOUVY O DODAVKACH,zaloha dle smlouvy o dodavkach c. 45678/2017,VS0250117002/SS0000000000/KS0000SEPA poevod",
                    "beneficiary": {
                        "name": "RENWORTH s.r.o",
                        "account_id": "CZ1308001800640033122856"
                    },
                    "transaction_type": "CRDT",
                    "foreign_currency": "EUR",
                    "foreign_amount": 86200,
                    "status": "BOOK"
                }
            }
        ]
    }
    

    This endpoint lists all transactions on the given account

    Authentication Level

    authorization_code

    HTTP Request

    GET https://api-sandbox.fintecture.com/ais/v1/customer/[customer_id]/accounts/[accounts_id]/transactions

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Accept application/json required

    URL Parameters

    Parameter Value Usage
    customer_id the customer id of the requested beneficial owner personal information required
    account_id the account id of the requested transactions as returned from /accounts required

    Query Parameters

    Parameter Description Type Usage
    remove_nulls remove all fields with null value. Default is false boolean optional
    convert_dates convert all date fields to ISO8601 yyyy-mm-ddThh:mm:ss.fffZ format. Default is false boolean optional
    filter[date_to] filter transactions by booking date. Default is today yyyy-mm-dd optional
    filter[date_from] filter transactions by booking date. Default is 1 year ago yyyy-mm-dd optional

    GET /accountholders

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "customer_id": "98a2358374"
        },
        "data": [
            {
                "id": "1593ca222ce8bf015",
                "type": "accountholders",
                "attributes": {
                    "first_name": "Kim",
                    "middle_name": null,
                    "last_name": "Schmid",
                    "sex": "FEMALE",
                    "birthdate": "1986-08-05",
                    "emails": [
                        {
                            "email_type": "BUSINESS_ADDRESS",
                            "email": "KimSchmid@test.com"
                        }
                    ],
                    "phones": [
                        {
                            "phone_number": "0873448764",
                            "phone_type": "MOBILE_PHONE",
                            "phone_extension": "+49"
                        }
                    ],
                    "identity_documents": [
                        {
                            "id_number": "X324775743",
                            "id_type": "PASSPORT",
                            "id_expiration_date": "2020-05-02",
                            "id_issue_date": "2010-05-02",
                            "id_country": "DEU",
                            "id_issue_city": "Munich"
                        }
                    ],
                    "addresses": [
                        {
                            "address_type": "BUSINESS_ADDRESS",
                            "address1": "Am Sandtorkai",
                            "address2": "4",
                            "zip": "20457",
                            "city": "Hamburg",
                            "country": "DEU"
                        },
                        {
                            "address_type": "PRIVATE_ADDRESS",
                            "address1": "Am Sandtorkai",
                            "address2": "4",
                            "zip": "20457",
                            "city": "Hamburg",
                            "country": "DEU"
                        }
                    ],
                    "accountholder_type": "NATURAL_PERSON",
                    "birth_city": "München",
                    "marital_status": "Married"
                }
            }
        ]
    }
    

    This endpoint retrieves all personal information of the clients such as name, address and contact details for all the beneficiary owners.

    Authentication Level

    authorization_code

    HTTP Request

    GET https://api-sandbox.fintecture.com/ais/v1/customer/[customer_id]/accountholders

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Accept application/json required

    URL Parameters

    Parameter Description Type Usage
    customer_id the customer id of the requested beneficial owner personal information string required

    Query Parameters

    Parameter Description Type Usage
    remove_nulls remove all fields with null value. Default is false boolean optional

    PIS

    POST /initiate

    Request Body

    { 
        "data": {
            "type" : "SEPA", 
            "attributes" : {
                "debited_account_id" : "0d508bb024c97d3d4f69d9bcfc84d350",
                "amount" : "149.30", 
                "currency": "EUR", 
                "communication" : "March Household expenses",
                "beneficiary" : {
                    "name" : "Bob Smith",
                    "address" : "8 road of somewhere, 80330 Lisboa",
                    "country" : "Lisboa",
                    "iban" : "PT07BARC20325388680799",
                    "swift_bic": "DEUTPTFF"
                },
                "end_to_end_id": "7544248608784409db1a7006c25a39f"
            }
        }
    }
    

    Response 201

    HTTP/1.1 201 Created
    Accept: application/json
    Content-Type: application/json
    
    {
        "meta": {
            "status": 201,
            "code": "payment_created",
            "message": "Payment order successfully created.",
            "session_id": "4MDExNTA0MTMwNzAzM2",
            "customer_id": "e233F7he30denje=ef2"
        }
    }
    

    Response 202

    HTTP/1.1 202 Accepted
    Accept: application/json
    Content-Type: application/json
    
    {
        "meta": {
            "status": 202,
            "code": "payment_pending",
            "message": "Payment is pending. Check progress of payment by using the session_id.",
            "session_id": "4MDExNTA0MTMwNzAzM2",
            "customer_id": "e233F7he30denje=ef2"
        }
    }
    

    Response 200

    HTTP/1.1 201 Created
    Accept: application/json
    Content-Type: application/json
    
    {
        "meta": {
            "code": 200,
            "status": "sca_required",
            "session_id": "df920acc85b84ce3b88ecdec24f860a3",
            "customer_id": "6b585b6fd04d71cbbeb728b2ee54f7b2",
            "provider": "ccfrfr",
            "url": "https://developer.hsbc.com/psd2/consent-pages/?scaId=0486e70e-924b-4089-bcd3-dd7a8c3ca31a&spec=stet&version=1.4&scope=PISP&state=df920acc85b84ce3b88ecdec24f860a3",
            "title": "Authentication Required",
            "message": "The payment requires Strong Customer Authentication."
        }
    }
    

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

    POST https://api-sandbox.fintecture.com/pis/v1/provider/[provider_id]/initiate

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Accept application/json required
    Content-Type application/json required

    URL Parameters

    Parameter Description Usage
    provider_id the id of the financial institution required

    Query Parameters

    Parameter Value Usage
    return_uri must correspond to one of the URLs provided when creating an application on the console required
    customer_id optional customer_id param used if going from AIS to PIS and to avoid authenticating twice optional
    scheme Payment scheme type, either SEPA or FPS optional
    state an optional state parameter which will be provided back on redirection string

    Body Parameters

    Parameter Type Description SEPA FPS
    debited_account_id string The account ID from which the account has to be debited from. If the field is not incldued, the bank will prompt PSU a choice of accounts to be used for payment optional optional
    debited_account_type "internal"/"provider" Internal is the account id provided by the /accounts API in the "id" field. Provider is the account id provided by the provider. Default is "provider" optional optional
    amount integer the requested amount to be transferred required required
    currency string the currency of the transferred amount required required
    communication string the transfer communication ( or invoice ref ) shared with the beneficiary optional optional
    beneficiary.name string the name of the beneficiary required required
    beneficiary.iban string the IBAN of the beneficiary required N/a
    beneficiary.account_id string the account id of the beneficiary N/a required
    beneficiary.swift_bic string the swift/bic of the beneficiary's bank required N/a
    counterparty.sort_code string the sort code of the beneficiary's bank N/a required
    beneficiary.address1 string address of the beneficiary optional optional
    beneficiary.address2 string address of the beneficiary optional optional
    beneficiary.country string address of the beneficiary optional optional
    end_to_end_id string A unique ID given by the creator of the transfer. In case a uid is reused for an already-processed transfer, it is not executed. This mechanism can be used to prevent double bookings in case of network failure or a similar event where the transfer status is unknown. optional optional

    Return Values

    The payments API will return a payment status code which defines the next step, including url, to be taken in order to complete the payment initiation cycle. As defined by the PSD2 regulation, payments need to go through a Strong Customer Authentication (SCA) with the exception of certain scenarios such as a low value transfers. In the case of a SCA, the provider will require a Second Factor Authentication (2FA).

    The possible return values are defined and the next step is defined in the following table:

    Status Code Description Next Step
    payment_created 201 The provider has succesfully created the payment -
    payment_pending 202 The provider is processing the payment GET /payments
    payment_unsuccessful 500 The provider rejected the payment View error details
    confirmation_required 200 The provider rejected the payment View error details
    sca_required 200 The provider requires to authenticate to his bank URL or polling_id
    debited_account_required 200 The debtor bank account of the Customer needs to be specified. The bank does not have an interface to let the customer choose himself the payment debtor account. [POST /initiate]

    PUT /confirm

    Request Body

    { 
        "meta": {
            "session_id": "e233F7he30denj"
        }
    }
    

    Response 201

    HTTP/1.1 201 Created
    Accept: application/json
    Content-Type: application/json
    
    {
        "meta": {
            "status": 201,
            "code": "payment_created",
            "message": "Payment order successfully created.",
            "session_id": "4MDExNTA0MTMwNzAzM2",
            "customer_id": "e233F7he30denje=ef2"
        }
    }
    

    Response 202

    HTTP/1.1 202 Accepted
    Accept: application/json
    Content-Type: application/json
    
    {
        "meta": {
            "status": 202,
            "code": "payment_pending",
            "message": "Payment is pending. Check progress of payment by using the session_id.",
            "session_id": "4MDExNTA0MTMwNzAzM2",
            "customer_id": "e233F7he30denje=ef2"
        }
    }
    

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

    PUT https://api-sandbox.fintecture.com/pis/v1/customer/[customer_id]/confirm

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Accept application/json required
    Content-Type application/json required

    URL Parameters

    Parameter Description Usage
    customer_id the customer id of the requested beneficial owner personal information required

    Body Parameters

    Parameter Type Description Usage
    session_id string Payment session ID received after SCA required

    Returned Values

    The payments API will return a payment status which defines the next step to be taken in order to complete the payment initiation cycle. As defined by the PSD2 regulation, payments need to go through a Strong Customer Authentication (SCA) with the exception of certain scenarios such as a low value transfers. In the case of a SCA, the provider will require a Second Factor Authentication (2FA).

    The possible return values are defined and the next step is defined in the following table:

    Status Code Description Next Step
    payment_created 201 The provider has succesfully created the payment -
    payment_pending 202 The provider is processing the payment GET /payments
    payment_unsuccessful 500 The provider rejected the payment View error details
    confirmation_required 200 The provider rejected the payment View error details
    sca_required 200 The provider requires a 2FA URL or polling_id
    debited_account_required 200 The debtor bank account of the Customer needs to be specified. The bank does not have an interface to let the customer choose himself the payment debtor account. [POST /initiate]

    GET /payments

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "status": "payment_created",
            "session_id": "db9aa00d-c41e-49c9-aa6a-623eab9d34e9",
            "customer_id": "747fa582a1c69ed7a3f3020edffbfc25",
            "provider": "bnpafr"
        },
        "data": {
            "id": "dc0ec84957d682306fdbaf5ae9ec1f5e3edba44c65f84c63ee6def94f33e3061",
            "type": "payments",
            "attributes": {
                "amount": "149",
                "currency": "EUR",
                "code": null,
                "reference": "RF1321321",
                "session_id": "db9aa00d-c41e-49c9-aa6a-623eab9d34e9",
                "fees_currency": null,
                "fees_amount": null,
                "operation_type": null,
                "debited_account_id": "FI6593857450293470-EUR",
                "beneficiary": {
                    "name": null,
                    "iban": "GB07BARC20325388680799",
                    "swift_bic": null
                },
                "status": "Paid",
                "created_at": null,
                "communication": "Beer Money"
            }
        }
    }
    

    This endpoint returns the details of all transfers or of a specific transfer

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

    GET https://api-sandbox.fintecture.com/pis/v1/customer/[customer_id]/payments/[session_id]

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Accept application/json required

    URL Parameters

    Parameter Description Usage
    customer_id the customer id of the requested beneficial owner personal information required
    session_id the session ID of the payment following payment acceptance or creation required

    Returned Values

    The payments API will return a payment status which defines the next step to be taken in order to complete the payment initiation cycle. As defined by the PSD2 regulation, payments need to go through a Strong Customer Authentication (SCA) with the exception of certain scenarios such as a low value transfers. In the case of a SCA, the provider will require a Second Factor Authentication (2FA).

    The possible return values are defined and the next step is defined in the following table:

    Status Code Description Next Step
    payment_created 201 The provider has succesfully created the payment -
    payment_pending 202 The provider is processing the payment GET /payments
    payment_unsuccessful 500 The provider rejected the payment View error details
    confirmation_required 200 The provider rejected the payment View error details
    sca_required 200 The provider requires a 2FA URL or polling_id
    debited_account_required 200 The debtor bank account of the Customer needs to be specified. The bank does not have an interface to let the customer choose himself the payment debtor account. [POST /initiate]

    Errors

    Status Title Code Description
    400 - Bad Request Bad Request bad_request Invalid parameters or malformed syntax.
    400 - Bad Request Customer ID invalid customer_unknown Invalid customer_id. Use a valid customer_id or authenticate to a bank to continue.
    400 - Bad Request Account ID invalid account_unknown Invalid account_id. You must specify an account_id as defined by the /accounts API.
    400 - Bad Request Session ID Invalid or Expired session_id_invalid_or_expired The session ID used is either expired or invalid.
    400 - Bad Request Invalid Field invalid_field The value or format of field [field] is incorrect
    400 - Bad Request Missing Field mandatory_field_missing The mandatory field is missing: [field] has not been defined.
    400 - Bad Request Invalid Debited Account ID invalid_debited_account Invalid debited_account_id. The debited_account_type is set to internal, please use an id provider by the accounts API.
    400 - Bad Request Provider Error provider_error The provider has returned an unexpected error. [details]
    401 - Unauthorized Invalid Token invalid_token The token is either invalid or expired.
    401 - Unauthorized Invalid Scopes invalid_scopes Your app does not have the necessary scopes to access this API.
    401 - Unauthorized Invalid Code invalid_code The authorization code is either wrong or expired.
    401 - Unauthorized Invalid App ID invalid_app_id Invalid app redirect URL.
    401 - Unauthorized Invalid Redirect URL invalid_app_url Invalid app_id.
    403 - Forbidden forbidden You do not have the necessary permissions to access this resource.
    404 - Not Found Not Found not_found The requested resource could not be found. The requested resource either does not exist or is temporarly down.
    405 - Method Not Allowed Method Not Allowed method_not_allowed A request method is not supported for the requested resource.
    406 - Not Acceptable Not Acceptable not_accepted The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.
    410 - Gone Gone gone Indicates that the resource requested is no longer available and will not be available again.
    429 - Too Many Requests Too Many Requests too_many_requests The user has sent too many requests in a given amount of time.
    500 - Internal Server Error Internal Error internal_error An internal error has occured. If the error persists, please contact our support.
    500 - Internal Server Error Payment Initiation Unsuccessful payment_unsuccessful The payment initiation was unsuccessful. The user either has not enough funds or has not authorized online transfers.
    500 - Internal Server Error Internal Error payment_unsupported The payment method is unsupported. Contact support to request this method if needed.
    501 - Not Implemented Provider Endpoint Unavailable provider_endpoint_unavailable The provider endpoint is currently unavailable or has not been implemented yet.
    503 - Service Unavailable Provider Unavailable provider_unavailable The provider is currently unavailable. Please try again later.
    {
        "meta": {
            "title": "copyright",
            "details": "copyright© 2018 Fintecture. All rights reserved."
        }
    }
    

    Copyright © 2018 Fintecture. All rights reserved.