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

    Authentication
  • APIs

    Resources
  • APIs

    AIS
  • APIs

    PIS
  • Appendix
  • Errors
  • Introduction

    Welcome to the Fintecture API documentation.

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

    Our API endpoints allow easy and secure access to Account Information Services (AIS) and Payment initiation Services (PIS).




    AIS Connect
    Build the future generation of Account Information Services
    accountsbalancestransactions


    PIS Connect
    Start accepting Payment Initiation Services into your website
    SEPAiSCTFPSSWIFT

    How it works

    Prerequisites

    a. 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 account type as either ECOMMERCE or OPEN BANKING depending on your use case.



    b. 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.



    Environments

    The guides will explain how to integrate the Production environment APIs. To switch to Sandbox, simply change the base URLs:

    Endpoints SANDBOX PRODUCTION
    Oauth https://oauth-sandbox.fintecture.com https://oauth.fintecture.com
    APIs https://api-sandbox.fintecture.com https://api.fintecture.com
    Connect https://connect-sandbox.fintecture.com https://connect.fintecture.com

    SDKs & sample code

    Javascript SDK PIS example

    let connectConfig = {
        amount: '23.50',
        currency: 'EUR',
        communication: 'OrderRef-123',
        state: 'abc'
    };
    
    let tokens = await client.getAccessToken();
    let connect = await client.getPisConnect(tokens.access_token, connectConfig);
    window.href.location = connect.url;
    

    This guide provides a complete overview on how to integrate Account Information Services (AIS) and Payment Information Services (PIS) using the Fintecture Connect webview into your platform without an SDK.

    It is recommended to use an SDK if available, as our community and ourselves continually update them with any new features and changes. The SDKs are available in our Github.

    For any examples of real implementations of our APIs and of the Connect integrator, you can review them into from our Github.

    AIS Connect

    The complete connection flow using the Fintecture Connect webview, to access to AIS resources, has been simplified into the following 3 steps and illustrated using the payment flow below:

    1. Connect URL: First, request the AIS Connect URL API to which you will redirect the user (i.e. PSU)
    2. Access Token: Then, exchange the code received after redirection for an access_token
    3. Request Resource: Finally, request the relevant AIS endpoints using the customer_id and the access_token



    The following section is split based on the 3 steps presented above.


    Step 1: Connect URL

    Step 1: Request

    GET /ais/v1/connect?redirect_uri=[redirect_uri]&state=[state] HTTP/1.1
    Accept: application/json
    app_id: [app_id]
    signature: [signature]
    x-date: [date]
    x-request-id: [request_id]
    x-psu_type: [psu_type]
    x-country: [country]
    

    Step 1: Response

    HTTP/1.1 200 OK
    
    {
        "meta": {
            "url": "https://connect.fintecture.com/ais?config=eyJhcHBfaWQiOiI1MWM3MjViNi=="
        }
    }
    

    The first step is to request the AIS Connect API to receive the URL to redirect the PSU towards Fintecture Connect. Simply GET the illustrated request including all the necessary headers and query string parameters as defined in the following table



    parameter type sandbox production description
    scope query optional optional By default: accounts, balances, transactions
    redirect_uri query required required A redirect URL to which the PSU will be redirected to after authorization. Must be one which has been defined in the console
    state query required required The state parameter returned on callback
    app_id header required required The app_id of your application
    signature header optional required The HTTP Signature build using headers "x-date x-request-id", according to the draft cavage http signature 10
    x-date header optional required A RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT)
    x-request-id header optional required a UUIDv4 ID. Must be different for each request (e.g. 2219654c-981a-4506-9686-5a3fa341c0a7)
    x-psu_type header optional optional Defines what type of banks to be provided in the webview. Either retail, corporate or all. Default: retail
    x-country header optional optional Defines the country of banks to be provided in the webview. Default: fr language optional Display Language of Connect. Default: fr ( ISO 3166 )
    x-language header optional optional The display language of Connect. Default is the browser language ( ISO 639-1 )
    x-provider header optional optional Filter Connect to only display the provider




    The response of a successful request is the Connect URL.

    After redirecting the PSU to the Connect URL, they will be able to select their bank and authenticate to it. Following the authentication, they will be redirected back to your redirect_uri with the following parameters as query string:


    Step 2: Access Token

    Step 2: 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],
      "scope": "AIS"
    }
    

    Step 2: Response

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

    The second step is to authenticate the customer with the Fintecture API Gateway and this is done by exchanging the received code for an access_token using the /accesstoken API, as illustrated.

    To use the API, you must first created a basic token. To do so, encode the following string using a base64 encoder:



    parameter type sandbox production description
    basic_token header required required Basic token built by base64 encoding the concatenation of app_id, ":" and your app_secret
    grant_type body required required Must be 'authorization_code'
    code body required required The code received in the previous step
    scope body required required Must be 'AIS'



    Step 3: Request Resource

    At this point, you should have a customer_id and an access_token. hese values will enable you to access the accounts endpoints /accounts and /transactions.


    3.1 Accounts

    Step 3.1: Request

    GET /ais/v1/customer/[customer_id]/accounts HTTP/1.1
    Authorization: Bearer [access_token]
    Signature: [signature]
    Date: [date]
    X-Request-Id: [x-request-id]
    Accept: application/json
    Content-Type: application/json
    

    Step 3.1: 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",
                    "balance_available": "110.19",
                    "account_name": "Euro Account",
                    "account_id": "ES0182002000000000000000000042075349XXXXXXXXX",
                    "account_type": "CHECKING",
                    "currency": "EUR",
                    "product": "BBVA CHECKING ACCOUNT"
                },
                "relationships": {
                    "transactions": {
                        "links": {
                            "related": "https://api.fintecture.com/ais/v1/customer/a8dd747459a761f/accounts/b71722204d1a3f5ecd895/transactions"
                        }
                    }
                }
            },
            {
                "id": "e8993e4e7027bb600",
                "type": "accounts",
                "attributes": {
                    "iban": "ES3801824000690201882814",
                    "balance": "0.64",
                    "balance_available": "0.64",
                    "account_id": "ES0182002000000000500000000315017926XXXXXXXXX",
                    "account_type": "CHECKING",
                    "currency": "EUR",
                    "product": "BBVA CHECKING ACCOUNT"
                },
                "relationships": {
                    "transactions": {
                        "links": {
                            "related": "https://api.fintecture.com/ais/v1/customer/a8dd747459a761f/accounts/e8993e4e7027bb600/transactions"
                        }
                    }
                }
            }
        ]
    }
    

    The /accounts endpoints enables you to access to the PSU payment accounts identifiers, currency, account type, booked balance and available balance if available.



    parameter type sandbox production description
    customer_id url required required the customer_id received in Step 1
    access_token header required required the access token received in Step 2
    signature header optional required the HTTP signature calculated as describe in the Appendix
    date header optional required An RFC 2822 formatted date e.g. Wed, 26 Feb 2020 17:29:51 GMT
    x-request-id header optional required An UUID v4 formatted unique value.



    3.2 Transactions

    The /transactions endpoint enables you to access to the PSUs historical transactions.



    parameter type sandbox production description
    customer_id url required required the customer_id received in Step 1
    account_id url required required the account->id received in 3.1 Accounts
    access_token header required required the access token received in Step 2
    signature header optional required the HTTP signature calculated as describe in Appendix
    date header optional required An RFC 2822 formatted date e.g. Wed, 26 Feb 2020 17:29:51 GMT
    x-request-id header optional required An UUID v4 formatted unique value.



    PIS Connect

    The complete payment flow using the Fintecture Connect webview has been simplified into the following steps and illustrated using the payment flow below:

    1. Access Token: The first step is to request a PIS access token
    2. Prepare Payment: The next step is to prepare the payment by sending the payment payload to the API Gateway in exchange of a session_id
    3. Connect URL: The following step is to build the Connect URL to which you will redirect the payer (i.e. PSU)
    4. Validate Payment: The last step is to verify the payment on callback such that the payment status and order ID matches
    5. Listen to Webhook: (OPTIONAL) This optional step is to listen to a webhook to intercept payments status change events



    The following section is split based on the steps presented above.


    Step 1: Access Token

    Step 1: Request

    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"
    }
    

    Step 1: Response

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

    The first step is to authenticate your application with the Fintecture API Gateway and this is done using the /accesstoken API, as illustrated.

    To use the API, you must first created a basic token. To do so, encode the following string using a base64 encoder:



    parameter type sandbox production description
    basic_token header required required Basic token built by base64 encoding the concatenation of app_id, ":" and your app_secret
    grant_type body required required Must be 'client_credentials'
    app_id body required required The app_id of your application
    scope body required required Must be 'PIS'



    Step 2: Prepare Payment

    Step 2: Request

    POST pis/v1/prepare HTTP/1.1
    Authorization: Bearer [access_token]
    Signature: [signature]
    Digest: [digest]
    X-Date: [x-date]
    X-Request-Id: [x-request-id]
    Accept: application/json
    Content-Type: application/json
    
    { 
        "meta": { 
            "psu_name": "Bob Smith",
            "psu_email": "bob.smith@email.com", 
            "psu_ip": "91.67.42.23", 
            "psu_phone": "003344685897", 
            "psu_address": { 
                "number": "23", 
                "street": "Rue de la Tour", 
                "complement": "Appartment 2B", 
                "zip": "17001", 
                "city": "Paris", 
                "country": "FR" 
                }, 
            "psu_form": "SARL", 
            "psu_incorporation": "8622498846565",
        },
        "data": { 
                "type" : "SEPA", 
                "attributes" : { 
                    "amount" : "149.30", 
                    "currency": "EUR", 
                    "communication" : "ORDER-REF 1232", 
                    "beneficiary" : { 
                        "name" : "John Snow Technologies", 
                        "form": "SARL", 
                        "incorporation": "8442247484848", 
                        "street" : "road of somewhere", 
                        "number" : "2", 
                        "city" : "Berlin", 
                        "zip" : "93160", 
                        "country" : "Germany", 
                        "iban" : "DE07BARC20325388680799", 
                        "swift_bic": "DEUTPTFF", 
                        "bank_name": "Deutche Bank", 
                    } 
                } 
            } 
        }
    }
    

    The second step is to prepare the payment in order to receive a session_id. The session_id enables you to follow the status of the payment throughout it's lifecycle.



    parameter type sandbox production description
    access_token header required required the access token received in Step 2
    signature header optional required the HTTP signature calculated as describe in Appendix
    digest header optional required the SHA-256 digest of the body as describe in Appendix
    date header optional required An RFC 2822 formatted date e.g. Wed, 26 Feb 2020 17:29:51 GMT
    x-request-id header optional required An UUID v4 formatted unique value.


    The /prepare payload contains all the necessary information to initiate a payment. The application you have configured in the console can have a predefined beneficiary associated to it. If that is the case, you won't be able to override a beneficiary during payment initiation as you will receive an error.



    Parameter Description Use Case Usage
    type the payment scheme to use. Default: PIS (automatic selection) ALL required
    amount the requested amount to be transferred ALL required
    currency the currency of the transferred amount (EUR, GBP) ALL required<>
    communication description of the transaction, as seen on a bank statement ALL required
    beneficiary.name the name of the beneficiary) OPEN BANKNG required
    beneficiary.iban the IBAN of the beneficiary OPEN BANKNG required
    beneficiary.account_id the IBAN of the beneficiary OPEN BANKNG required
    beneficiary.swift_bic the swift/bic of the beneficiary's bank OPEN BANKNG required
    beneficiary.sort_code the sort code of the beneficiary's bank OPEN BANKNG required
    beneficiary.bank_name the full name of the beneficiary's bank OPEN BANKNG optional
    beneficiary.street the street name from the beneficiary's address OPEN BANKNG required
    beneficiary.number the street number from the beneficiary's address OPEN BANKNG optional
    beneficiary.complement the street name from the beneficiary's address OPEN BANKNG optional
    beneficiary.city the city from the beneficiary's address OPEN BANKNG required
    beneficiary.zip the zip codee from the beneficiary's address OPEN BANKNG required
    beneficiary.country the country from the beneficiary's address OPEN BANKNG required
    beneficiary.form The incorporation form of the beneficiary (only legal company ex: SARL) OPEN BANKNG required*
    beneficiary.incorporation The incorporation number of the PSU OPEN BANKNG required*
    end_to_end_id A unique ID given by the creator of the payment and send to the bank. This field is also used to avoid double bookings ALL recommended
    psu_name The full name of the PSU ALL required
    psu_email The email of the PSU ALL required
    psu_phone The phone number of the PSU ALL optional
    psu_ip The IP Address of the PSU ALL optional
    psu_form The incorporation number of the PSU ALL required*
    psu_incorporation The IP Address of the PSU ALL required*
    psu_address.street The street of the PSU ALL required
    psu_address.number The street number of the PSU ALL optional
    psu_address.complement The address complement of the PSU ALL optional
    psu_address.city The city of the PSU ALL required
    psu_address.zip The ZIP code of the PSU ALL required
    psu_address.country The 2 letter country of the PSU ALL required

    * required if the beneficiary is a legal person


    Step 3: Connect URL

    Step 3: Request

    POST /pis/v1/connect?redirect_uri=[redirect_uri]&state=[state] HTTP/1.1
    Authorization: Bearer [access_token]
    Signature: [signature]
    Digest: [digest]
    x-date: [date]
    x-request-id: [request_id]
    x-psu_type: [psu_type]
    x-country: [country]
    Accept: application/json
    Content-Type: application/json
    

    Step 3: Response

    HTTP/1.1 200 OK
    
    {
        "meta": {
            "session_id": "fc8583ae532346d1b7c5ed1c2853d497",
            "url": "https://connect.fintecture.com/pis?config=eyJhcHBfaWQiOiI1MWM3MjViNi=="
        }
    }
    

    The third step is to request the PIS Connect API to receive the URL to redirect the PSU towards Fintecture Connect. Simply POST the illustrated request including all the necessary headers, body and query string as defined in the following table



    parameter type sandbox production description
    redirect_uri query optional optional A redirect URL to which the PSU will be redirected after authorization. Must be one of the redirect URIs which have been defined in the console. By default the first redirect_uri defined is chosen.
    state query required required The state parameter returned on callback
    access_token header required required The access_token received in Step 1
    signature header optional required The HTTP Signature header is build according to the draft cavage http signature 10
    digest header optional required The sha-256 digest of the body build according to the draft cavage http signature 10
    x-date header optional required A RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT)
    x-request-id header optional required a UUIDv4 ID. Must be different for each request (e.g. 2219654c-981a-4506-9686-5a3fa341c0a7)
    x-psu_type header optional optional Defines what type of banks to be provided in the webview. Either retail or corporate. Default: retail
    x-country header optional optional Defines the country of banks to be provided in the webview. Default: fr
    x-language header optional optional The display language of Connect. Default is the browser language
    x-provider header optional optional Filter Connect to only display the provider


    The values provided in the body must match the ones provided in Step 2 /prepare or else an error will be returned.


    body type sandbox production description
    meta.session_id body required required The session_id received from the /prepare API
    data.attributes.amount body required required The amount of the payment
    data.attributes.currency body required required The currency of the payment
    data.attributes.communication body required required The communication field of the payment
    data.attributes.execution_date body optional optional Only necessary if the payment has a future execution date
    data.attributes.beneficiary.name body optional optional Only necessary if the payment has a beneficiary explicitely defined



    The response of a successful request is the Connect URL and the corresponding payment session_id which will enable you to follow the transaction using the /payments/[session_id] API

    After redirecting the PSU to the Connect URL, they will be able to select their bank and initiate the payment from their bank's portal. Following the payment initiation, they will be redirected back to your redirect_uri with the following query string parameters:


    Step 4: Validate Payment

    Step 4: Request

    GET pis/v1/payments/[session_id] HTTP/1.1
    Accept: application/json
    Authorization: Bearer [access_token]
    Signature: [signature]
    Digest: [digest]
    X-Date: [x-date]
    X-Request-Id: [x-request-id]
    

    Step 4: Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
     { 
        "meta": {
            "session_id": "44f00841780445d4981be9ea2f8aafae", 
            "status": "payment_created",
            "customer_id": "3621eacaccd04fa772638dec70da323c" 
        },
        "data": { 
            "type": "PIS", 
            "attributes": { 
                "amount": "42.05", 
                "currency": "EUR", 
                "communication": "123", 
                "beneficiary": { 
                    "name": "Legal Entity Name", 
                    "street": "Some street", 
                    "number": "23", 
                    "zip": "12011", 
                    "city": "Paris", 
                    "country": "FR", 
                    "iban": "FR1420041010050500013M02606", 
                    "swift_bic": "BANKFRPPXXX" 
                }, 
                "end_to_end_id": "44f00841780445d4981be9ea2f8aafae"
            }
        }
    }
    

    The payment validation is verifying that the payment has either been successful or not.

    Start by considering the returned parameters from the callback. The redirection url is composed of the following parameters:

    Using the callback query string parameter session_id, you can call the API at the /payments/[session_id] endpoint. The returned values from the /payments/[session_id] endpoint are the actual payment values you can consider.

    On your end, retreive the order reference using the callback state query parameter which you stored locally. Reconcile the order reference and only then can you validate the payment and consider the payment status from the returned payload.




    parameter type sandbox production description
    session_id url required required the payment session ID.
    access_token header required required The access_token received in Step 1 (or a newly generated one)
    signature header optional required The HTTP Signature header is build according to the draft cavage http signature 10
    x-date header optional required A RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT)
    x-request-id header optional required a UUIDv4 ID. Must be different for each request (e.g. 2219654c-981a-4506-9686-5a3fa341c0a7)




    Step 5: Webhooks

    Step 5: Webhook

    POST /webhook HTTP/1.1
    Host: mywebsite.com
    Signature: keyId="2dfdcf57-5b2f-4309-846f-913d0b2802cf",algorithm="rsa-sha256",headers="(request-target) date digest x-request-id",signature="h0V0SUbjRhLEP/MiYo0Mgs1N17EuCEmKyQrDjxysc7iSiFXTjvY6qVEoaiRkzB8ZI0J39gGwOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fSTQ2/BSZWx04CjbPv/XUVusnkKVr3W6p+Vn073hAuJn1nKCvDOyl+QnDtstkzT+UacVzDA9L9nyPbbaPQHJobaZuG8TjhnI+Y0PZxneke6OU6fcdPT0uwkEamDOOExcMryHIX1iH5iiPMvLoVA8acqvvMSDYar0rlEQ2J1M4dcowWT8FxLo6C8uqvJIaBYm7Ze0RNJOwY0UBImCVDIuQLJuBjPwjQT5GjTQlg==
    Digest: SHA-256=wOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fS
    Date: Mon, 08 Jun 2020 23:11:23 GMT
    X-Request-ID: 88c414df-6895-48db-8ef3-1fd1ce4272c6
    Content-Type: application/x-www-form-urlencoded
    
    session_id=b2bca2bcd3b64a32a7da0766df59a7d2&satus=payment_created&customer_id=1ef74051a77673de120820fb370dc382&provider=provider&state=thisisastate
    

    Webhooks enables you to be notified of an event such as a payment status change.

    In the context of a payment model based on redirection, it is important to use a redundant payment notification channel in case the redirection fails. Some implementations uses webhooks as the main payment notification channel and the redirection simply displays the resulting payment result.

    You can add webhooks to your application using the Console. he configuration of a webhook requires the following three parameters:

    The webhook is a x-www-form-urlencoded POST request which is signed using your public key. Verify the signature using your private key, and only then process the order based on the result of the payment.



    API Explorer

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

    Resources Scope Description
    Authentication - Authentication API endpoints are used to authenticate your Apps to Fintecture.
    Resources - The Resource API 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 used 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

    POST /oauth/accesstoken

    PRODUCTION SANDBOX

    The accesstoken API endpoint is used to exchange the code received in the /authorize endpoint 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],
      "scope": "AIS"
    }
    

    Response for AIS

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

    Response for PIS

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

    The access token endpoint enables the TPP to authenticate to the Fintecture Authentication Server. There are 2 types of grant_types, authorization_code and client_credentials, depending if you require access to the AIS or PIS resources respectively.

    Compliance Level

    All

    Authentication Level

    -

    HTTP Request

    POST https://oauth.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 is either authorization_code or client_credentials string required
    code the code as received from the authorize API string required for AIS
    app_id your app_id from your application string required for PIS
    scope is either AIS, PIS, or AIS PIS string required

    POST /oauth/refreshtoken

    PRODUCTION SANDBOX

    The refresh API is used to generate a new access_token and invalidate the previous one. This allows clients to continue to have a valid access token without further interaction with the user.

    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..."
    }
    

    Compliance Level

    All

    Authentication Level

    -

    HTTP Request

    POST https://oauth.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

    Resources

    GET /providers

    PRODUCTION SANDBOX

    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 the banks to which you can access account data and initiate payments.

    The services provided by the banks are detailed in the ‘ais’ and ‘pis’ attributes, and can be:

    • AIS: Accountholders, Accounts, Transactions • PIS: SEPA, iSCT, FPS, PLN, INT

    Compliance Level

    All

    Authentication Level

    app_id

    HTTP Request

    GET https://api.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
    filter[psu_type] filter providers based on supported PSU types retail / corporate optional
    filter[auth_model] filter providers based on authentication models redirect / decoupled 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_id] sorts the providers by provider code ASC / DESC optional

    GET /applications

    PRODUCTION SANDBOX

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "data" : {
            "type": "app",
            "id": "1",
            "attributes": {
                "name": "Fintecture TEST",
                "description": "Secure Bank Connections",
                "environment": "sandbox",
                "scope": {
                    "ais": true,
                    "pis": false
                },
                "logo": "data:image/png;base64,iVBORw0KGgoAAA..."
                "created_at": "2018-04-23T10:26:00.996Z"
            }
        }
    }
    

    This endpoint retrieves all information related to your application.

    Compliance Level

    All

    Authentication Level

    app_id

    HTTP Request

    GET https://api.fintecture.com/res/v1/applications

    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

    null

    GET /testaccounts

    SANDBOX

    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 sandbox.

    Compliance Level

    All

    Authentication Level

    app_id

    HTTP Request

    GET https://api.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_id] filter testaccounts by provider string optional

    AIS

    GET /connect

    PRODUCTION SANDBOX

    Request Body

    {
            "meta": {
                "session_id": "c4c889194f28455a9f47811ef54ef9e2"
            },
            "data": {
                "attributes": {
                    "amount": "152",
                    "currency": "EUR",
                    "beneficiary": {
                        "name": "Legal Entity Name"
                    }
                }
            }
        }
    

    Response 201

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "url": "https://connect.fintecture.com/ais?config=eyJhcHkifQ=="
        }
    }
    

    Compliance Level

    All

    Authentication Level

    app_id

    HTTP Request

    GET https://api.fintecture.com/ais/v1/connect

    Header Parameters

    Parameter Value Usage
    app_id [app_id] required
    Accept application/json required
    Signature see APPENDIX - signed headers: "x-date x-request-id" required
    x-date [date] required
    x-request-id uuid v4 required
    x-psu-type [retail, corporate, all] optional
    x-country 2 letter country - ex: fr optional
    x-language 2 letter language code - ex: fr optional
    x-provider [provider_id] optional

    URL Parameters

    Parameter Description Usage
    redirect_uri must correspond to one of the URLs provided when creating an application on the console required
    state an optional state parameter which will be provided back on redirection required
    scope the scopes used for consent - default: accounts,balances,transactions optional

    Body Parameters

    Parameter Type Description Usage

    -

    Returned Values

    Parameter Description
    meta.url the connect URL

    GET /authorize

    PRODUCTION SANDBOX

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

    Request

    GET /provider/[provider_id]/authorize 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.fintecture.com/provider/deutde/auth/callback&state=169"
    }
    

    Compliance Level

    Licensed

    Authentication Level

    app_id or authorization_code

    HTTP Request

    GET https://api.fintecture.com/ais/v1/provider/[provider_id]/authorize

    Header Parameters

    Parameter Value Redirect Decoupled
    app_id [app_id] conditional conditional
    Authorization Bearer [access_token] conditional conditional
    Signature see APPENDIX - signed headers: "date x-request-id" required
    Date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 required
    Accept application/json required required
    x-psu-id The PSU's ID at the provider optional required
    x-psu-ip-address the PSU's IP Address (ex: 92.168.0.12) optional required

    URL Parameters

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

    Query Parameters

    Parameter Description Type Redirect Decoupled
    response_type must be set to code and is only required if app_id has been set in headers URL conditional conditional
    redirect_uri must correspond to one of the URLs provided when creating an application on the console URL required optional
    state an optional state parameter which will be provided back on redirection string optional optional
    model either "redirect" (default) or "decoupled". URL optional required

    Body Parameters

    -

    GET /authorize/decoupled

    PRODUCTION SANDBOX

    This API endpoint is used to poll the authentication status within the decoupled model. Once the decoupled authentication flow is initiated, the status is "PENDING". Once the PSU has successfully authenticated, the status becomes "COMPLETED". If the authentication times out, is cancelled or failed, the status becomes "FAILED".

    Request

    GET /provider/[provider_id]/authorize/decoupled/[polling_id] HTTP/1.1
    Authorization: Bearer [access_token]
    Accept: application/json
    

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "provider": "handse",
        "status": "COMPLETED",
        "customer_id": "ec10fadfbadccb4901b522ab7286a549",
        "code": "443834fc92fb358042520c46d9ad4f1d"
    }
    

    Compliance Level

    Licensed

    Authentication Level

    app_id or authorization_code

    HTTP Request

    GET https://api.fintecture.com/ais/v1/provider/[provider_id]/authorize/decoupled/[polling_id]

    Header Parameters

    Parameter Value Usage
    app_id [app_id] conditional
    Authorization Bearer [access_token] conditional
    Signature see APPENDIX - signed headers: "date x-request-id" required
    Date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 required
    Accept application/json required

    URL Parameters

    Parameter Description Type Usage
    provider_id the id of the financial institution string required
    polling_id the polling_id of the decoupled flow string required

    Query Parameters

    -

    Body Parameters

    -

    GET /accounts

    PRODUCTION SANDBOX

    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.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.fintecture.com/ais/v1/customer/a8dd747459a761f/accounts/e8993e4e7027bb600/transactions"
                        }
                    }
                }
            }
        ]
    }
    

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

    Compliance Level

    All

    Authentication Level

    authorization_code

    HTTP Request

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

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Signature see APPENDIX - signed headers: "date x-request-id" required
    Date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 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 (default true) boolean optional
    withBalances returns the accounts balances (default true) boolean optional

    GET /transactions

    PRODUCTION SANDBOX

    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",
                    "counterparty": {
                        "name": "Spokojený Jiří",
                        "account_id": "CZ0827000000002108589434"
                    },
                    "transaction_type": "DBIT",
                    "status": "BOOK",
                    "debit_credit": "DEBIT"
                }
            },
            {
                "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",
                    "counterparty": {
                        "name": "RENWORTH s.r.o",
                        "account_id": "CZ1308001800640033122856"
                    },
                    "transaction_type": "CRDT",
                    "foreign_currency": "EUR",
                    "foreign_amount": 86200,
                    "status": "BOOK",
                    "debit_credit": "DEBIT"
                }
            }
        ]
    }
    

    This endpoint lists all transactions on the given account

    Compliance Level

    All

    Authentication Level

    authorization_code

    HTTP Request

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

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Signature see APPENDIX - signed headers: "date x-request-id" required
    Date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 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. yyyy-mm-dd optional
    filter[date_from] filter transactions by booking date. yyyy-mm-dd optional
    filter[date_from]=max returns maximum amount of transactions permitted by the bank, on a best effort basis max optional

    GET /accountholders

    SANDBOX

    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.

    Compliance Level

    All

    Authentication Level

    authorization_code

    HTTP Request

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

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Signature see APPENDIX - signed headers: "date x-request-id" required
    Date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 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

    DELETE /customer

    PRODUCTION SANDBOX

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "status": 200,
            "code": "customer_deleted",
            "message": "Customer successfully deleted.",
            "customer_id": "46d1b5c2ebdcec4a4d30bb9e63315171"
        }
    }
    

    This endpoint deletes all active access tokens and all related PSU data

    Compliance Level

    All

    Authentication Level

    app_id

    HTTP Request

    DELETE https://api.fintecture.com/ais/v1/customer/[customer_id]

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Signature see APPENDIX - signed headers: "date x-request-id" required
    Date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 required
    Accept application/json required

    URL Parameters

    Parameter Description Type Usage
    customer_id the customer id returned from a previous AIS authentication string required

    Query Parameters

    Parameter Description Type Usage

    -

    PIS

    POST /connect

    PRODUCTION SANDBOX

    Request Body

    {
            "meta": {
                "session_id": "c4c889194f28455a9f47811ef54ef9e2"
            },
            "data": {
                "attributes": {
                    "amount": "152",
                    "currency": "EUR",
                    "beneficiary": {
                        "name": "Legal Entity Name"
                    }
                }
            }
        }
    

    Response 201

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "session_id": "c4c889194f28455a9f47811ef54ef9e2",
            "url": "https://connect.fintecture.com/pis?config=eyJhcHkifQ=="
        }
    }
    

    Compliance Level

    All

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

    POST https://api.fintecture.com/pis/v1/connect

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Accept application/json required
    Content-Type application/json required
    Signature see APPENDIX - signed headers: "digest x-date x-request-id" required
    Digest see APPENDIX - sha-256 base64 encoded digest required
    x-date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 required
    x-psu-type [retail, corporate, all] optional
    x-country 2 letter country - ex: fr optional
    x-language 2 letter language code - ex: fr optional
    x-provider [provider_id] optional

    URL Parameters

    Parameter Description Usage
    redirect_uri must correspond to one of the URLs provided when creating an application on the console - default: the first one defined in the console optional
    state an optional state parameter which will be provided back on redirection required

    Body Parameters

    Parameter Type Description Usage
    meta.session_id string The session_id received from the /prepare API endpoint required
    data.attributes.amount string The amount of the payment required
    data.attributes.currency string The currency of the payment required
    data.attributes.communication string The communication field of the payment required
    data.attributes.execution_date string Only necessary if the payment has a future execution date optional
    data.attributes.beneficiary.name string Only necessary if the payment has a beneficiary explicitely defined optional

    Returned Values

    Parameter Description
    meta.session_id The session_id of the payment
    meta.url the connect URL

    POST /initiate

    PRODUCTION SANDBOX

    Request Body (Use case: ECOMMERCE)

    POST pis/v1/provider/[provider_id]/initiate HTTP/1.1
    Authorization: Bearer [access_token]
    Accept: application/json
    Content-Type: application/json
    
    { 
        "meta": {
            "psu_name" : "Bob McCheese", 
            "psu_email" : "bob@mccheese.com",
            "psu_phone" : "00339743593535",
            "psu_ip": "159.358.578.99",
            "psu_address": {
                "street": "route de la france",
                "number": "33",
                "complement": "2nd floor",
                "zip": "12001",
                "city": "Paris",
                "country": "FR"
            }
        },
        "data": {
            "type" : "SEPA", 
            "attributes" : {
                "amount" : "149.30", 
                "currency": "EUR", 
                "communication" : "March Household expenses"
            }
        }
    }
    

    Response 200

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "status": "sca_required",
            "message": "The payment requires customer authentication to complete.",
            "model": "redirect",
            "provider": "deutde",
            "customer_id": "xcgf54zji904c3t89zu4rt2c98z042r5cd0",
            "session_id": "e07335fdeb073e0ebab13ba0bd71ad3c",
            "url": "https://sandbox.auth.bnpparibasfortis.com/authorize?response_type=code&client_id=..."
        },
        "data": {
            "type" : "SEPA", 
            "attributes" : {
                "amount" : "149.30", 
                "currency": "EUR", 
                "communication" : "March Household expenses",
                "beneficiary" : {
                    "name" : "Bob Smith",
                    "street" : "road of somewhere",
                    "number" : "2",
                    "city" : "Berlin",
                    "zip" : "93160",
                    "country" : "Germany",
                    "iban" : "DE07BARC20325388680799",
                    "swift_bic": "DEUTPTFF",
                    "bank_name": "Deutche Bank"
                },
            }
        }
    }
    

    Compliance Level

    Licensed

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

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

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Signature see APPENDIX - signed headers: "digest date x-request-id" required
    Digest see APPENDIX - sha-256 base64 encoded digest required
    Date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 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
    redirect_uri must correspond to one of the URLs provided when creating an application on the console required
    state an optional state parameter which will be provided back on redirection optional

    Body Parameters

    Parameter Type Description Use Case Usage
    session_id string The payment session_id receivd after a successful /prepare ALL required
    Parameter Description Use Case Usage
    type the payment scheme to use. Default: PIS (automatic selection) ALL required
    amount the requested amount to be transferred ALL required
    currency the currency of the transferred amount (EUR, GBP) ALL required
    communication description of the transaction, as seen on a bank statement ALL required
    beneficiary.name the name of the beneficiary) OPEN BANKNG required
    beneficiary.iban the IBAN of the beneficiary OPEN BANKNG required
    beneficiary.account_id the IBAN of the beneficiary OPEN BANKNG required
    beneficiary.swift_bic the swift/bic of the beneficiary's bank OPEN BANKNG required
    beneficiary.sort_code the sort code of the beneficiary's bank OPEN BANKNG required
    beneficiary.bank_name the full name of the beneficiary's bank OPEN BANKNG optional
    beneficiary.street the street name from the beneficiary's address OPEN BANKNG required
    beneficiary.number the street number from the beneficiary's address OPEN BANKNG optional
    beneficiary.complement the street name from the beneficiary's address OPEN BANKNG optional
    beneficiary.city the city from the beneficiary's address OPEN BANKNG required
    beneficiary.zip the zip codee from the beneficiary's address OPEN BANKNG required
    beneficiary.country the country from the beneficiary's address OPEN BANKNG required
    beneficiary.form The incorporation form of the beneficiary (only legal company ex: SARL) OPEN BANKNG required*
    beneficiary.incorporation The incorporation number of the PSU OPEN BANKNG required*
    debited_account_id 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 ALL optional
    debited_account_type "internal" or "provider". "internal" is the account id provided by the /accounts endpoint. "provider" is the iban/account_id provided by the provider. Default is "provider" ALL optional
    end_to_end_id A unique ID given by the creator of the payment and send to the bank. This field is also used to avoid double bookings ALL recommended
    psu_name The full name of the PSU ALL required
    psu_email The email of the PSU ALL required
    psu_phone The phone number of the PSU ALL optional
    psu_ip The IP Address of the PSU ALL optional
    psu_form The incorporation number of the PSU ALL required*
    psu_incorporation The IP Address of the PSU ALL required*
    psu_address.street The street of the PSU ALL required
    psu_address.number The street number of the PSU ALL optional
    psu_address.complement The address complement of the PSU ALL optional
    psu_address.city The city of the PSU ALL required
    psu_address.zip The ZIP code of the PSU ALL required
    psu_address.country The 2 letter country of the PSU ALL required

    * required if the beneficiary is a legal person

    Return Values

    The payments API endpoint will return an URL which is required to authenticate the PSU and consent the payment initiation.

    The possible return values are defined as follows:

    Status Code Description
    payment_created 201 The provider has succesfully initiated the payment
    payment_pending 202 The provider is processing the payment
    payment_unsuccessful 500 The provider rejected the payment
    payment_error 200 The payment has failed for technical reasons
    sca_required 200 The PSU got redirected to his bank and needs to authenticate
    provider_required 200 The payment has been prepared

    GET /initiate/decoupled

    SANDBOX

    This API endpoint is used to poll the authentication status within the decoupled model. Once the decoupled authentication flow as initiated, the status is "PENDING". Once the PSU has successfully authenticated, the status becomes "COMPLETED". If the authentication times out, is cancelled or failed, the status becomes "FAILED".

    Request

    GET /provider/[provider_id]/initiate/decoupled/[polling_id] HTTP/1.1
    Authorization: Bearer [access_token]
    Accept: application/json
    

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "provider": "handse",
        "status": "COMPLETED",
        "customer_id": "ec10fadfbadccb4901b522ab7286a549",
        "session_id": "4MDExNTA0MTMwNzAzM2",
        "payment_status": "payment_created"
    }
    

    Compliance Level

    Licensed

    Authentication Level

    client_credentials

    HTTP Request

    GET https://api.fintecture.com/pis/v1/provider/[provider_id]/initiate/decoupled/[polling_id]

    Header Parameters

    Parameter Value Usage
    app_id [app_id] optional
    Authorization Bearer [access_token] optional
    Signature see APPENDIX - signed headers: "date x-request-id" required
    Date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 required
    Accept application/json required

    URL Parameters

    Parameter Description Type Usage
    provider_id the id of the financial institution string required
    polling_id the polling_id of the decoupled flow string required

    Query Parameters

    -

    Body Parameters

    -

    POST /prepare

    PRODUCTION SANDBOX

    Request Body

    POST pis/v1/prepare HTTP/1.1
    Authorization: Bearer [access_token]
    Accept: application/json
    Content-Type: application/json
    
    { 
        "meta": {
            "psu_name" : "Bob McCheese", 
            "psu_email" : "bob@mccheese.com",
            "psu_phone" : "00339743593535",
            "psu_ip": "159.358.578.99",
            "psu_address": {
                "street": "route de la france",
                "number": "33",
                "complement": "2nd floor",
                "zip": "12001",
                "city": "Paris",
                "country": "FR"
            }
        },
        "data": {
            "type" : "PIS", 
            "attributes" : {
                "amount" : "149.30", 
                "currency": "EUR", 
                "communication" : "March Household expenses"
            }
        }
    }
    

    Response 200

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "status": "provider_required",
            "title": "Payment Prepared",
            "model": "redirect",
            "provider": "deutde",
            "session_id": "e07335fdeb073e0ebab13ba0bd71ad3c",
        },
        "data": {
            "type" : "SEPA", 
            "attributes" : {
                "amount" : "149.30", 
                "currency": "EUR", 
                "communication" : "March Household expenses",
                "beneficiary" : {
                    "name" : "Bob Smith",
                    "street" : "road of somewhere",
                    "number" : "2",
                    "city" : "Berlin",
                    "zip" : "93160",
                    "country" : "Germany",
                    "iban" : "DE07BARC20325388680799",
                    "swift_bic": "DEUTPTFF",
                    "bank_name": "Deutche Bank"
                },
            }
        }
    }
    

    Compliance Level

    All

    Authentication Level

    Grant Type: client_credentials or authorization_code

    HTTP Request

    POST https://api.fintecture.com/pis/v1/prepare

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Signature see APPENDIX - signed headers: "digest date x-request-id" required
    Digest see APPENDIX - sha-256 base64 encoded digest required
    Date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 required
    Accept application/json required
    Content-Type application/json required

    URL Parameters

    Parameter Description Usage

    -

    Query Parameters

    Parameter Value Usage
    redirect_uri must correspond to one of the URLs provided when creating an application on the console required

    Body Parameters

    Parameter Description Use Case Usage
    type the payment scheme to use. Default: PIS (automatic selection) ALL required
    amount the requested amount to be transferred ALL required
    currency the currency of the transferred amount (EUR, GBP) ALL required
    communication description of the transaction, as seen on a bank statement ALL required
    beneficiary.name the name of the beneficiary) OPEN BANKNG required
    beneficiary.iban the IBAN of the beneficiary OPEN BANKNG required
    beneficiary.account_id the IBAN of the beneficiary OPEN BANKNG required
    beneficiary.swift_bic the swift/bic of the beneficiary's bank OPEN BANKNG required
    beneficiary.sort_code the sort code of the beneficiary's bank OPEN BANKNG required
    beneficiary.bank_name the full name of the beneficiary's bank OPEN BANKNG optional
    beneficiary.street the street name from the beneficiary's address OPEN BANKNG required
    beneficiary.number the street number from the beneficiary's address OPEN BANKNG optional
    beneficiary.complement the street name from the beneficiary's address OPEN BANKNG optional
    beneficiary.city the city from the beneficiary's address OPEN BANKNG required
    beneficiary.zip the zip codee from the beneficiary's address OPEN BANKNG required
    beneficiary.country the country from the beneficiary's address OPEN BANKNG required
    beneficiary.form The incorporation form of the beneficiary (only legal company ex: SARL) OPEN BANKNG required*
    beneficiary.incorporation The incorporation number of the PSU OPEN BANKNG required*
    debited_account_id 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 ALL optional
    debited_account_type "internal" or "provider". "internal" is the account id provided by the /accounts endpoint. "provider" is the iban/account_id provided by the provider. Default is "provider" ALL optional
    end_to_end_id A unique ID given by the creator of the payment and send to the bank. This field is also used to avoid double bookings ALL recommended
    psu_name The full name of the PSU ALL required
    psu_email The email of the PSU ALL required
    psu_phone The phone number of the PSU ALL optional
    psu_ip The IP Address of the PSU ALL optional
    psu_form The incorporation number of the PSU ALL required*
    psu_incorporation The IP Address of the PSU ALL required*
    psu_address.street The street of the PSU ALL required
    psu_address.number The street number of the PSU ALL optional
    psu_address.complement The address complement of the PSU ALL optional
    psu_address.city The city of the PSU ALL required
    psu_address.zip The ZIP code of the PSU ALL required
    psu_address.country The 2 letter country of the PSU ALL required

    * required if the beneficiary is a legal person

    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
    payment_created 201 The provider has succesfully initiated the payment
    payment_pending 202 The provider is processing the payment
    payment_unsuccessful 500 The provider rejected the payment
    payment_error 200 The payment has failed for technical reasons
    sca_required 200 The PSU got redirected to his bank and needs to authenticate
    provider_required 200 The payment has been prepared

    GET /payments

    PRODUCTION SANDBOX

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "session_id": "44f00841780445d4981be9ea2f8aafae",
            "status": "payment_created",
            "code": 200,
            "customer_id": "3621eacaccd04fa772638dec70da323c"
        },
        "data": {
            "type": "SEPA",
            "attributes": {
                "amount": "42.05",
                "currency": "EUR",
                "beneficiary": {
                    "zip": "12011",
                    "city": "Paris",
                    "iban": "FR1420041010050500013M02606",
                    "name": "Legal Entity Name",
                    "number": "23",
                    "street": "Some street",
                    "country": "FR",
                    "bank_name": "Some Bank",
                    "swift_bic": "SOMEFRXXX"
                },
                "communication": "123",
                "end_to_end_id": "44f00841780445d4981be9ea2f8aafae"
            }
        }
    }
    

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

    Compliance Level

    All

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

    GET https://api.fintecture.com/pis/v1/payments/[session_id]

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Signature see APPENDIX - signed headers: "date x-request-id" required
    Date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 required
    Accept application/json required

    URL Parameters

    Parameter Description Usage
    session_id the session ID of the payment, all payments are returned if no session_id is specified optional

    Returned Values

    The payments API endpoint 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
    payment_created 201 The provider has succesfully initiated the payment
    payment_pending 202 The provider is processing the payment
    payment_unsuccessful 500 The provider rejected the payment
    payment_error 200 The payment has failed for technical reasons
    sca_required 200 The PSU got redirected to his bank and needs to authenticate
    provider_required 200 The payment has been prepared

    POST /refund

    PRODUCTION SANDBOX

    Request Body

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

    Response 201

    HTTP/1.1 201 Created
    Content-Type: application/json
    
    {
        "meta": {
            "status": 201,
            "code": "refund_initiated",
            "message": "Refund initiated successfully.",
            "session_id": "4MDExNTA0MTMwNzAzM2"
        }
    }
    

    Compliance Level

    All

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

    POST https://api.fintecture.com/pis/v1/refund

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Signature see APPENDIX - signed headers: "digest date x-request-id" required
    Digest see APPENDIX - sha-256 base64 encoded digest required
    Date RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) required
    x-request-id UUID v4 required
    Accept application/json required
    Content-Type application/json required

    URL Parameters

    Parameter Description Usage

    -

    Body Parameters

    Parameter Type Description Usage
    session_id string Payment session ID required

    Returned Values

    The refund API endpoint triggers a request for refund.

    The possible return values are defined in the following table:

    Status Description
    refund_initiated The refund has been successfully initiated by the TPP
    refund_accepted The refund has been accepted by the PSU and the account has been identified
    refund_pending The refund is pending for the TPP initiate refund
    refund_created The payment has successfully been refunded
    refund_aborted The refund has been cancelled
    refund_unsuccessful The refund payment initiation has been unsuccessful

    Appendix

    HTTP Signatures

    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 integrity reasons. In Sandbox, signatures are optional but highly recommended. The HTTP header follows the signing HTTP Messages IETF standard, with the following particularities:

    The following steps have to be undertaken to build the signature:

    <> 1. Build the message digest

    The digest is a SHA-256 hash of the payload encoded into base64, and concatenated with a "SHA-256=" prefix.

    digest function
    digest = "SHA-256=" + base64( SHA256( body ) )

    e.g. SHA-256=cjuagrzhZ8joOWLlQCCe5co30bRISL1VIWNq99da+hM=

    2. Create the signing parameters:

    3. Build the signing string:

    (request-target): get /ais/v1/customer/123/accounts\n
    date: Wed, 26 Feb 2020 17:29:51 GMT\n
    digest: SHA-256=cjuagrzhZ8joOWLlQCCe5co30bRISL1VIWNq99da+hM=\n
    x-request-id: 123e4567-e89b-12d3-a456-42665544

    4. Encrypt the signing string with your private key and encode it into base64

    signing function
    signature = base64( RSA-SHA256( signing string ) )

    5. Create the signature string by concatenating the following values:

    //For POST request
    keyId=app_id
    algorithm=rsa-sha256
    headers=(request-target) date digest x-request-id
    signature=signature

    //For GET request
    keyId=app_id
    algorithm=rsa-sha256
    headers=(request-target) date x-request-id
    signature=signature

    //For CONNECT AIS API
    keyId=app_id
    algorithm=rsa-sha256
    headers=x-date x-request-id
    signature=signature

    //For CONNECT PIS API
    keyId=app_id
    algorithm=rsa-sha256
    headers=digest x-date x-request-id
    signature=signature

    This results to an HTTP signature with the following structure:

    keyId="0354d723-d8d3-469a-8926-4f3f18b2c416",algorithm="rsa-sha256",headers="(request-target) date digest x-request-id",signature="eyvAyh5kuqifP8vkUy5KBWPgtQAurB7xMeC6T/KGJQm2JA=="

    Payment Status

    The below table show's the different status a payment may have and it's definition.

    Status Description
    payment_created The bank has accepted and succesfully created the payment.
    payment_unsuccessful The bank has not accepted or could not create the payment. This is mostly due to the PSU abandoning the authentication process, a failed authentication or insufficient funds.
    payment_pending The payment has a future execution date and the payment has not been processed yet.
    sca_required The PSU has selected a bank and is required to authenticate to his bank.
    provider_required The payment has been prepared but the PSU has not selected any provider.
    payment_error There was a technical error when initiating the payment. This usually happens if the bank APIs are down.

    Webhooks

    Step 5: Webhook

    POST /webhook HTTP/1.1
    Host: mywebsite.com
    Signature: keyId="2dfdcf57-5b2f-4309-846f-913d0b2802cf",algorithm="rsa-sha256",headers="(request-target) date digest x-request-id",signature="h0V0SUbjRhLEP/MiYo0Mgs1N17EuCEmKyQrDjxysc7iSiFXTjvY6qVEoaiRkzB8ZI0J39gGwOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fSTQ2/BSZWx04CjbPv/XUVusnkKVr3W6p+Vn073hAuJn1nKCvDOyl+QnDtstkzT+UacVzDA9L9nyPbbaPQHJobaZuG8TjhnI+Y0PZxneke6OU6fcdPT0uwkEamDOOExcMryHIX1iH5iiPMvLoVA8acqvvMSDYar0rlEQ2J1M4dcowWT8FxLo6C8uqvJIaBYm7Ze0RNJOwY0UBImCVDIuQLJuBjPwjQT5GjTQlg==
    Digest: SHA-256=wOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fS
    Date: Mon, 08 Jun 2020 23:11:23 GMT
    X-Request-ID: 88c414df-6895-48db-8ef3-1fd1ce4272c6
    Content-Type: application/x-www-form-urlencoded
    
    session_id=b2bca2bcd3b64a32a7da0766df59a7d2&satus=payment_created&customer_id=1ef74051a77673de120820fb370dc382&provider=provider&state=thisisastate
    

    Webhooks enables you to be notified of an event such as a payment status change.

    In the context of a payment model based on redirection, it is important to use a redundant payment notification channel in case the redirection fails. Some implementations uses webhooks as the main payment notification channel and the redirection simply displays the resulting payment result.

    Webhooks are configured in the Console in your application. Webhooks take 3 parameters:

    The webhook is a x-www-form-urlencoded POST request which is signed using the privately-kept public key (private asymmetric keys). Verify the signature using your private key, and only then process the order based on the result of the payment. Notice that the payload of the POST request is the same as the query string parameters returned to your redirect callback page.

    JSON:API

    The APIs are inspired from 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.

    Licensed vs Unlicensed TPP

    Depending whether you are a PSD2 licensed TPP or not, the integration possibiliies are different.

    As a PSD2 licensed TPP, either as a PISP, AISP or Fintecture Agent, you can integrate our APIs either in a complete white label solution or as a co-branded solution. For more information regarding our white label solutions or co-branded solution, contact us.

    For unlicensed TPP, you will need to use the Fintecture Connect webview which gives the PSU all the necessary information and disclaimers for a compliant user experience.

    The following section "How it works" explains how to integrate the Fintecture APIs using our Connect tool. However, the API documentation contains both APIs used in the context of licensed and unlicensed TPPs. Look for the Compliance Level tags:

    Definitions

    Support

    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.

    Errors

    Error Object

    The error object contains both a high level error code and an array of detailed error codes and messages. The root object has the following members:

    In case the error comes from the provider, the returned error code is provider_error and the provider's error is parsed into the errors array.

    Error Codes

    The below table is a non-comprehensive list of error codes:

    Status Code Errors Description
    400 provider_error bad_request a provider specific message is included
    400 bad_request bad_request Invalid parameters or malformed syntax.
    400 bad_request customer_unknown Invalid customer_id. Use a valid customer_id or authenticate to a bank to continue.
    400 bad_request 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 The session ID used is either expired or invalid.
    400 bad_request invalid_field The value or format of field [field] is incorrect
    400 bad_request mandatory_field_missing The mandatory field is missing: [field] has not been defined.
    400 bad_request invalid_debited_account Invalid debited_account_id. The debited_account_type is set to internal, please use an id provider by the accounts API.
    401 unauthorized invalid_token The token is either invalid or expired.
    401 unauthorized invalid_scopes Your app does not have the necessary scopes to access this API.
    401 unauthorized invalid_code The authorization code is either wrong or expired.
    401 unauthorized invalid_app_id Invalid app redirect URL.
    401 unauthorized invalid_app_url Invalid app_id.
    404 not_found not_found The requested resource could not be found. The requested resource either does not exist or is temporarly down.
    429 too_many_requests too_many_requests The user has sent too many requests in a given amount of time.
    500 internal_server_error internal_server_error An internal error has occured. If the error persists, please contact our support.
    501 not_implemented provider_endpoint_unavailable The provider endpoint is currently unavailable or has not been implemented yet.
    503 service_unavailable provider_unavailable The provider is currently unavailable. Please try again later.
    {
        "meta": {
            "title": "copyright",
            "details": "copyright© 2020 Fintecture. All rights reserved."
        }
    }
    

    Copyright © 2020 Fintecture. All rights reserved.