v2 (latest)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).
|
Payment Initiation Services Start accepting Payment Initiation Services into your website
Account Information Services Build the future generation of Account Information Services
|
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 initiating a payment through Fintecture, we give you full control and visibility on your payment, while abstracting 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, Pending or Unsuccessful following the approval of the payer. While most payments will be Created, exceptionally some might end up as Pending. Both Created and Pending payments are irrevocable and the funds are reserved in the bank account of the payer.
For scheduled payments, Pending status is expected unil the execution date is reach where the payment should change to either Created or Unsuccessful.
When a payment session is either Created or Pending, the payment has successfully been created by the bank as the payer has authenticated and accepted the payment request. At this point you can already show a payment success page to the payer. However, you may prefer to wait until the settlement has been completed before fulfilling the order.
When a payment session is Unsuccessful, the payment was cancelled by the payer or rejected by the bank. An indicative reason is provided in the transfer_reason field.
| Status | Description |
|---|---|
payment_created |
The payment has been successfully created |
payment_pending |
The payment is currently pending or in the process of being created |
payment_unsuccessful |
The payment was rejected by either the payer or the bank |
payment_error |
The payment has failed for technical reasons |
sca_required |
The payer got redirected to his bank and needs to authenticate |
provider_required |
The payment has been prepared |
payment_waiting |
The request to pay has been generated and is waiting for payer |
In terms of transfer processing, state values can be classified by phase - Intermediate or Final.
| State | Description | Phase |
|---|---|---|
completed |
The payment settlement is completed | Final |
sent |
The payment is being processed and the bank does not return settlement information | Final |
processing |
The payment is being processed | Intermediate |
pending |
The payment is pending for execution (in the case of deferred payments) | Intermediate |
authorized |
The payer has authorized the payment | Intermediate |
accepted |
The payment was accepted by the bank | Intermediate |
received |
The Payment has been received in the payment account | Final |
rejected |
The payment has been rejected (see reasons in APPENDIX) | Final |
completed and sent which both become Intermediate states
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.
Guides
Payment Initiation
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" : "payments",
"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 defaultallis 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 useful 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 |
query | optional | optional | Redirect URL as configured in the console |
state |
query | required | required | A state parameter which will be provided back on redirection |
access_token |
header | required | required | The access_token received in Step 1 (or a newly generated one) |
signature |
header | optional | required | The HTTP Signature header is build according to the draft cavage http signature 10 |
date |
header | optional | required | A RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) |
x-request-id |
header | optional | required | a UUIDv4 ID. Must be different for each request (e.g. 2219654c-981a-4506-9686-5a3fa341c0a7) |
The response of a successful request is the Connect URL and the corresponding payment session_id which will enable you to follow the transaction using the /payments/[session_id] API
After redirecting the PSU to the Connect URL, they will be able to select their bank and initiate the payment from their bank's portal. Following the payment initiation, they will be redirected back to your redirect_uri with the following query string parameters:
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",
"type": "payments"
},
"data": {
"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"
}
}
}
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, retrieve 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="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. The 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.
Refunds
Trigger a refund of a previously collected Fintecture payment back to the PSU's bank account. Only completed payments can be refunded.
By default, a refund will initiate a PIS payment from your bank account directly to the bank account of the PSU. This requires an SCA to be done with your bank account for each refund. Alternatively, refunds can be done from an internal payment account which reduces the friction from SCA and enable mass-refunds to help with your daily operations. Internal payment accounts can be created directly from the Console.
Partial refunds are enabled by overriding the refund amount attribute. It is also possible to change the communication field by overriding the communication attribute.
Multi-refunds are possible by triggering several times the refund API. Each call will trigger a new refund session until the total refund amount exceeds the original amount at which point the API will return an error. Cancelled refunds are not considered in the total refund amount.
The following steps will guide you through completing a PIS refund:
- Access Token: The first step is to request a PIS access token
- Trigger Refund: Then the refund can be triggered by providing the session_id of the original payment
- Get Refund Status: Retrieve the status of the refund
- Receive Refund Webhook: Listen to the refund related webhooks
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: Trigger Refund
Step 2: Request
POST /pis/v2/refund 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": {
"session_id" : "fc8583ae532346d1b7c5ed1c2853d497",
"method": "email"
},
"data": {
"attributes" : {
"amount" : "10.00",
"communication" : "REFUND ORDER-6543321"
}
}
}
Step 2: Response
HTTP/1.1 200 OK
{
"meta": {
"code": 201,
"status": "refund_initiated",
"message": "Refund initiated successfully.",
"session_id": "a4e767db61c346798bb560d11d6092ab",
"refunded_session_id": "fc8583ae532346d1b7c5ed1c2853d497",
"method": "email"
},
"data": {
"id": "a4e767db61c346798bb560d11d6092ab",
"type": "payments",
"attributes": {
"amount": "10.00",
"currency": "EUR",
"communication": "REFUND ORDER-6543321"
}
}
}
The second step is to trigger the refund by posting a request including the original payment session_id. By default, the amount and communication field of the original payment is used but these can be overridden with respect that the amount must be smaller or equal than the original payment.
Notice the method field indicates the way your will receive the refund link to start the authentication flow. The supported methods are:
- email: (default) an email is sent with the refund link. This method is useful to easily share the link to the relevant person which can do an SCA on the bank account. The email used can be changed in the Console settings.
- link: a link is returned with the refund link.
For more information on each field, see the /refund API
- Method:
POST - API: /pis/v2/refund
| parameter | type | description | ||
|---|---|---|---|---|
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) |
session_id |
body | required | required | the payment session ID. |
amount |
body | optional | optional | the amount to refund. By default de original payment amount is used. |
communication |
body | optional | optional | the communication label of the transfer. By default de original payment communication is used. |
Step 3: Get Refund Status
Step 3: 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: Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"session_id": "a4e767db61c346798bb560d11d6092ab",
"refunded_session_id": "fc8583ae532346d1b7c5ed1c2853d497",
"status": "provider_required"
},
"data": {
"id": "a4e767db61c346798bb560d11d6092ab",
"type": "payments",
"attributes": {
"amount": "10.0",
"currency": "EUR",
"communication": "REFUND ORDER-6543321",
"beneficiary": {
"name": "Mr PSU",
"street": "Another Street",
"number": "11",
"zip": "74001",
"city": "Paris",
"country": "FR",
"iban": "FR1420041010050500013M02606",
"swift_bic": "BANKFRPPXXX"
},
"end_to_end_id": "a4e767db61c346798bb560d11d6092ab"
}
}
}
The refund status is returned by calling the usual GET /payments/[session_id] endpoint similarly to PIS payments. The [session_id] of the refund was returned along with the response payload from step 2 in the field $.meta.session_id.
- Method:
GET - API: /pis/v2/payments/[session_id]
| parameter | type | description | ||
|---|---|---|---|---|
session_id |
url | required | required | the refund 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 4: Receive Refund Webhooks
Step 4: Request
POST /webhook HTTP/1.1
Host: mywebsite.com
Signature: keyId="2dfdcf57-5b2f-4309-846f-913d0b2802cf",algorithm="rsa-sha256",headers="date digest x-request-id",signature="h0V0SUbjRhLEP/MiYo0Mgs1N17EuCEmKyQrDjxysc7iSiFXTjvY6qVEoaiRkzB8ZI0J39gGwOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fSTQ2/BSZWx04CjbPv/XUVusnkKVr3W6p+Vn073hAuJn1nKCvDOyl+QnDtstkzT+UacVzDA9L9nyPbbaPQHJobaZuG8TjhnI+Y0PZxneke6OU6fcdPT0uwkEamDOOExcMryHIX1iH5iiPMvLoVA8acqvvMSDYar0rlEQ2J1M4dcowWT8FxLo6C8uqvJIaBYm7Ze0RNJOwY0UBImCVDIuQLJuBjPwjQT5GjTQlg==
Digest: SHA-256=wOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fS
Date: Mon, 08 Jun 2020 23:11:23 GMT
X-Request-ID: 88c414df-6895-48db-8ef3-1fd1ce4272c6
Content-Type: application/x-www-form-urlencoded
session_id=a4e767db61c346798bb560d11d6092ab&status=payment_created&customer_id=1ef74051a77673de120820fb370dc382&provider=provider&state=thisisastate
In the context of a refund, you will receive a webhook once the refund reaches a certain status similar to a normal PIS payment.
You can add webhooks to your application using the Console. The 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.
Account Information
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_idand 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_tokenstate: 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. These 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. |
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 or 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
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-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": "0cf2ebf7e73c8144d51e60aea454add9",
"provider": "cmcifrpp",
"last_authentication": "2021-07-14T08:43:01.876Z",
"remaining_days": 89
},
"data": [
{
"id": "b71722204d1a3f5ecd895",
"type": "accounts",
"attributes": {
"iban": "ES9401824000680201862164",
"balance": 1.19,
"account_name": "Euro Account",
"account_id": "ES0182002000000000000000000042075349XXXXXXXXX",
"account_type": "CHECKING",
"currency": "EUR",
"product": "BBVA CHECKING ACCOUNT"
},
"relationships": {
"transactions": {
"links": {
"related": "https://api.fintecture.com/ais/v1/customer/a8dd747459a761f/accounts/b71722204d1a3f5ecd895/transactions"
}
}
}
},
{
"id": "e8993e4e7027bb600",
"type": "accounts",
"attributes": {
"iban": "ES3801824000690201882814",
"balance": 0.64,
"account_id": "ES0182002000000000500000000315017926XXXXXXXXX",
"account_type": "CHECKING",
"currency": "EUR",
"product": "BBVA CHECKING ACCOUNT"
},
"relationships": {
"transactions": {
"links": {
"related": "https://api.fintecture.com/ais/v1/customer/a8dd747459a761f/accounts/e8993e4e7027bb600/transactions"
}
}
}
}
]
}
This endpoint returns all information regarding the customer's account
Compliance Level
Authentication Level
authorization_code
HTTP Request
GET https://api.fintecture.com/ais/v1/customer/[customer_id]/accounts/[account_id]
Header Parameters
| Parameter | Value | Usage |
|---|---|---|
Authorization |
Bearer [access_token] |
required |
Signature |
see APPENDIX - signed headers: "(request-target) date x-request-id" | required |
Date |
RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) | required |
x-request-id |
UUID v4 | required |
Accept |
application/json | required |
URL Parameters
| Parameter | Description | Type | Usage |
|---|---|---|---|
customer_id |
the customer id of the requested account holder's personal information | string | required |
account_id |
the account id of the requested account information. If no account id is provider, all accounts are returned | string | optional |
Query Parameters
| Parameter | Description | Type | Usage |
|---|---|---|---|
remove_nulls |
remove all fields with null value (default true) | boolean | optional |
with_balances |
returns the accounts balances (default true) | boolean | optional |
GET /transactions
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"customer_id": "0cf2ebf7e73c8144d51e60aea454add9",
"provider": "cmcifrpp",
"last_authentication": "2021-07-14T08:43:01.876Z",
"remaining_days": 89
},
"data": [
{
"id": "1c09eb2ebb41dc72b70ad",
"type": "transactions",
"attributes": {
"transaction_id": "RB-4567813",
"booking_date": "2017-01-31T00:00:00.000+01",
"value_date": "2017-01-31T00:00:00.000+01",
"amount": 10000,
"currency": "CZK",
"communication": "Domácí platba - S24/IB,záloha plyn Bohemia Energy",
"counterparty": {
"name": "Spokojený Jiří",
"account_id": "CZ0827000000002108589434"
},
"transaction_type": "DBIT",
"status": "BOOK",
"debit_credit": "DEBIT"
}
},
{
"id": "31f48d3ae770630348",
"type": "transactions",
"attributes": {
"transaction_id": "FP-4156489123",
"booking_date": "2017-01-31T00:00:00.000+01",
"value_date": "2017-01-31T00:00:00.000+01",
"amount": 2328262,
"currency": "CZK",
"communication": "8201701069595 BIC: GIBACZPXXXX; #71A# SHA ZALOHA DLE SMLOUVY O DODAVKACH,zaloha dle smlouvy o dodavkach c. 45678/2017,VS0250117002/SS0000000000/KS0000SEPA poevod",
"counterparty": {
"name": "RENWORTH s.r.o",
"account_id": "CZ1308001800640033122856"
},
"transaction_type": "CRDT",
"foreign_currency": "EUR",
"foreign_amount": 86200,
"status": "BOOK",
"debit_credit": "DEBIT"
}
}
],
"links": {
"next": "https://api.fintecture.com/ais/v1/customer/0cf2ebf7e73c8144d51e60aea454add9/accounts/b71722204d1a3f5ecd895/transactions?page[number]=2",
"self": "https://api.fintecture.com/ais/v1/customer/0cf2ebf7e73c8144d51e60aea454add9/accounts/b71722204d1a3f5ecd895/transactions?page[number]=1"
}
}
This endpoint lists all transactions on the given account
Compliance Level
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": "8562e79aa2256c275b96ef3304e936e7",
"provider": "cmcifrpp",
"last_authentication": "2021-07-14T08:43:01.876Z",
"remaining_days": 89
},
"data": [
{
"id": "1593ca222ce8bf015",
"type": "accountholders",
"attributes": {
"full_name": "Mr John Smith"
}
}
]
}
This endpoint retrieves all personal information of the client such as name, address and contact details for all the beneficiary owners.
Compliance Level
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]
Accept: application/json
Content-Type: application/json
{
"meta": {
"psu_name" : "Bob McCheese",
"psu_company": "McCheese SA",
"psu_incorporation": "FR123123123",
"psu_form": "SA",
"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" : "connect",
"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
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-country |
2 letter country - ex: fr | optional |
x-language |
2 letter language code - ex: fr | optional |
x-provider |
[provider_id] | optional |
Query Parameters
| Parameter | Description | Usage |
|---|---|---|
redirect_uri |
must correspond to one of the URLs provided when creating an application on 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 |
with_beneficiary |
Returns the beneficiary in the response | optional |
with_virtualbeneficiary |
Returns the virtual beneficiary in the response. Requires internal payment account to be enabled | optional |
state |
A state parameter which will be provided back on redirection | Required |
Body Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
$.data |
object | Object containing all payment related data | Required |
data.type |
string(50) | Name of the resource | Required |
data.attributes |
object | Object containing all attributes of the payment | Required |
attributes.amount |
string(20) | The requested amount to be transferred | Required |
attributes.currency |
string(3) | The currency of the transferred amount (EUR, GBP) | Required |
attributes.communication |
string(140) | Communication label of the transaction, as seen on a bank statement | Required |
attributes.execution_date |
string(10) | The execution date YYYY-MM-DD of the payment order. If no date is specified, the execution is considered as immediate | optional |
attributes.beneficiary |
object | Object containing all beneficiary information | Conditional |
beneficiary.name |
string(50) | the name of the beneficiary | Required |
beneficiary.iban |
string(34) | the IBAN of the beneficiary | Required |
beneficiary.swift_bic |
string(11) | the swift/bic of the beneficiary's bank | Required |
beneficiary.street |
string(50) | the street name from the beneficiary's address | Required |
beneficiary.number |
string(50) | the street number from the beneficiary's address | optional |
beneficiary.complement |
string(50) | extra information regarding the beneficiary's address | optional |
beneficiary.city |
string(50) | the city from the beneficiary's address | Required |
beneficiary.zip |
string(50) | the zip code from the beneficiary's address | Required |
beneficiary.country |
string(2) | the country from the beneficiary's address | Required |
beneficiary.form |
string(50) | The incorporation form of the beneficiary (only legal persons ex: SARL) | Conditional |
beneficiary.incorporation |
string(50) | The incorporation number of the beneficiary | Conditional |
attributes.debited_account_id |
string(50) | Predefine the account which which the payment will be done | optional |
attributes.debited_account_type |
string(8) | "internal" or "iban", "bban". | optional |
attributes.end_to_end_id |
string(35) | A unique ID given by the creator of the payment and send to the bank. By default de session_id is used. | optional |
attributes.scheme |
string(12) | the payment scheme to use. Default: AUTO (automatic selection), SEPA, INSTANT_SEPA | optional |
$.meta |
object | Object containing all metadata in order to successfully operate a compliant payment | Required |
meta.psu_name |
string(50) | The full name of the PSU | Required |
meta.psu_email |
string(50) | The email of the PSU | Required |
meta.psu_phone |
string(20) | The phone number of the PSU | optional |
meta.psu_phone_prefix |
string(5) | The phone prefix of the PSU (ex: 0033) | optional |
meta.psu_company |
string(50) | The company name of the PSU | Conditional |
meta.psu_form |
string(50) | The incorporation form of the PSU | Conditional |
meta.psu_incorporation |
string(50) | The incorporation number of the PSU | Conditional |
meta.psu_address |
object | Object containing the address of the PSU | optional |
psu_address.street |
string(50) | The street of the PSU | Required |
psu_address.number |
string(50) | The street number of the PSU | optional |
psu_address.complement |
string(50) | The address complement of the PSU | optional |
psu_address.city |
string(50) | The city of the PSU | Required |
psu_address.zip |
string(50) | The ZIP code of the PSU | Required |
psu_address.country |
string(2) | The 2 letter country of the PSU | Required |
meta.expiry |
number | The time in seconds which the link is valid before it expires (default: no expiry) | optional |
meta.custom |
JSON or string(1000) | A custom UTF8 message which can be included for reconciliation purposes | optional |
meta.reconciliation |
object | Object containing the reconciliation settings for bank transfers | optional |
reconciliation.level |
string(20) | The seed to generate a virtual iban. Acceptable values are "payer" or "payment_session". Default "payer" | optional |
reconciliation.match_amount |
boolean | Only reconcile the payment session if the received amount is a match. Default true | optional |
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_company": "McCheese SA",
"psu_incorporation": "FR123123123",
"psu_form": "SA",
"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" : "payments",
"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",
"code": 200,
"provider": "bankfr",
"customer_id": "xcgf54zji904c3t89zu4rt2c98z042r5cd0",
"session_id": "e07335fdeb073e0ebab13ba0bd71ad3c",
"url": "https://sandbox.auth.somebank.com/authorize?response_type=code&client_id=..."
},
"data": {
"type" : "payments",
"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"
}
}
}
Compliance Level
Authentication Level
client_credentials
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 | Type | Description | Usage |
|---|---|---|---|
$.data |
object | Object containing all payment related data | Required |
data.type |
string(50) | Name of the resource | Required |
data.attributes |
object | Object containing all attributes of the payment | Required |
attributes.amount |
string(50) | The requested amount to be transferred | Required |
attributes.currency |
string(3) | The currency of the transferred amount (EUR, GBP) | Required |
attributes.communication |
string(140) | Communication label of the transaction, as seen on a bank statement | Required |
attributes.execution_date |
string(10) | The execution date YYYY-MM-DD of the payment order. If no date is specified, the execution is considered as immediate | optional |
attributes.beneficiary |
object | Object containing all beneficiary information | Conditional |
beneficiary.name |
string(50) | the name of the beneficiary | Required |
beneficiary.iban |
string(34) | the IBAN of the beneficiary | Required |
beneficiary.swift_bic |
string(11) | the swift/bic of the beneficiary's bank | Required |
beneficiary.street |
string(50) | the street name from the beneficiary's address | Required |
beneficiary.number |
string(50) | the street number from the beneficiary's address | optional |
beneficiary.complement |
string(50) | extra information regarding the beneficiary's address | optional |
beneficiary.city |
string(50) | the city from the beneficiary's address | Required |
beneficiary.zip |
string(50) | the zip code from the beneficiary's address | Required |
beneficiary.country |
string(2) | the country from the beneficiary's address | Required |
beneficiary.form |
string(50) | The incorporation form of the beneficiary (only legal persons ex: SARL) | Conditional |
beneficiary.incorporation |
string(50) | The incorporation number of the beneficiary | Conditional |
attributes.debited_account_id |
string(50) | Predefine the account which which the payment will be done | optional |
attributes.debited_account_type |
string(8) | "internal" or "iban", "bban". | optional |
attributes.end_to_end_id |
string(35) | A unique ID given by the creator of the payment and send to the bank. By default de session_id is used. | optional |
attributes.scheme |
string(12) | the payment scheme to use. Default: AUTO (automatic selection), SEPA, INSTANT_SEPA | optional |
$.meta |
object | Object containing all metadata in order to successfully operate a compliant payment | Required |
meta.psu_name |
string(50) | The full name of the PSU | Required |
meta.psu_email |
string(50) | The email of the PSU | Required |
meta.psu_phone |
string(20) | The phone number of the PSU | optional |
meta.psu_phone_prefix |
string(5) | The phone prefix of the PSU (ex: 0033) | optional |
meta.psu_company |
string(50) | The company name of the PSU | Conditional |
meta.psu_form |
string(50) | The incorporation form of the PSU | Conditional |
meta.psu_incorporation |
string(50) | The incorporation number of the PSU | Conditional |
meta.psu_address |
object | Object containing the address of the PSU | optional |
psu_address.street |
string(50) | The street of the PSU | Required |
psu_address.number |
string(50) | The street number of the PSU | optional |
psu_address.complement |
string(50) | The address complement of the PSU | optional |
psu_address.city |
string(50) | The city of the PSU | Required |
psu_address.zip |
string(50) | The ZIP code of the PSU | Required |
psu_address.country |
string(2) | The 2 letter country of the PSU | Required |
meta.custom |
JSON or string(1000) | a custom UTF8 message which can be included for reconciliation purposes | optional |
Return Values
The payments API endpoint will return a payment session status and a payment transfer state which defines the next step to be taken in order to complete the payment initiation cycle.
The possible return values are defined in the following table:
| Status | Description |
|---|---|
payment_created |
The provider has successfully initiated the payment |
payment_pending |
The provider is processing the payment |
payment_unsuccessful |
The provider rejected the payment |
payment_error |
The payment has failed for technical reasons |
sca_required |
The PSU got redirected to his bank and needs to authenticate |
provider_required |
The payment has been prepared |
payment_waiting |
The request to pay has been generated and is waiting for payer |
| State | Description |
|---|---|
completed |
The payment settlement is completed |
processing |
The payment is being processed |
pending |
The payment is pending for execution (in the case of deferred payments) |
rejected |
The payment has been rejected (see reasons in APPENDIX) |
authorized |
The PSU has authorized the payment |
accepted |
The payment was accepted by the provider |
POST /refund
Request Body
{
"meta": {
"session_id": "44f00841780445d4981be9ea2f8aafae"
},
"data": {
"attributes": {
"amount": "15.2",
"communication": "REFUND ORDER-123"
}
}
}
Response 201
HTTP/1.1 201 Created
Content-Type: application/json
{
"meta": {
"code": 201,
"status": "refund_initiated",
"message": "Refund initiated successfully.",
"session_id": "44f00841780445d4981be9ea2f8aafae"
}
}
Compliance Level
Authentication Level
client_credentials
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 |
|---|---|---|
state |
State parameter is a free string that will be sent to weebhooks when the status of the session changes. This can be useful to identify the refund session. | optional |
-
Body Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
$.meta |
object | Object containing all metadata related to the refund | Required |
meta.session_id |
string(35) | Payment session ID | Required |
meta.user_id |
string(36) | Only for payment accounts. The user_id of an user with access to the payment account | optional |
$.data |
object | Object containing all data for the refund | Required |
data.attributes |
object | Object containing all attributes of the refund | Required |
attributes.amount |
string(50) | The amount in case of partial refund. By default, the full amount of the original payment is used. | optional |
attributes.communication |
string(140) | The communication to use for the refund payment. By default it will append "REFUND" to the original communication. | optional |
attributes.debtor |
object | Object containing the attributes related to the debtor account to be used if different from the original payment beneficiary account | optional |
debtor.bank_account_id |
string(50) | The payout account to be used if different from the original payment beneficiary account. | optional |
Returned Values
The refund API endpoint triggers a refund session with a new session_id. This session_id can be followed using the /payments API and the payment status are to be considered to follow the state of refund.
The original payment also keeps track of the underlying refund status'. That particular status is returned in response of the API call and 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_partial |
The partial refund is successfully completed |
refund_created |
The refund is successfully completed |
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": "FR"
},
"expiry": 86400,
"due_date": 76400,
"cc": "xxx@xxx.xxx",
"bcc": "xxx@xxx.xxx"
},
"data": {
"type": "request-to-pay",
"attributes": {
"amount": "100",
"currency": "EUR",
"communication": "#ref",
"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 201 Created
Content-Type: application/json
{
"meta": {
"status": "request_to_pay_initiated",
"code": 201,
"message": "Request to pay initiated successfully.",
"session_id": "44f00841780445d4981be9ea2f8aafae"
}
}
Compliance Level
Authentication Level
client_credentials
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-country |
2 letter country - ex: fr | optional |
x-provider |
[provider_id] | optional |
x-language |
2 letter language code - ex: fr | Required |
Accept |
application/json | Required |
Content-Type |
application/json | Required |
Query Parameters
| Parameter | Description | Usage |
|---|---|---|
redirect_uri |
must correspond to one of the URLs provided when creating an application on the console | Optional |
with_virtualbeneficiary |
Returns the virtual beneficiary in the response. Requires internal payment account to be enabled | optional |
Body Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
$.data |
object | Object containing all payment related data | Required |
data.type |
string(50) | Name of the resource | Required |
data.attributes |
object | Object containing all attributes of the payment | Required |
attributes.amount |
string(50) | The requested amount to be payed | Required |
attributes.currency |
string(3) | The currency of the payed amount (ISO 4217) | Required |
attributes.communication |
string(255) | The communication of the payment | Optional |
attributes.beneficiary |
object | Object containing all beneficiary information | Conditional |
beneficiary.name |
string(50) | the name of the beneficiary | Required |
beneficiary.iban |
string(34) | the IBAN of the beneficiary | Required |
beneficiary.swift_bic |
string(11) | the swift/bic of the beneficiary's bank | Required |
beneficiary.street |
string(50) | the street name from the beneficiary's address | Required |
beneficiary.number |
string(50) | the street number from the beneficiary's address | optional |
beneficiary.complement |
string(50) | extra information regarding the beneficiary's address | optional |
beneficiary.city |
string(50) | the city from the beneficiary's address | Required |
beneficiary.zip |
string(50) | the zip code from the beneficiary's address | Required |
beneficiary.country |
string(2) | the country from the beneficiary's address | Required |
$.meta |
object | Object containing all metadata in order to successfully operate a compliant payment | Required |
meta.psu_name |
string(255) | The name of the PSU | Conditional |
meta.psu_email |
string(255) | The email of the PSU | Conditional |
meta.psu_phone |
string(20) | The number of the PSU | Conditional |
meta.psu_phone_prefix |
string(4) | The indice number of the PSU | Conditional |
meta.psu_company |
string(50) | The company name of the PSU | Conditional |
meta.psu_form |
string(50) | The incorporation form of the PSU | Conditional |
meta.psu_incorporation |
string(50) | The incorporation number of the PSU | Conditional |
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) | The country of the PSU (ISO 3166-1) | Optional |
meta.expiry |
int(8) | The number of seconds of the validity of the request to pay, by default 86400 | Optional |
meta.due_date |
int(8) | The number of seconds of the due date of the request to pay. Conditional |
Optional |
meta.cc |
string(255) | The CC email to receive a copy (If multiple emails, the emails must be concatenated with a comma.) | Optional |
meta.bcc |
string(255) | The BCC email to receive a copy (If multiple emails, the emails must be concatenated with a comma.) | Optional |
meta.method |
'email','link','sms' | email/link/sms method type for notifiying PSU (default: link) | Optional |
meta.custom |
JSON or string(1000) | a custom UTF8 message which can be included for reconciliation purposes | Optional |
meta.permanent |
boolean | To indicate this is a template payment | Optional |
meta.reconciliation |
object | Object containing the reconciliation settings for bank transfers | optional |
reconciliation.level |
string(20) | The seed to generate a virtual iban. Acceptable values are "payer" or "payment_session". Default "payer" | optional |
reconciliation.match_amount |
boolean | Only reconcile the payment session if the received amount is a match. Default true | 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 |
POST /request-for-payout
Request Body
{
"meta": {
"psu_name": "Jean",
"psu_email": "xxx@xxx.xxx",
"psu_phone": "601020304",
"psu_phone_prefix": "+33",
"psu_address": {
"street_number": "5",
"street": "Parvis Alan Turing",
"zipcode": "75013",
"city": "Paris",
"country": "FR"
},
"expiry": 86400,
"method": "link"
},
"data": {
"attributes": {
"amount": "100.23",
"currency": "EUR",
"communication": "Refund ORDER-123"
}
}
}
Response 201
HTTP/1.1 201 Created
Content-Type: application/json
{
"meta": {
"code": 201,
"session_id": "d62ac07d90fc48dc954c7edb2d85b962",
"method": "link",
"url": "http://connect.fintecture.com/v2/b22074e7-3776-41c9-acb5-bca2e9531aa4"
}
}
Compliance Level
Authentication Level
client_credentials
HTTP Request
POST https://api.fintecture.com/pis/v2/request-for-payout
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-country |
2 letter country - ex: fr | optional |
Accept |
application/json | Required |
Content-Type |
application/json | Required |
Query Parameters
| Parameter | Value | Usage |
|---|---|---|
redirect_uri |
the uri which will be redirected the payoutee at the end of the payout process | optional |
state |
A state parameter which will be provided back on redirection | optional |
Body Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
$.data |
object | Object containing all payment related data | Required |
data.type |
string(50) | Name of the resource | Required |
data.attributes |
object | Object containing all attributes of the payment | Required |
attributes.amount |
string(50) | The requested amount to be payed | Required |
attributes.currency |
string(3) | The currency of the payed amount (ISO 4217) | Required |
attributes.communication |
string(255) | The communication of the payment | Optional |
$.meta |
object | Object containing all metadata in order to successfully operate a compliant payment | Required |
meta.psu_name |
string(255) | The name of the PSU | Conditional |
meta.psu_email |
string(255) | The email of the PSU | Conditional |
meta.psu_phone |
string(20) | The number of the PSU | Optional |
meta.psu_phone_prefix |
string(4) | The indice number of the PSU | Optional |
meta.psu_company |
string(50) | The company name of the PSU | Conditional |
meta.psu_form |
string(50) | The incorporation form of the PSU | Conditional |
meta.psu_incorporation |
string(50) | The incorporation number of the PSU | Conditional |
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) | The country of the PSU (ISO 3166-1) | Optional |
meta.method |
'email','link' | email/link method type for notifiying PSU (default: link) | Optional |
meta.custom |
JSON or string(1000) | a custom UTF8 message which can be included for reconciliation purposes | Optional |
meta.expiry |
number | The time in seconds which the link is valid before it expires (default: no expiry) | Optional |
Returned Values
The request for payout API endpoint triggers a request for payout.
The possible return values are defined in the following table:
| Code | Description |
|---|---|
| 201 | The request for payout has been successfully initiated by us |
| 500 | The request for payout initiation has been unsuccessful |
GET /payments
Request
GET pis/v2/payments HTTP/1.1
Authorization: Bearer [access_token]
Signature: [signature]
Date: [date]
x-request-id: [request_id]
Accept: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": "ecec9f13407f4c2cb5f1591255e8f815",
"type": "payments",
"meta": {
"session_id": "ecec9f13407f4c2cb5f1591255e8f815",
"status": "payment_unsuccessful",
"provider": "bnpafr"
},
"attributes": {
"amount": "150.30",
"currency": "EUR",
"beneficiary": {
"zip": "12001",
"city": "Paris",
"iban": "FR1420041010050500013M02606",
"name": "Dummy SA",
"number": "23",
"street": "dummy street",
"country": "FR",
"bank_name": "BNP-PARIBAS SA",
"swift_bic": "BNPAFRPPXXX"
},
"communication": "AB784159624_ABC",
"execution_date": "2021-07-15",
"end_to_end_id": "ecec9f13407f4c2cb5f1591255e8f815",
"transfer_state": "rejected",
"transfer_reason": "blocked_account"
}
},
{
"id": "f7a35d376fd54c9385ad2cac1b159732",
"type": "payments",
"meta": {
"session_id": "f7a35d376fd54c9385ad2cac1b159732",
"status": "payment_created",
"provider": "bnpafr"
},
"attributes": {
"amount": "150.30",
"currency": "EUR",
"beneficiary": {
"zip": "12001",
"city": "Paris",
"iban": "FR1420041010050500013M02606",
"name": "Dummy SA",
"number": "23",
"street": "dummy street",
"country": "FR",
"bank_name": "BNP-PARIBAS SA",
"swift_bic": "BNPAFRPPXXX"
},
"communication": "AB784159623_XYZ",
"execution_date": "2021-07-15",
"end_to_end_id": "f7a35d376fd54c9385ad2cac1b159732",
"transfer_state": "completed"
}
}
]
}
This endpoint returns the details of all transfers or of a specific transfer
Compliance Level
Authentication Level
client_credentials
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 |
|---|---|---|
filter[start_date] |
search payments as of date the payment was initiated | Optional |
filter[end_date] |
search payments up to date the payment was initiated | Optional |
filter[reference] |
search a payment matching a reference in the communication field | Optional |
Returned Values
The payments API endpoint will return a payment session status and a payment transfer state which defines the next step to be taken in order to complete the payment initiation cycle.
The possible return values are defined in the following table:
| Status | Description |
|---|---|
payment_created |
The provider has successfully initiated the payment |
payment_pending |
The provider is processing the payment |
payment_unsuccessful |
The provider rejected the payment |
payment_error |
The payment has failed for technical reasons |
sca_required |
The PSU got redirected to his bank and needs to authenticate |
provider_required |
The payment has been prepared |
payment_waiting |
The request to pay has been generated and is waiting for payer |
| State | Description |
|---|---|
completed |
The payment settlement is completed |
processing |
The payment is being processed |
pending |
The payment is pending for execution (in the case of deferred payments) |
rejected |
The payment has been rejected (see reasons in APPENDIX) |
authorized |
The PSU has authorized the payment |
accepted |
The payment was accepted by the provider |
GET /payments/[session_id]
Request
GET pis/v2/payments/[session_id] HTTP/1.1
Authorization: Bearer [access_token]
Signature: [signature]
Date: [date]
x-request-id: [request_id]
Accept: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"session_id": "44f00841780445d4981be9ea2f8aafae",
"status": "payment_unsuccessful",
"provider": "bnpafr",
"type": "payments"
},
"data": {
"attributes": {
"amount": "42.05",
"received_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"
}
}
}
This endpoint returns the details of all transfers or of a specific transfer
Compliance Level
Authentication Level
client_credentials
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 |
Query Parameters
| Parameter | Description | Usage |
|---|---|---|
with_beneficiary |
Returns the beneficiary in the request | optional |
with_virtualbeneficiary |
Returns the virtual beneficiary in the request. Requires bank transfer method to be enabled | optional |
Returned Values
The payments API endpoint will return a payment session status and a payment transfer state which defines the next step to be taken in order to complete the payment initiation cycle.
The possible return values are defined in the following table:
| Status | Description |
|---|---|
payment_created |
The provider has successfully initiated the payment |
payment_pending |
The provider is processing the payment |
payment_unsuccessful |
The provider rejected the payment |
payment_error |
The payment has failed for technical reasons |
sca_required |
The PSU got redirected to his bank and needs to authenticate |
provider_required |
The payment has been prepared |
payment_waiting |
The request to pay has been generated and is waiting for payer |
| State | Description |
|---|---|
completed |
The payment settlement is completed |
sent |
The payment is being processed and the bank does not return settlement information |
rejected |
The payment has been rejected (see reasons in APPENDIX) |
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]/refunds
Request
GET pis/v2/payments/[session_id]/refunds 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": "refunds",
"meta": {
"session_id": "ecec9f13407f4c2cb5f1591255e8f815",
"status": "provider_required"
},
"attributes": {
"amount": "10.00",
"currency": "EUR",
"communication": "REFUND AB784159624_ABC",
"beneficiary": {
"name": "Bob Smith"
}
}
},
{
"id": "f7a35d376fd54c9385ad2cac1b159732",
"type": "refunds",
"meta": {
"session_id": "f7a35d376fd54c9385ad2cac1b159732",
"status": "payment_created",
"provider": "bnpafr"
},
"attributes": {
"amount": "150.30",
"currency": "EUR",
"communication": "REFUND AB784159623_XYZ",
"beneficiary": {
"name": "George Dupont"
},
"execution_date": "2021-07-15",
"end_to_end_id": "f7a35d376fd54c9385ad2cac1b159732",
"transfer_state": "completed"
}
}
]
}
This endpoint returns all refunds associated to a payment
Compliance Level
Authentication Level
client_credentials
HTTP Request
GET https://api.fintecture.com/pis/v2/payments/[session_id]/refunds
Header Parameters
| Parameter | Value | Usage |
|---|---|---|
Authorization |
Bearer [access_token] |
Required |
Signature |
see APPENDIX - signed headers: "(request-target) date x-request-id" | Required |
Date |
RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) | Required |
x-request-id |
UUID v4 | Required |
Accept |
application/json | Required |
URL Parameters
| Parameter | Description | Usage |
|---|---|---|
| - | - | - |
Returned Values
The payments API endpoint will return a payment session status and a payment transfer state which defines the next step to be taken in order to complete the payment initiation cycle.
The possible return values are defined in the following table:
| Status | Description |
|---|---|
payment_created |
The provider has successfully initiated the payment |
payment_pending |
The provider is processing the payment |
payment_unsuccessful |
The provider rejected the payment |
payment_error |
The payment has failed for technical reasons |
sca_required |
The PSU got redirected to his bank and needs to authenticate |
provider_required |
The payment has been prepared |
payment_waiting |
The request to pay has been generated and is waiting for payer |
| State | Description |
|---|---|
completed |
The payment settlement is completed |
processing |
The payment is being processed |
pending |
The payment is pending for execution (in the case of deferred payments) |
rejected |
The payment has been rejected (see reasons in APPENDIX) |
authorized |
The PSU has authorized the payment |
accepted |
The payment was accepted by the provider |
PATCH /payments/[session_id]
Request
PATCH pis/v2/payments/[session_id] HTTP/1.1
Authorization: Bearer [access_token]
Signature: [signature]
Date: [date]
x-request-id: [request_id]
Accept: application/json
{
"meta": {
"status": "payment_cancelled",
}
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {
"session_id": "44f00841780445d4981be9ea2f8aafae",
"status": "payment_cancelled"
},
"data": {
"type": "payments",
"attributes": {
"amount": "42.05",
"currency": "EUR",
"communication": "ORDER 123",
"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"
},
"end_to_end_id": "44f00841780445d4981be9ea2f8aafae"
}
}
}
The endpoint enables to change certain attributes of a payment session. Attributes can only be changes if the payment has not been processed.
For example, a payment session can be cancelled by changing the status. Once cancelled, the payer will not be able to pay using this payment session.
Compliance Level
Authentication Level
client_credentials
HTTP Request
PATCH 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 to be patched | Required |
Body Parameters
| Parameter | Type | Description | Usage |
|---|---|---|---|
$.meta |
object | Object containing the metadata related to the payment | Required |
meta.status |
string(35) | only accepts "payment_cancelled" | Required |
Returned Values
This endpoint returns the details of the patched payment session.
GET /settlements
Settlements are outgoing payments from your Local Acquiring account to your own bank account. The settlements API lists all disbursements which occurred from your Local Acquiring account.
Local Acquiring can be enabled in your console.
Request
GET pis/v2/settlements HTTP/1.1
Authorization: Bearer [access_token]
Signature: [signature]
Date: [date]
x-request-id: [request_id]
Accept: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [{
"id": "127335fdeb073e0eb2313ba0bd71ad44",
"type": "settlements",
"attributes": {
"net_amount": "2100.00",
"gross_amount": "7100.00",
"other_maount": "0.00",
"deposit_amount": "5000.00",
"currency": "EUR",
"execution_date": "2021-03-15",
"communication": "SETTLEMENT-11112"
}},{
"id": "964321fdeb073ddeb2313ba876543d43",
"type": "settlements",
"attributes": {
"net_amount": "1323.10",
"gross_amount": "6323.10",
"other_maount": "0.00",
"deposit_amount": "5000.00",
"currency": "EUR",
"execution_date": "2021-02-15",
"communication": "SETTLEMENT-11111"
}
}]
}
Compliance Level
Authentication Level
client_credentials
HTTP Request
GET https://api.fintecture.com/pis/v2/settlements
Header Parameters
| Parameter | Value | Usage |
|---|---|---|
Authorization |
Bearer [access_token] |
Required |
Signature |
see APPENDIX - signed headers: "(request-target) date x-request-id" | Required |
Date |
RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) | Required |
x-request-id |
UUID v4 | Required |
Accept |
application/json | Required |
URL Parameters
| Parameter | Description | Usage |
|---|---|---|
| - | - | - |
Query Parameters
| Parameter | Description | Type | Usage |
|---|---|---|---|
filter[date_to] |
filter settlements by booking date. | yyyy-mm-dd | optional |
filter[date_from] |
filter settlements by booking date. | yyyy-mm-dd | optional |
Returned Values
The settlements API endpoint lists all disbursements which occurred from your Local Acquiring account.
The settlement payload includes 4 payments amounts and correspond to the following definition:
net_amount: The settlement amount which is transfered to your accountgross_amount: The sum of the corresponding payments and refundsother_amount: The sum of the unidentified paymentsdeposit_amount: The residual amount left on the 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": {
"net_amount": "2100.00",
"gross_amount": "7100.00",
"other_maount": "0.00",
"deposit_amount": "5000.00",
"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": "5000.00",
"currency": "EUR",
"execution_date": "2021-02-28",
"communication": "ORDER-123",
}
},
{
"id": "264ccb4adbc25f344f6c678c1e256ac5",
"type": "payments",
"attributes": {
"amount": "2100.00",
"currency": "EUR",
"execution_date": "2021-02-2",
"communication": "ORDER-321",
}
}
]
}
Compliance Level
Authentication Level
client_credentials
HTTP Request
GET https://api.fintecture.com/pis/v2/settlements/[settlement_id]
Header Parameters
| Parameter | Value | Usage |
|---|---|---|
Authorization |
Bearer [access_token] |
Required |
Signature |
see APPENDIX - signed headers: "(request-target) date x-request-id" | Required |
Date |
RFC2822 formatted date (e.g. Thu, 18 Jun 2020 18:14:15 GMT) | Required |
x-request-id |
UUID v4 | Required |
Accept |
application/json | Required |
URL Parameters
| Parameter | Description | Usage |
|---|---|---|
settlement_id |
the settlement ID of the payment, all payments are returned if no settlement ID is specified | optional |
Query Parameters
| Parameter | Description | Type | Usage |
|---|---|---|---|
include |
Add the included object which includes all the details of the payments | payments | optional |
Returned Values
The settlements API endpoint, without specifying a specific settlement ID, will return an array of settlement payments which occurred in your local acquiring bank account. The settlements API endpoint, with a specific settlement ID, will return an object including the details of the settlement. By including the "include" query param, you can return all payment sessions which corresponds to each settlements. The settlement payload includes 4 payments amounts and correspond to the following definition:
net_amount: The settlement amount which is transfered to your accountgross_amount: The sum of the corresponding payments and refundsother_amount: The sum of the unidentified paymentsdeposit_amount: The residual amount left on the account
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 keyId 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 keyId, 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),dateandx-request-id - For POST & PUT requests, use
(request-target),date,digestandx-request-id
(request-target): get /ais/v1/customer/123/accounts?querystring=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:
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 Session Status
The below table shows the different status a payment may have and it's definition.
| Status | Description |
|---|---|
payment_created |
The payment has been successfully created |
payment_pending |
The payment is currently pending or in the process of being created |
payment_unsuccessful |
The payment was rejected by either the payer or the bank |
payment_error |
The payment has failed for technical reasons |
sca_required |
The payer got redirected to his bank and needs to authenticate |
provider_required |
The payment has been prepared |
payment_waiting |
The request to pay has been generated and is waiting for payer |
See Payment Initiation Flow to understand how Status and States represent and what you should consider
Payment Transfer States
The below table shows the different states a transfer may have and it's definition.
| State | Description | Phase |
|---|---|---|
completed |
The payment settlement is completed | Final |
sent |
The payment is being processed and the bank does not return settlement information | Final |
processing |
The payment is being processed | Intermediate |
pending |
The payment is pending for execution (in the case of deferred payments) | Intermediate |
authorized |
The payer has authorized the payment | Intermediate |
accepted |
The payment was accepted by the bank | Intermediate |
received |
The payment has been received in the wallet | Final |
rejected |
The payment has been rejected (see reasons in APPENDIX) | Final |
completed and sent which both become Intermediate states
See Payment Initiation Flow to understand how Status and States represent and what you should consider
Payment Rejected Reason
The below table shows the different payment transfer rejected reasons. The list is not exhaustive:
| Reason | Description |
|---|---|
insufficient_funds |
The PSU has insufficient funds |
incorrect_account_number |
The provided account number is unknown |
closed_account |
The PSU account is closed |
blocked_account |
The PSU account is blocked |
transaction_forbidden |
The transaction is forbidden |
too_many_transactions |
The bulk payment contains too many transactions |
invalid_execution_date |
The execution date is invalid |
customer |
The payment was rejected by the customer |
cancelled |
The payment was cancelled by the customer |
fraudulent_originated |
The payment was rejected as fraud was detected |
no_answer |
The payment was rejected as it expired |
regulatory_reason |
The payment was rejected for regulatory reason |
Webhooks
Step 5: Webhook
POST /webhook HTTP/1.1
Host: mywebsite.com
Signature: keyId="2dfdcf57-5b2f-4309-846f-913d0b2802cf",algorithm="rsa-sha256",headers="date digest x-request-id",signature="h0V0SUbjRhLEP/MiYo0Mgs1N17EuCEmKyQrDjxysc7iSiFXTjvY6qVEoaiRkzB8ZI0J39gGwOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fSTQ2/BSZWx04CjbPv/XUVusnkKVr3W6p+Vn073hAuJn1nKCvDOyl+QnDtstkzT+UacVzDA9L9nyPbbaPQHJobaZuG8TjhnI+Y0PZxneke6OU6fcdPT0uwkEamDOOExcMryHIX1iH5iiPMvLoVA8acqvvMSDYar0rlEQ2J1M4dcowWT8FxLo6C8uqvJIaBYm7Ze0RNJOwY0UBImCVDIuQLJuBjPwjQT5GjTQlg==
Digest: SHA-256=wOtTXN9CJPVRbhEHhi9Z9rQvM33FkygXvvx8BwM76fS
Date: Mon, 08 Jun 2020 23:11:23 GMT
X-Request-ID: 88c414df-6895-48db-8ef3-1fd1ce4272c6
Content-Type: application/x-www-form-urlencoded
session_id=b2bca2bcd3b64a32a7da0766df59a7d2&status=payment_created&customer_id=1ef74051a77673de120820fb370dc382&provider=provider&state=thisisastate
Webhooks enables you to be notified of an event such as a payment status change.
In the context of a payment model based on redirection, it is important to use a redundant payment notification channel in case the redirection fails. Some implementations uses webhooks as the main payment notification channel and the redirection simply displays the resulting payment result.
Webhooks are configured in the Console in your application. Webhooks take 3 parameters:
- 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.
Pagination
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta": {},
"data": [{},{}],
"links": {
"next": "https://api.fintecture.com/ais/v1/.../transactions?page[number]=2",
"self": "https://api.fintecture.com/ais/v1/.../transactions?page[number]=1"
}
}
Several APIs return pagination results. Those APIs are the following
- AIS: GET /transactions
- PIS: GET /payments and GET /settlements
AIS APIs follow the same indexing as provides the banks. Most banks don't support pagination so all the results will be returned as a single page. As the pagination logic is based on what the bank retuns, the control on pagination is limited. The available feature is to be able to navigate throught the using the next, self page links found at the end of the JSON provided the bank paginates the results.
PIS APIs are more flexible as these are provided directly by Fintecture. The following filters are available:
- page[cursor]: the page cursor ID
- page[number]: the page number
- page[size]: the amount of item returned on a page (min: 0, max: 100)
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 possibilities 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, 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 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_id. |
| 401 | unauthorized |
invalid_app_url |
Invalid app redirect URL. |
| 404 | not_found |
not_found |
The requested resource could not be found. The requested resource either does not exist or is temporarily down. |
| 429 | too_many_requests |
too_many_requests |
The user has sent too many requests in a given amount of time. |
| 500 | internal_server_error |
internal_server_error |
An internal error has occurred. If the error persists, please contact our support. |
| 501 | not_implemented |
provider_endpoint_unavailable |
The provider endpoint is currently unavailable or has not been implemented yet. |
| 503 | service_unavailable |
provider_unavailable |
The provider is currently unavailable. Please try again later. |
{
"meta": {
"title": "copyright",
"details": "copyright© 2021 Fintecture. All rights reserved."
}
}
Copyright © 2021 Fintecture. All rights reserved.