NAV Navbar v1
  • 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).




    PIS Connect
    Start accepting Payment Initiation Services into your website
    SEPAINSTANT_SCTFPSSWIFT


    AIS Connect
    Build the future generation of Account Information Services
    accountsbalancestransactions

    How it works

    Payment Initiation Flow

    Payment Initiation enables you to create an account-to-account payment order, essentially let your users transfer money immediately from their bank account into other bank accounts, such as yours if you're en ecommerce for example.

    When intiating a payment through Fintecture, we give you full control and visibility on your payment, while abastracting most of the complexity behind a payment initiation.

    By default, we will route your payment automatically using our Smart Routing capabilities, defining automatically the fastest, cheapest and most reliable scheme to use. For example, we will automatically select SEPA, INSTANT_SEPA, SWIFT or FPS. However, if you require to specify a specific scheme, it's also possible.

    Furthermore, using Fintecture Payment Initiation you will be able to initiate the following orders (with respect to banks support):

    When initiating a payment, this will create a payment session. This payment session can contain 1 to N payment transfer(s) (1: single payment, 2+: bulk payment). The payment session has a global status while the payment transfers have their own state in order to track them individually.

    The following diagram illustrates the flow:



    An immediate payment is expected to have a status of either Created, Pending or Unsuccessful following the approval of the payer. While most payments will be Created, exceptionnaly some might end up as Pending. Both Created and Pending payments are irrevocable and the funds are reserved in the bank account of the payer.

    For scheduled payments, Pending status is expected unil the execution date is reach where the payment should change to either Created or Unsuccessful.

    When a payment session is both Created and Pending, the payment has successfully been created by the bank as the payer has authenticated and accepted the payment request. At this point you can already show a payment success page to the payer. However, it's best to wait until the settlement has been completed before finalizing and shipping the order.

    When a payment session is Unsuccessful, the payment was cancelled by the payeur or rejected by the bank. An indicative reason is provided in the transfer_reason field.

    Status Description
    payment_created The payment has been successfully created
    payment_pending The payment is currently pending or in the process of being created
    payment_unsuccessful The payment was rejected by either the payer or the bank
    payment_error The payment has failed for technical reasons
    sca_required The payer got redirected to his bank and needs to authenticate
    provider_required The payment has been prepared
    payment_waiting The request to pay has been generated and is waiting for payer

    In terms of transfer processing, state values can be classified by phase - Intermediate or Final.

    State Description Phase
    completed The payment settlement is completed Final
    sent The payment is being processed and the bank does not return settlement information Final
    processing The payment is being processed Intermediate
    pending The payment is pending for execution (in the case of deferred payments) Intermediate
    authorized The payer has authorized the payment Intermediate
    accepted The payment was accepted by the bank Intermediate
    rejected The payment has been rejected (see reasons in APPENDIX) Final

    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.

    Once the account is create, you can access directly all SANDBOX ressources.

    To access PRODUCTION ressources, you will need to Activate your account.

    b. Generate credentials

    The console enables you to create Shops in case you are using an integration module. For a custom API integration, you will need to go the the Developer menu.

    In the developer menu, 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
    APIs https://api-sandbox.fintecture.com https://api.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 Payment Information Services (PIS) and Account Information Services (AIS) 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.

    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. Connect URL: The following step is to build the Connect URL to which you will redirect the payer (i.e. PSU)
    3. a. Validate Payment: The last step is to verify the payment on callback such that the payment status and order ID matches
    4. b. Listen to Webhook: Additionally, it is a best practice to listen to a webhook to intercept payments status change events as a redundant channel to the redirect callback



    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...",
      "expires_in": 3600
    }
    

    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: Connect URL

    Step 2: Request

    POST /pis/v2/connect?redirect_uri=[redirect_uri]&state=[state] HTTP/1.1
    Authorization: Bearer [access_token]
    Signature: [signature]
    Digest: [digest]
    Date: [date]
    x-request-id: [request_id]
    x-psu_type: [psu_type]
    x-country: [country]
    Accept: application/json
    Content-Type: application/json
    
    { 
        "meta": {
            "psu_name" : "Bob McCheese", 
            "psu_email" : "bob@mccheese.com",
            "psu_phone" : "09743593535",
            "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" : "ORDER-6543321"
            }
        }
    }
    

    Step 2: Response

    HTTP/1.1 200 OK
    
    {
        "meta": {
            "session_id": "fc8583ae532346d1b7c5ed1c2853d497",
            "url": "https://connect.fintecture.com/v2/pis/00547d75-243e-48ce-9b0c-12136c076a8a"
        }
    }
    

    The second step is to request the PIS Connect API to receive the URL to redirect the PSU towards Fintecture Connect.

    In the headers, you will find the following parameters which enables you to control the Connect webview:

    The body is seperated into meta and data. In the former, you will specify all the information regarding the payer. The the latter you will specify all the necassary information to process the payment. Note that if you have fixed a beneficiary to your application, you should not include the beneficiary in the payload, as the one you have fixed will be used by default and cannot be overriden.

    Simply POST the illustrated request including all the necessary headers, body and query string. For more information on each field, see the /connect API



    parameter type sandbox production description
    redirect_uri query optional optional Redirect URL as configured in the console. Default is the first URL configured.
    state query required required A state parameter which will be provided back on redirection
    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
    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)


    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 3.a.: Validate Payment

    Step 3.a.: Request

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

    Step 3.a.: 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", 
                "execution_date": "2021-02-28",
                "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",
                "transfer_state": "completed",
                "scheme": "INSTANT_SEPA"
            }
        }
    }
    

    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 query 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
    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 3.b.: Webhooks

    Step 3.b.: Request

    POST /webhook HTTP/1.1
    Host: mywebsite.com
    Signature: keyId="2dfdcf57-5b2f-4309-846f-913d0b2802cf",algorithm="rsa-sha256",headers="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&status=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.



    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 query 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 query required required the customer_id received in Step 1
    account_id query 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.



    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://api.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://api.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:

    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

    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/v2/connect

    Header Parameters

    Parameter Value Usage
    app_id [app_id] required
    Accept application/json required
    Signature see APPENDIX - signed headers: "(request-target) date x-request-id" required
    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: "(request-target) 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: "(request-target) 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": "0cf2ebf7e73c8144d51e60aea454add9",
            "provider": "cmcifrpp",
            "last_authentication": "2021-07-14T08:43:01.876Z",
            "remaining_days": 89
        },
        "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

    Compliance Level

    All

    Authentication Level

    authorization_code

    HTTP Request

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

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] required
    Signature see APPENDIX - signed headers: "(request-target) 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",
            "provider": "cmcifrpp",
            "last_authentication": "2021-07-14T08:43:01.876Z",
            "remaining_days": 89
        },
        "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"
                }
            }
        ],
        "links": {
            "next": "https://api.fintecture.com/ais/v1/customer/0cf2ebf7e73c8144d51e60aea454add9/accounts/b71722204d1a3f5ecd895/transactions?page[number]=2", 
            "self": "https://api.fintecture.com/ais/v1/customer/0cf2ebf7e73c8144d51e60aea454add9/accounts/b71722204d1a3f5ecd895/transactions?page[number]=1"
        }
    }
    

    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: "(request-target) 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": "8562e79aa2256c275b96ef3304e936e7",
            "provider": "cmcifrpp",
            "last_authentication": "2021-07-14T08:43:01.876Z",
            "remaining_days": 89
        },
        "data": [
            {
                "id": "1593ca222ce8bf015",
                "type": "accountholders",
                "attributes": {
                    "full_name": "Mr John Smith"
                }
            }
        ]
    }
    

    This endpoint retrieves all personal information of the client 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: "(request-target) 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: "(request-target) 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

    POST /pis/v2/connect?redirect_uri=[redirect_uri]&state=[state] HTTP/1.1
    Authorization: Bearer [access_token]
    Signature: [signature]
    Digest: [digest]
    Date: [date]
    x-request-id: [request_id]
    x-psu_type: [psu_type]
    x-country: [country]
    Accept: application/json
    Content-Type: application/json
    
    { 
        "meta": {
            "psu_name" : "Bob McCheese", 
            "psu_email" : "bob@mccheese.com",
            "psu_phone" : "09743593535",
            "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" : "Order 6543321",
                "beneficiary" : {
                    "name" : "Bob Smith",
                    "street" : "road of somewhere",
                    "number" : "2",
                    "city" : "Paris",
                    "zip" : "93160",
                    "country" : "FR",
                    "iban" : "FR1420041010050500013M02606",
                    "swift_bic": "BANKFRXXXXX"
                }
            }
        }
    }
    

    Response 201

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "session_id": "c4c889194f28455a9f47811ef54ef9e2",
            "url": "https://connect.fintecture.com/v2/pis/00547d75-243e-48ce-9b0c-12136c076a8a"
        }
    }
    

    Compliance Level

    All

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

    POST https://api.fintecture.com/pis/v2/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: "(request-target) date digest 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
    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
    origin_uri the URL to which he will be returned if he cancels the payment from the Connect webview. By default the user is returned to the previous screen (i.e. your checkout page) optional
    state A state parameter which will be provided back on redirection Required

    Body Parameters

    Parameter Description Usage
    amount the requested amount to be transferred Required
    currency the currency of the transferred amount (EUR, GBP) Required
    communication description of the transaction, as seen on a bank statement Required
    execution_date The execution date (YYYY-MM-DD) of the payment order. If no date is specified, the execution is considered as immediate optional
    beneficiary.name the name of the beneficiary conditional
    beneficiary.iban the IBAN of the beneficiary conditional
    beneficiary.swift_bic the swift/bic of the beneficiary's bank conditional
    beneficiary.street the street name from the beneficiary's address conditional
    beneficiary.number the street number from the beneficiary's address optional
    beneficiary.complement extra information regarding the beneficiary's address optional
    beneficiary.city the city from the beneficiary's address conditional
    beneficiary.zip the zip code from the beneficiary's address conditional
    beneficiary.country the country from the beneficiary's address conditional
    beneficiary.form The incorporation form of the beneficiary (only legal persons ex: SARL) conditional*
    beneficiary.incorporation The incorporation number of the beneficiary conditional*
    debited_account_id Predefine the account which which the payment will be done optional
    debited_account_type "internal" or "iban", "bban".
    end_to_end_id A unique ID given by the creator of the payment and send to the bank. By default de session_id is used. optional
    scheme the payment scheme to use. Default: AUTO (automatic selection), SEPA, INSTANT_SEPA optional
    psu_name The full name of the PSU Required
    psu_email The email of the PSU Required
    psu_phone The phone number of the PSU Required
    psu_phone_prefix The phone prefix of the PSU (ex: 0033) optional
    psu_ip The IP Address of the PSU optional
    psu_form The incorporation form of the PSU Required*
    psu_incorporation The incorporation number of the PSU Required*
    psu_address.street The street of the PSU Required
    psu_address.number The street number of the PSU optional
    psu_address.complement The address complement of the PSU optional
    psu_address.city The city of the PSU Required
    psu_address.zip The ZIP code of the PSU Required
    psu_address.country The 2 letter country of the PSU Required

    conditional Required if no fixed beneficiary has been mapped to the application * Required if the beneficiary is a legal person

    Returned Values

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

    POST /initiate

    PRODUCTION SANDBOX

    Request Body

    POST pis/v2/provider/[provider_id]/initiate HTTP/1.1
    Authorization: Bearer [access_token]
    Signature: [signature]
    Digest: [digest]
    Date: [date]
    x-request-id: [request_id]
    Accept: application/json
    Content-Type: application/json
    
    { 
        "meta": {
            "psu_name" : "Bob McCheese", 
            "psu_email" : "bob@mccheese.com",
            "psu_phone" : "09743593535",
            "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" : "Order 6543321",
                "beneficiary" : {
                    "name" : "Bob Smith",
                    "street" : "road of somewhere",
                    "number" : "2",
                    "city" : "Paris",
                    "zip" : "93160",
                    "country" : "FR",
                    "iban" : "FR1420041010050500013M02606",
                    "swift_bic": "BANKFRXXXXX"
                }
            }
        }
    }
    

    Response 200

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "status": "sca_required",
            "provider": "bankfr",
            "customer_id": "xcgf54zji904c3t89zu4rt2c98z042r5cd0",
            "session_id": "e07335fdeb073e0ebab13ba0bd71ad3c",
            "url": "https://sandbox.auth.somebank.com/authorize?response_type=code&client_id=..."
        },
        "data": {
            "type" : "PIS", 
            "attributes" : {
                "amount" : "149.30", 
                "currency": "EUR", 
                "communication" : "March Household expenses",
                "execution_date": "2021-02-28",
                "beneficiary" : {
                    "name" : "Bob Smith",
                    "street" : "road of somewhere",
                    "number" : "2",
                    "city" : "Paris",
                    "zip" : "93160",
                    "country" : "FR",
                    "iban" : "FR1420041010050500013M02606",
                    "swift_bic": "BANKFRXXXXX"
                },
                "transfer_state": "accepted",
                "scheme": "INSTANT_SEPA"
            }
        }
    }
    

    Compliance Level

    Licensed

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

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

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] Required
    Signature see APPENDIX - signed headers: "(request-target) date digest 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 A state parameter which will be provided back on redirection optional

    Body Parameters

    Parameter Description Usage
    amount the requested amount to be transferred Required
    currency the currency of the transferred amount (EUR, GBP) Required
    communication description of the transaction, as seen on a bank statement Required
    beneficiary.name the name of the beneficiary) conditional
    beneficiary.iban the IBAN of the beneficiary conditional
    beneficiary.swift_bic the swift/bic of the beneficiary's bank conditional
    beneficiary.street the street name from the beneficiary's address conditional
    beneficiary.number the street number from the beneficiary's address optional
    beneficiary.complement the street name from the beneficiary's address optional
    beneficiary.city the city from the beneficiary's address conditional
    beneficiary.zip the zip code from the beneficiary's address conditional
    beneficiary.country the country from the beneficiary's address conditional
    beneficiary.form The incorporation form of the beneficiary (only legal persons ex: SARL) conditional*
    beneficiary.incorporation The incorporation number of the PSU conditional*
    debited_account_id Predefine the account which which the payment will be done optional
    debited_account_type "internal" or "iban", "bban".
    end_to_end_id A unique ID given by the creator of the payment and send to the bank. By default de session_id is used. optional
    scheme the payment scheme to use. Default: AUTO (automatic selection), SEPA, INSTANT_SEPA optional
    psu_name The full name of the PSU Required
    psu_email The email of the PSU Required
    psu_phone The phone number of the PSU Required
    psu_phone_prefix The phone prefix of the PSU (ex: 0033) optional
    psu_ip The IP Address of the PSU optional
    psu_form The incorporation form of the PSU Required*
    psu_incorporation The incorporation number of the PSU Required*
    psu_address.street The street of the PSU Required
    psu_address.number The street number of the PSU optional
    psu_address.complement The address complement of the PSU optional
    psu_address.city The city of the PSU Required
    psu_address.zip The ZIP code of the PSU Required
    psu_address.country The 2 letter country of the PSU Required

    conditional Required if no fixed beneficiary has been mapped to the application * Required if the beneficiary is a legal person

    Return Values

    The payments API endpoint will return a payment session status and a payment transfer state which defines the next step to be taken in order to complete the payment initiation cycle.

    The possible return values are defined in the following table:

    Status Description
    payment_created The provider has successfully initiated the payment
    payment_pending The provider is processing the payment
    payment_unsuccessful The provider rejected the payment
    payment_error The payment has failed for technical reasons
    sca_required The PSU got redirected to his bank and needs to authenticate
    provider_required The payment has been prepared
    payment_waiting The request to pay has been generated and is waiting for payer
    State Description
    completed The payment settlement is completed
    processing The payment is being processed
    pending The payment is pending for execution (in the case of deferred payments)
    rejected The payment has been rejected (see reasons in APPENDIX)
    authorized The PSU has authorized the payment
    accepted The payment was accepted by the provider

    GET /payments

    PRODUCTION SANDBOX

    Request

    GET pis/v2/payments HTTP/1.1
    Authorization: Bearer [access_token]
    Signature: [signature]
    Date: [date]
    x-request-id: [request_id]
    Accept: application/json
    

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "data": [
            {
                "id": "ecec9f13407f4c2cb5f1591255e8f815",
                "type": "payments",
                "meta": {
                    "session_id": "ecec9f13407f4c2cb5f1591255e8f815",
                    "status": "payment_unsuccessful",
                    "provider": "bnpafr",
                    "session_id": "1005053407f4c100505cb5f1510050516",
                },
                "attributes": {
                    "amount": "150.30",
                    "currency": "EUR",
                    "beneficiary": {
                        "zip": "12001",
                        "city": "Paris",
                        "iban": "FR1420041010050500013M02606",
                        "name": "Dummy SA",
                        "number": "23",
                        "street": "dummy street",
                        "country": "FR",
                        "bank_name": "BNP-PARIBAS SA",
                        "swift_bic": "BNPAFRPPXXX"
                    },
                    "communication": "AB784159624_ABC",
                    "execution_date": "2021-07-15",
                    "end_to_end_id": "ecec9f13407f4c2cb5f1591255e8f815",
                    "transfer_state": "rejected",
                    "transfer_reason": "blocked_account",
                    "scheme": "INSTANT_SEPA"
                }
            },
            {
                "id": "f7a35d376fd54c9385ad2cac1b159732",
                "type": "payments",
                "meta": {
                    "session_id": "f7a35d376fd54c9385ad2cac1b159732",
                    "status": "payment_created",
                    "provider": "bnpafr",
                    "customer_id": "57913d566d4d8a68c1a19ba5c9266e7b"
                },
                "attributes": {
                    "amount": "150.30",
                    "currency": "EUR",
                    "beneficiary": {
                        "zip": "12001",
                        "city": "Paris",
                        "iban": "FR1420041010050500013M02606",
                        "name": "Dummy SA",
                        "number": "23",
                        "street": "dummy street",
                        "country": "FR",
                        "bank_name": "BNP-PARIBAS SA",
                        "swift_bic": "BNPAFRPPXXX"
                    },
                    "communication": "AB784159623_XYZ",
                    "execution_date": "2021-07-15",
                    "end_to_end_id": "f7a35d376fd54c9385ad2cac1b159732",
                    "transfer_state": "completed",
                    "scheme": "SEPA"
                }
            }
        ]
    }
    

    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/v2/payments

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] Required
    Signature see APPENDIX - signed headers: "(request-target) 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
    - - -

    Returned Values

    The payments API endpoint will return a payment session status and a payment transfer state which defines the next step to be taken in order to complete the payment initiation cycle.

    The possible return values are defined in the following table:

    Status Description
    payment_created The provider has successfully initiated the payment
    payment_pending The provider is processing the payment
    payment_unsuccessful The provider rejected the payment
    payment_error The payment has failed for technical reasons
    sca_required The PSU got redirected to his bank and needs to authenticate
    provider_required The payment has been prepared
    payment_waiting The request to pay has been generated and is waiting for payer
    State Description
    completed The payment settlement is completed
    processing The payment is being processed
    pending The payment is pending for execution (in the case of deferred payments)
    rejected The payment has been rejected (see reasons in APPENDIX)
    authorized The PSU has authorized the payment
    accepted The payment was accepted by the provider

    GET /payments/[session_id]

    PRODUCTION SANDBOX

    Request

    GET pis/v2/payments/[session_id] HTTP/1.1
    Authorization: Bearer [access_token]
    Signature: [signature]
    Date: [date]
    x-request-id: [request_id]
    Accept: application/json
    

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {
            "session_id": "44f00841780445d4981be9ea2f8aafae",
            "status": "payment_unsuccessful",
            "code": 200,
            "provider": "bnpafr",
            "customer_id": "3621eacaccd04fa772638dec70da323c"
        },
        "data": {
            "type": "payments",
            "attributes": {
                "amount": "42.05",
                "currency": "EUR",
                "execution_date": "2021-02-28",
                "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": "ORDER 123",
                "end_to_end_id": "44f00841780445d4981be9ea2f8aafae",
                "transfer_state": "rejected",
                "transfer_reason": "cancelled",
                "scheme": "SEPA"
            }
        }
    }
    

    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/v2/payments/[session_id]

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] Required
    Signature see APPENDIX - signed headers: "(request-target) 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 session status and a payment transfer state which defines the next step to be taken in order to complete the payment initiation cycle.

    The possible return values are defined in the following table:

    Status Description
    payment_created The provider has successfully initiated the payment
    payment_pending The provider is processing the payment
    payment_unsuccessful The provider rejected the payment
    payment_error The payment has failed for technical reasons
    sca_required The PSU got redirected to his bank and needs to authenticate
    provider_required The payment has been prepared
    payment_waiting The request to pay has been generated and is waiting for payer
    State Description
    completed The payment settlement is completed
    processing The payment is being processed
    pending The payment is pending for execution (in the case of deferred payments)
    rejected The payment has been rejected (see reasons in APPENDIX)
    authorized The PSU has authorized the payment
    accepted The payment was accepted by the provider

    POST /refund

    PRODUCTION SANDBOX

    Request Body

    { 
        "meta": {
            "session_id": "e233F7he30denj"
        },
        "data": {
            "attributes": {
                "amount": "15.2"
            }
        }
    }
    

    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/v2/refund

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] Required
    Signature see APPENDIX - signed headers: "(request-target) date digest 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
    amount string The amount in case of partial refund. By default, the full amount of the original payment is used. optional

    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

    POST /request-to-pay

    PRODUCTION SANDBOX

    Request Body

    { 
        "meta": {
            "psu_name": "Jean",
            "psu_email": "xxx@xxx.xxx",
            "psu_phone": "601020304",
            "psu_phone_prefix": "+33",
            "psu_address": {
                "street_number": "5",
                "street": "Parvis Alan Turing",
                "zipcode": "75013",
                "city": "Paris",
                "country": "FR"
            },      
            "expirary": 86400,
            "cc": "xxx@xxx.xxx",
            "bcc": "xxx@xxx.xxx"
        },
        "data": {
            "type": "REQUEST_TO_PAY",
            "attributes": {
                "amount": 100,
                "currency": "EUR",
                "communication": "#ref"
            }
        }
    }   
    

    Response 201

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

    Compliance Level

    All

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

    POST https://api.fintecture.com/pis/v2/request-to-pay

    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
    x-psu-type [retail, corporate, all] optional
    x-country 2 letter country - ex: fr optional
    x-provider [provider_id] optional
    x-language 2 letter language code - ex: fr Required
    Accept application/json Required
    Content-Type application/json Required

    URL Parameters

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

    Body Parameters

    Parameter Type Description Usage
    attributes.amount number The requested amount to be payed Required
    attributes.currency string(3) ISO 4217 The currency of the payed amount Required
    attributes.communication string(255) The communication of the payment Optional
    psu_name string(255) The name of the PSU Required
    psu_email string(255) The email of the PSU Required
    psu_phone string(20) The number of the PSU Required
    psu_phone_prefix string(4) The indice number of the PSU Required
    psu_address.street_number string(20) The street number of the PSU Optional
    psu_address.street string(255) The street number of the PSU Optional
    psu_address.zipcode string(255) The zip code of the PSU Optional
    psu_address.city string(255) The city of the PSU Optional
    psu_address.country string(2) ISO 3166-1 The country of the PSU Optional
    expirary int(8) The number of seconds of the validity of the request to pay, by default 86400 Optional
    cc string(255) The CC email to receive a copy (If multiple emails, the emails must be concatenated with a comma.) Optional
    bcc string(255) The BCC email to receive a copy (If multiple emails, the emails must be concatenated with a comma.) Optional

    Returned Values

    The request to pay API endpoint triggers a request for pay.

    The possible return values are defined in the following table:

    Code Status Description
    201 request_to_pay_initiated The request to pay has been successfully initiated by us
    500 request_to_pay_unsuccessful The request to pay initiation has been unsuccessful

    GET /settlements

    PRODUCTION SANDBOX

    Settlements are outgoing payments from your Local Acquiring account to your own bank account. The settlements API lists all disbursements which occurred from your Local Acquiring account.

    Local Acquiring can be enabled in your console.

    Request

    GET pis/v2/settlements HTTP/1.1
    Authorization: Bearer [access_token]
    Signature: [signature]
    Date: [date]
    x-request-id: [request_id]
    Accept: application/json
    

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "data": [{
            "id": "127335fdeb073e0eb2313ba0bd71ad44",
            "type": "settlements",
            "attributes": {
                "amount": "230.25",
                "currency": "EUR",
                "execution_date": "2021-03-15",
                "communication": "SETTLEMENT-11112"
            }},{
            "id": "964321fdeb073ddeb2313ba876543d43",
            "type": "settlements",
            "attributes": {
                "amount": "33.05",
                "currency": "EUR",
                "execution_date": "2021-02-15",
                "communication": "SETTLEMENT-11111"
            }
        }]
    }
    

    Compliance Level

    All

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

    GET https://api.fintecture.com/pis/v2/settlements

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] Required
    Signature see APPENDIX - signed headers: "(request-target) 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
    - - -

    Query Parameters

    Parameter Description Type Usage
    filter[date_to] filter settlements by booking date. yyyy-mm-dd optional
    filter[date_from] filter settlements by booking date. yyyy-mm-dd optional

    Returned Values

    The settlements API endpoint lists all disbursements which occurred from your Local Acquiring account.

    GET /settlements/[settlement_id]

    PRODUCTION SANDBOX

    Settlements are outgoing payments from your Local Acquiring account to your own bank account. The settlements API also include the relationship with the payment sessions for your reconciliation needs.

    Local Acquiring can be enabled in your console.

    Request

    GET pis/v2/settlements/[settlement_id]?include=payments HTTP/1.1
    Authorization: Bearer [access_token]
    Signature: [signature]
    Date: [date]
    x-request-id: [request_id]
    Accept: application/json
    

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "data": {
            "id": "127335fdeb073e0eb2313ba0bd71ad44",
            "type": "settlements",
            "attributes": {
                "amount": "230.25",
                "currency": "EUR",
                "execution_date": "2021-03-15",
                "communication": "SETTLEMENT-11112"
            },
            "relationships": {
                "payments": {
                    "data": [
                        { "type": "payments", "id": "f7a35d376fd54c9385ad2cac1b159732"},
                        { "type": "payments", "id": "264ccb4adbc25f344f6c678c1e256ac5"}
                    ]
                }
            }
        },
        "included": [
            {
                "id": "f7a35d376fd54c9385ad2cac1b159732",
                "type": "payments",
                "attributes": {
                    "amount": "42.05",
                    "currency": "EUR",
                    "execution_date": "2021-02-28",
                    "communication": "ORDER-123",
                }
            },
            {
                "id": "264ccb4adbc25f344f6c678c1e256ac5",
                "type": "payments",
                "attributes": {
                    "amount": "188.20",
                    "currency": "EUR",
                    "execution_date": "2021-02-2",
                    "communication": "ORDER-321",
                }
            }
        ]
    }
    

    Compliance Level

    All

    Authentication Level

    client_credentials or authorization_code

    HTTP Request

    GET https://api.fintecture.com/pis/v2/settlements/[settlement_id]

    Header Parameters

    Parameter Value Usage
    Authorization Bearer [access_token] Required
    Signature see APPENDIX - signed headers: "(request-target) 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
    settlement_id the settlement ID of the payment, all payments are returned if no settlement ID is specified optional

    Query Parameters

    Parameter Description Type Usage
    include Add the included object which includes all the details of the payments payments optional

    Returned Values

    The settlements API endpoint, without specifying a specific settlement ID, will return an array of settlement payments which occurred in your local acquiring bank account. The settlements API endpoint, with a specific settlement ID, will return an object including the details of the settlement. By including the "include" query param, you can return all payment sessions which corresponds to each settlements.

    Appendix

    HTTP Signatures

    Example of Signature (GET)

    GET /ais/v1/customer/123/accounts HTTP/1.1
    Accept: application/json
    Authorization: Bearer [access_token]
    Date: Wed, 26 Feb 2020 17:29:51 GMT
    X-Request-Id: 123e4567-e89b-12d3-a456-42665544
    Signature: keyId="0354d213-d8d3-462a-8926-4f3f1822c412",algorithm="rsa-sha256",headers="(request-target) date x-request-id", signature="AlOOA0d7na2VSw0EbKRaONhTulToAFK8V/u/2PUffRKbHuwe59npbozcetpDXE1HrxLvrIA/fgAQYk4A=="
    

    Example of Signature (POST)

    POST /pis/v2/initiate HTTP/1.1
    Accept: application/json
    Authorization: Bearer [access_token]
    Date: Wed, 26 Feb 2020 17:29:51 GMT
    X-Request-Id: 123e4567-e89b-12d3-a456-42665544
    Digest: SHA-256=cjuagrzhZ8joOWLlQCCe5co30bRISL1VIWNq99da+hM=
    Signature: keyId="0354d213-d8d3-462a-8926-4f3f1822c412",algorithm="rsa-sha256",headers="(request-target) date digest x-request-id", 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?include_query=true\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

    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 Session Status

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

    Status Description
    payment_created The payment has been successfully created
    payment_pending The payment is currently pending or in the process of being created
    payment_unsuccessful The payment was rejected by either the payer or the bank
    payment_error The payment has failed for technical reasons
    sca_required The payer got redirected to his bank and needs to authenticate
    provider_required The payment has been prepared
    payment_waiting The request to pay has been generated and is waiting for payer

    See Payment Initiation Flow to understand how Status and States represent and what you should consider

    Payment Transfer States

    The below table shows the different states a transfer may have and it's definition.

    State Description Phase
    completed The payment settlement is completed Final
    sent The payment is being processed and the bank does not return settlement information Final
    processing The payment is being processed Intermediate
    pending The payment is pending for execution (in the case of deferred payments) Intermediate
    authorized The payer has authorized the payment Intermediate
    accepted The payment was accepted by the bank Intermediate
    rejected The payment has been rejected (see reasons in APPENDIX) Final

    See Payment Initiation Flow to understand how Status and States represent and what you should consider

    Payment Rejected Reason

    The below table shows the different payment transfer rejected reasons. The list is not exhaustive:

    Reason Description
    insufficient_funds The PSU has insufficient funds
    incorrect_account_number The provided account number is unknown
    closed_account The PSU account is closed
    blocked_account The PSU account is blocked
    transaction_forbidden The transaction is forbidden
    too_many_transactions The bulk payment contains too many transactions
    invalid_execution_date The execution date is invalid
    customer The payment was rejected by the customer
    cancelled The payment was cancelled by the customer
    fraudulent_originated The payment was rejected as fraud was detected
    no_answer The payment was rejected as it expired
    regulatory_reason The payment was rejected for regulatory reason

    Webhooks

    Step 5: Webhook

    POST /webhook HTTP/1.1
    Host: mywebsite.com
    Signature: keyId="2dfdcf57-5b2f-4309-846f-913d0b2802cf",algorithm="rsa-sha256",headers="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&status=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.

    Pagination

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "meta": {},
        "data": [{},{}],
        "links": {
            "next": "https://api.fintecture.com/ais/v1/.../transactions?page[number]=2", 
            "self": "https://api.fintecture.com/ais/v1/.../transactions?page[number]=1"
        }
    }
    

    Several APIs return pagination results. Those APIs are the following

    AIS APIs follow the same indexing as provides the banks. Most banks don't support pagination so all the results will be returned as a single page. As the pagination logic is based on what the bank retuns, the control on pagination is limited. The available feature is to be able to navigate throught the using the next, self page links found at the end of the JSON provided the bank paginates the results.

    PIS APIs are more flexible as these are provded directly by Fintecture. The following filters are available:

    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_id.
    401 unauthorized invalid_app_url Invalid app redirect URL.
    404 not_found not_found The requested resource could not be found. The requested resource either does not exist or is temporarily 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 occurred. 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© 2021 Fintecture. All rights reserved."
        }
    }
    

    Copyright © 2021 Fintecture. All rights reserved.