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

Get Started

SEPAINSTANT_SCTFPSSWIFT

AIS Connect

Build the future generation of Account Information Services

Get Started

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):

Immediate payment initiation
Scheduled payment initiation
Bulk payment initiation
Beta

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 or Unsuccessful following the approval of the payer. The Pending status is expected for scheduled payments.

When a payment session is Created, the payment session has successfully been initiated 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.

Status	Description
`payment_created`	The provider has succesfully 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

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 PSU has authorized the payment	Intermediate
`accepted`	The payment was accepted by the provider	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:

Access Token: The first step is to request a PIS access token
Connect URL: The following step is to build the Connect URL to which you will redirect the payer (i.e. PSU)
a. Validate Payment: The last step is to verify the payment on callback such that the payment status and order ID matches
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:

basic_token = base64(app_id:app_secret)

Method: POST
API: /oauth/accesstoken

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:

x-psu_type : The PSU type enables you to select a subset of banks based on the type of customer you have. If you only have retail customers and therefore would like to only show banks for retail custom, input retail. If you provider a B2B server, you can provider corporate. By default all is specified.
x-country : This field selects all banks from a specific country. By default, the default country is FR.
x-language : This field drives the language of the webview. The default language of the browser is used but you can force a language to be consistent with you website ex: FR.
x-provider : By specifying a provider, the webview will be filtered on that specific provider. This is usefull if you already know the bank of the payer.

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

Method: POST
API: /pis/v2/connect?redirect_uri=[redirect_uri]&state=[state]

parameter	type	sandbox	production	description
`redirect_uri`	url	optional	optional	Redirect URL as configured in the console. Default is the first URL configured.
`state`	url	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:

session_id: the payment session_id
status: the status of the payment (see status section for more information on the status)
provider: the bank code which the PSU connected to
customer_id: the customer_id of the PSU (which is a proxy of the PSU’s access_token to his bank so keep it safe!)
state: the state parameter which you provided during the PIS Connect URL

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:

redirect_uri?session_id=session_id&status=status&provider=provider&customer_id=customer_id&state=state

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.

Method: GET
API: /pis/v2/payments/[session_id]

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
`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="(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&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:

url: The URL to which the event message will be sent
offset: The delay in minutes after which the event message will be sent once an event occurs
event: The list of events to which you want to subscribe the webhook

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:

Connect URL: First, request the AIS Connect URL API to which you will redirect the user (i.e. PSU)
Access Token: Then, exchange the code received after redirection for an access_token
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

Method: GET
API: /ais/v1/connect

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:

provider: the code of the bank which the PSU connected to
customer_id: the customer_id of the PSU (which is a proxy of the PSU’s access_token to his bank so keep it safe!)
code: An authorization code to be exchange for an access_token
state: the state parameter which you provided during the AIS Connect URL

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:

basic_token = base64(app_id:app_secret)

Method: POST
API: /oauth/accesstoken

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.

Method: GET
API: /ais/v1/accounts

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.

Method: GET
API: /ais/v1//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.

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:

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/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": "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: "(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"
    },
    "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: "(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": "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: "(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 exeuction 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 codee 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 succesfully 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

POST 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",
                "created_at": "2021-01-14T09:42:57.000Z"
            },
            "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",
                "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",
                "created_at": "2021-01-14T08:25:53.000Z",
                "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",
                "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 succesfully 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

POST 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 succesfully 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": "French"
        },      
        "expirary": "86400",
        "cc": "xxx@xxx.xxx",
        "bcc": "xxx@xxx.xxx"
    },
    "data": {
        "type": "REQUEST_TO_PAY",
        "attributes": {
            "amount": "e233F7he30denj",
            "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-language`	2 letter language code - ex: fr	optional
`x-provider`	[provider_id]	optional
`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

SANDBOX

Settlements are outgoing payments from your Local Acquiring account to your own bank account. The settlements API lists all disbursments which occured 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 occured from your Local Acquiring account.

GET /settlements/[settlement_id]

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 settlemetn 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 occured 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 kid value is your app_id
The only algorithm currently supported is rsa-sha256
The mandatory headers for POST / PUT are (request-target), date, digest, x-request-id
The mandatory headers for GET / DELETE are (request-target), date, x-request-id
The mandatory parameters are kid, algorithm, headers and signature

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:

(request-target) : Method and pathname of an URL ; e.g. get /ais/v1/customer/123/accounts
date : An RFC 2822 formatted date ; e.g. Wed, 26 Feb 2020 17:29:51 GMT
digest : the SHA-256 digest of the body as describe in point 1
x-request-id : An UUID v4 formatted unique value ; e.g. 123e4567-e89b-12d3-a456-42665544

3. Build the signing string:

For GET & DELETE requests, use (request-target), date and x-request-id
For POST & PUT requests, use (request-target), date, digest and x-request-id

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

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
`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

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="(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&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.

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

url: The URL where you will listen to Fintecture webhooks and process the resulting message
offset: The delay in minutes when you post the webhook to be called after an event happened
event: The list of events to which you want the webhook to be called

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:

Licensed API reserved for PSD2 licensed TPPs
All API available for all TPPs

Definitions

PSD2 - Payment Services Directive 2 - A EU directive enforcing banks to open APIs for AIS & PIS purposes, and increase overall online payment security by enabling SCA.
RTS - Regulatory Technical Standard - the high level technical standard giving the framework to implement a PSD2 compliant system.
AIS - Account Information Services - The PSD2 definition of online services which provides access to bank account information (balances, transaction history, account holder information)
PIS - Payment information services - The PSD2 definition of online services which provide payment initiation from a bank account
SCA - Strong Customer Authentication - An RTS requirement to enable online payments in a PSD2 compliant way; which mandates the PSU to authenticate using 2 of the following 3 authentication methods: o Something the customer KNOWS - ex: username/password or PIN o Something the customer HAS - ex: phone or hardware token o Something the customer IS - ex: fingerprint or face recognition
TPP - Third Party Provider - The TPP is the ecommerce, or fintech, and any application interfacing with Fintecture Open Banking APIs.
ASPSP - Account Servicing Payment Service Provider - The ASPSP is essentially a bank
PSU - Payment Service User - The PSU is the account holder of a bank account ( a.k.a customer )
Provider - The Fintecture definition of an ASPSP
Customer - The Fintecture definition of a PSU
Fintecture - is also a verb that means to build a new solution or enhance an existing one using open banking (AIS, PIS or both) :)

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:

status: The HTTP error status code
code: The error code
errors: An array containing one or more error codes and messages

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 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© 2021 Fintecture. All rights reserved."
    }
}