Introduction
Welcome to the Fintecture API documentation.
Fintecture is a licensed and one-stop shop gateway to PSD2 Open Banking.
Our API endpoints allow easy and secure access to Account Information Services (AIS) and Payment initiation Services (PIS).
![]() |
AIS Connect Build the future generation of Account Information Services
PIS Connect Start accepting Payment Initiation Services into your website
|
How it works
Prerequisites
a. Create an account
Get started by subscribing to a free developer account. Join today to get access to our sandbox by registering on the developer console. When creating an account, specify your account type as either ECOMMERCE
or OPEN BANKING
depending on your use case.
ECOMMERCE
: If you intend to solely implement PIS to collect payments on your bank account.OPEN BANKING
: If you intend to to use AIS and/or PIS to collect payments on the bank accounts of your clients.
b. Store your credentials
In the developer console, create an application by providing the necessary fields such as your application name, logo and redirect URL, and take note of your app_id, app_secret and app_private_key. These are your keys to access our APIs.
Environments
The guides will explain how to integrate the Production environment APIs. To switch to Sandbox, simply change the base URLs:
Endpoints | SANDBOX | PRODUCTION |
---|---|---|
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 Account Information Services (AIS) and Payment Information Services (PIS) using the Fintecture Connect webview into your platform without an SDK.
It is recommended to use an SDK if available, as our community and ourselves continually update them with any new features and changes. The SDKs are available in our Github.
For any examples of real implementations of our APIs and of the Connect integrator, you can review them into from our Github.
AIS Connect
The complete connection flow using the Fintecture Connect webview, to access to AIS resources, has been simplified into the following 3 steps and illustrated using the payment flow below:
- 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 theaccess_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
- Method:
GET - API: /ais/v1/connect
parameter | type | 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 tocustomer_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 anaccess_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 | 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 | 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 | description | ||
---|---|---|---|---|
customer_id |
url | required | required | the customer_id received in Step 1 |
account_id |
url | required | required | the account->id received in 3.1 Accounts |
access_token |
header | required | required | the access token received in Step 2 |
signature |
header | optional | required | the HTTP signature calculated as describe in Appendix |
date |
header | optional | required | An RFC 2822 formatted date e.g. Wed, 26 Feb 2020 17:29:51 GMT |
x-request-id |
header | optional | required | An UUID v4 formatted unique value. |
PIS Connect
The complete payment flow using the Fintecture Connect webview has been simplified into the following steps and illustrated using the payment flow below:
- 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 | 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, inputretail
. If you provider a B2B server, you can providercorporate
. By defaultall
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
- Method:
POST - API: /pis/v2/connect?redirect_uri=[redirect_uri]&state=[state]
parameter | type | 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_idstatus
: the status of the payment (see status section for more information on the status)provider
: the bank code which the PSU connected tocustomer_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"
}
}
}
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 | 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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 |
---|---|---|
type |
the payment scheme to use. Default: PIS (automatic selection) | Required |
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 |
The account ID from which the account has to be debited from. If the field is not incldued, the bank will prompt PSU a choice of accounts to be used for payment | optional |
debited_account_type |
"internal" or "provider". "internal" is the account id provided by the /accounts endpoint. "provider" is the iban/account_id provided by the provider. Default is "provider" | optional |
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 |
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
Returned Values
Parameter | Description |
---|---|
meta.session_id |
The session_id of the payment |
meta.url |
the connect URL |
POST /initiate
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",
"message": "The payment requires customer authentication to complete.",
"model": "redirect",
"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"
}
}
}
}
Compliance Level
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 |
---|---|---|
type |
the payment scheme to use. Default: PIS (automatic selection) | Required |
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 |
The account ID from which the account has to be debited from. If the field is not incldued, the bank will prompt PSU a choice of accounts to be used for payment | optional |
debited_account_type |
"internal" or "provider". "internal" is the account id provided by the /accounts endpoint. "provider" is the iban/account_id provided by the provider. Default is "provider" | optional |
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 |
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
Return Values
The payments API endpoint will return an URL which is Required to authenticate the PSU and consent the payment initiation.
The possible return values are defined as follows:
Status | 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 |
GET /payments
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"
}
},
{
"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"
}
}
]
}
This endpoint returns the details of all transfers or of a specific transfer
Compliance Level
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 all payments including their status.
The possible payment status 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 |
GET /payments/[session_id]
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_created",
"code": 200,
"provider": "bnpafr",
"customer_id": "3621eacaccd04fa772638dec70da323c",
"settlement_id": "53206e909c5dfb5912d0ff771894eaa8"
},
"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"
}
}
}
This endpoint returns the details of all transfers or of a specific transfer
Compliance Level
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 status 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 |
POST /refund
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
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
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
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
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
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]
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
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 /ais/v1/customer/123/accounts HTTP/1.1
Accept: application/json
app_id: [app_id]
signature: keyId=0354d213-d8d3-462a-8926-4f3f1822c412,algorithm=rsa-sha256,signature=AlOOA0d7na2VSw0EbKRaONhTulToAFK8V/u/2PUffRKbHuwe59npbozcetpDXE1HrxLvrIA/fgAQYk4A==
In production, all our AIS and PIS APIs need to be signed with your app_private_key
for integrity reasons. In Sandbox, signatures are optional but highly recommended. The HTTP header follows the signing HTTP Messages IETF standard, with the following particularities:
- The 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/accountsdate
: An RFC 2822 formatted date ; e.g. Wed, 26 Feb 2020 17:29:51 GMTdigest
: the SHA-256 digest of the body as describe in point 1x-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
andx-request-id
- For POST & PUT requests, use
(request-target)
,date
,digest
andx-request-id
(request-target): get /ais/v1/customer/123/accounts\n
date: Wed, 26 Feb 2020 17:29:51 GMT\n
digest: SHA-256=cjuagrzhZ8joOWLlQCCe5co30bRISL1VIWNq99da+hM=\n
x-request-id: 123e4567-e89b-12d3-a456-42665544
4. Encrypt the signing string with your private key and encode it into base64
signing function | |
---|---|
signature = base64( RSA-SHA256( signing string ) ) |
5. Create the signature string by concatenating the following values:
keyId=app_id
algorithm=rsa-sha256
headers=(request-target) date digest x-request-id
signature=signature
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 Status
The below table show's the different status a payment may have and it's definition.
Status | Description |
---|---|
payment_created |
The bank has accepted and succesfully created the payment. |
payment_unsuccessful |
The bank has not accepted or could not create the payment. This is mostly due to the PSU abandoning the authentication process, a failed authentication or insufficient funds. |
payment_pending |
The payment has a future execution date and the payment has not been processed yet. |
sca_required |
The PSU has selected a bank and is required to authenticate to his bank. |
provider_required |
The payment has been prepared but the PSU has not selected any provider. |
payment_error |
There was a technical error when initiating the payment. This usually happens if the bank APIs are down. |
Webhooks
Step 5: Webhook
POST /webhook HTTP/1.1
Host: mywebsite.com
Signature: keyId="2dfdcf57-5b2f-4309-846f-913d0b2802cf",algorithm="rsa-sha256",headers="(request-target) date digest x-request-id",signature="h0V0SUbjRhLEP/MiYo0Mgs1N17EuCEmKyQrDjxysc7iSiFXTjvY6qVEoaiRkzB8ZI0J39gGwOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fSTQ2/BSZWx04CjbPv/XUVusnkKVr3W6p+Vn073hAuJn1nKCvDOyl+QnDtstkzT+UacVzDA9L9nyPbbaPQHJobaZuG8TjhnI+Y0PZxneke6OU6fcdPT0uwkEamDOOExcMryHIX1iH5iiPMvLoVA8acqvvMSDYar0rlEQ2J1M4dcowWT8FxLo6C8uqvJIaBYm7Ze0RNJOwY0UBImCVDIuQLJuBjPwjQT5GjTQlg==
Digest: SHA-256=wOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fS
Date: Mon, 08 Jun 2020 23:11:23 GMT
X-Request-ID: 88c414df-6895-48db-8ef3-1fd1ce4272c6
Content-Type: application/x-www-form-urlencoded
session_id=b2bca2bcd3b64a32a7da0766df59a7d2&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:
- 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 TPPsAll 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, an 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 codecode
: The error codeerrors
: 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 redirect URL. |
401 | unauthorized |
invalid_app_url |
Invalid app_id. |
404 | not_found |
not_found |
The requested resource could not be found. The requested resource either does not exist or is temporarly down. |
429 | too_many_requests |
too_many_requests |
The user has sent too many requests in a given amount of time. |
500 | internal_server_error |
internal_server_error |
An internal error has occured. If the error persists, please contact our support. |
501 | not_implemented |
provider_endpoint_unavailable |
The provider endpoint is currently unavailable or has not been implemented yet. |
503 | service_unavailable |
provider_unavailable |
The provider is currently unavailable. Please try again later. |
{
"meta": {
"title": "copyright",
"details": "copyright© 2020 Fintecture. All rights reserved."
}
}
Copyright © 2020 Fintecture. All rights reserved.