Connectors

Connectors represent business institutions that Powens can establish connections with, in order to extract data.

API endpoints

Authentication: endpoints listed in this page do not require authentication.

Connectors

List connectors

GET https://{domain}.biapi.pro/2.0/connectors

List all connectors available on the domain.

This endpoint does not require authentication.

Query Parameters

Name	Type	Description
country_codes	String	Filter on countries, using comma-separated ISO 3166-1 alpha-2 codes.
id_payment	String	Filter on a payment id to get only the connectors compatible with this payment.

200: OK List of connectors

Response body: ConnectorsList object

Deprecated route aliases:

/banks
/providers

Get a connector

GET https://{domain}.biapi.pro/2.0/connectors/{connectorUuid}

Get a single connector by UUID.

This endpoint does not require authentication.

Path Parameters

Name	Type	Description
connectorUuid*	String	UUID of the connector. IDs are also accepted (deprecated).

200: OK Connector

Response body: Connector object

Update a connector

PUT https://{domain}.biapi.pro/2.0/connectors/{connectorUuid}

This endpoint requires header authentication with a config token.

Request body: ConnectorUpdateRequest object

Path Parameters

Name	Type	Description
connectorUuid*	String	UUID of the connector. IDs are also accepted (deprecated).

200: OK Connector updated

Response body: Connector object

Batch enable/disable connectors

PATCH https://{domain}.biapi.pro/2.0/connectors

This endpoint requires header authentication with a config token.

Request body: A key-value object with connector UUIDs as keys, and ConnectorUpdateRequest object as value.

200: OK Connectors updated

Batch enable/disable connectors (deprecated)

PUT https://{domain}.biapi.pro/2.0/connectors/{connectorIds}

This endpoint requires header authentication with a config token.

Request body: ConnectorUpdateRequest object

Path Parameters

Name	Type	Description
connectorIds*	String	Comma-separated list of connector IDs to update.

200: OK Connectors updated

Response body: Connector object

Connector sources

List connector sources

GET https://{domain}.biapi.pro/2.0/connectors/{connectorUuid}/sources

This endpoint does not require authentication.

Path Parameters

Name	Type	Description
connectorUuid*	String	UUID or the related connector.

Query Parameters

Name	Type	Description
country_codes	String	Filter on countries, using comma-separated ISO 3166-1 alpha-2 codes.

200: OK List of connector sources

Response body: ConnectorSourcesList object

Get a connector source

GET https://{domain}.biapi.pro/2.0/connectors/{connectorUuid}/sources/{sourceId}

This endpoint does not require authentication.

Path Parameters

Name	Type	Description
connectorUuid*	String	UUID or the related connector.
sourceId*	Integer	ID of the connector source.

200: OK Connector source details

Response body: ConnectorSource object

Update a connector source

PUT https://{domain}.biapi.pro/2.0/connectors/{connectorUuid}/sources/{sourceId}

This endpoint requires header authentication with a config token.

Request body: ConnectorSourceUpdateRequest object

Path Parameters

Name	Type	Description
connectorUuid*	String	UUID or the related connector.
sourceId*	Integer	ID of the connector source.

200: OK Connector source updated

Response body: ConnectorSource object

Data model

ConnectorsList object

Property	Type	Description
connectors	Array of Connector objects	The list of connectors. The key is absent on deprecated endpoint routes.
banks	Array of Connector objects	(Deprecated) The list of connectors. The key is only present on deprecated endpoint routes.

Connector object

Property	Type	Description
id	Integer	ID of the connector, not stable across API domains.
uuid	String	Unique connector identifier, stable across API domains.
name	String	Name of the bank or provider.
hidden	Boolean or null	Whether this connector is hidden from users.
charged	Boolean	Usage of this connector is charged.
code	String or null	Bank code.
beta	Boolean	If true, this connector is likely unstable.
color	String or null	Branding color of the bank or provider.
slug	String or null	A short letter code to identify the connector. Slugs are not unique.
sync_frequency	Decimal or null	How many days to wait between syncs.
months_to_fetch	Integer or null	Number of months of history to fetch when synchronizing a connection.
auth_mechanism	AuthMechanism string or null	Authentication mechanism to use to add a connection.
available_auth_mechanisms	Array of AuthMechanism strings	The list of available mechanisms to add a connection (internal use only).
transfer_mechanism	AuthMechanism or null	Authentication mechanism to use to validate a transfer.
siret	String	SIRET code, for providers.
restricted	Boolean	If true, new connections cannot be added with this connector.
capabilities	Array of strings	The list of capabilities implemented on the connector. E.g. profile means that the connector is able to return identity information.
account_usages	Array of BankAccountUsage strings	The list of account usages returned by the sources of the connector.
payment_settings	PaymentSettings object	An object providing information about payment feature on this connector. Only present if Pay product is enabled on the connector.
products	Array of Product strings	The list of products implemented on the connector. (e.g. pay means that the connector has Pay product).

Available expands

The following parameters can be used for response properties expansion:

Property	Type	Description
sources	Array of ConnectorSource objects	The details of the sources available for the connector.
fields	Array of ConnectorField objects	The list of initial form fields associated with the connector. Only relevant when building a custom connection integration.
payment _fields	Array of ConnectorPaymentField objects	The list of initial form fields to use when validating a payment. Only relevant when implementing your own payment validation webview.
countries	Array of ConnectorCountry objects	Countries where users can open or have accounts/subscriptions with the given institution.
urls	Array of strings	List of connector's URLs from which we get the data.

AuthMechanism values

Value	Description
credentials	Connections will use a set of fields to save user credentials.
webauth	Connections will use a web-based flow to obtain access.

Forward compatibility requirement: additional mechanisms may be added in the future. When implementing mechanism handling, always safely handle unsupported values.

ConnectorField object

Name	Type	Description
name	String	The technical name of the field, used as a key when sending the values for the field.
connector_sources	Array of strings	The list of connector source names for which the field is relevant. Fields should be presented sequentially according to the source being added. The value can differ with the auth_mechanism preferentially used.
auth_mechanisms	Array of AuthMechanism strings	The list of mechanisms for which the field is relevant. Fields should be presented sequentially according to the source being added.
type	ConnectorFieldType string	Type of the field, to be used to present an appropriate UI form field to the end-user. Implementations should ignore unsupported types and fallback to a text field.
label	String	A short display label for the field.
required	Boolean	If true, the parameter is required, with a non-empty value, when creating a connection.
regex	String or null	An optional regular expression (PCRE-compatible) that the field value must validate.
values	Array of objects	For list fields, a closed list of fixed values to chose from. Entries are composed of label (string, display value of the field) and value (string, the actual value to send for the field).

ConnectorPaymentField object

Name	Type	Description
name	String	The technical name of the field, used as a key when sending the values for the field.
auth_mechanisms	Array of strings	The list of validation mechanisms for which the field is relevant. Fields should be presented sequentially according to the source being added.
type	ConnectorFieldType string	Type of the field, to be used to present an appropriate UI form field to the end-user. Implementations should ignore unsupported types and fallback to a text field.
label	String	A short display label for the field.
required	Boolean	If true, the parameter is required, with a non-empty value, when creating a connection.
regex	String or null	An optional regular expression (PCRE-compatible) that the field value must validate.
values	Array of objects	For list fields, a closed list of fixed values to chose from. Entries are composed of label (string, display value of the field) and value (string, the actual value to send for the field).

ConnectorFieldType values

Value	Description
text	A simple text field.
password	A simple text field for a sensitive value. Implementations should provide secure typing for such fields.
date	A date field. Input should be proposed in a user-friendly manner with a picker or a localized text input, but the value must be submitted as an ISO 8601 date string (yyyy-mm-dd).
list	A field whose value must be chosen in a closed list of values. The field can be presented with a dropdown or a similar control.

ConnectorCountry object

Name	Type	Description
id	String	The country ISO 3166‑1 alpha‑2 code.
name	String	The country name.

PaymentSettings object

Name	Type	Description
available_validate_mechanisms	Array of strings	The list of payment validation mechanisms supported by this connector. As of Sept. 2023, the only supported mechanism is webauth.
beneficiary_types	Array of PaymentAccountSchemeName	The list of supported payment beneficiary types for this connector.
execution_date_types	Array of ExecutionDate	The list of supported payment types.
execution_frequencies	Array of ExecutionFrequency	The list of supported periodic payment frequencies.
maximum_number_of_instructions	Integer	The maximum number of individual instructions for one payment. If 1, the connector does not support Bulk payments.
providing_payer_account	ProvidingPayerAccount	Indicates if the connector needs the payer account identification in order to initiate a payment with their bank.
partial_status_tracking	Array of ExecutionDate	Indicates for which payment date types a payment can reach the final state accepted for this connector, meaning the bank does not provide us with the full tracking of the payment status. See PaymentState values for more information. An empty list indicates that payments will never get the state accepted on this connector.
is_app_to_app_used	PaymentAppToAppUsed	Whether redirects can be caught by native applications on mobile platforms.
bank_provides_payer_account	Boolean or null	Whether the bank provides the payer account or not. null means this information is not yet available.
bank_provides_payer_label	Boolean or null	Whether the bank provides the payer account label or not. null means this information is not yet available.
transfer_date_types_where_ trusted_beneficiary_required	Array of ExecutionDate	List of execution date types for which the beneficiary must be trusted beforehand by the payer.
cancellation _available	Boolean	Whether cancellation is available for this connector.
minimum_amount	PaymentAmount	The minimum amount for a payment on this connector. The amount can differ between payment types.
maximum_amount	PaymentAmount	The maximum amount for a payment on this connector. The amount can differ between payment types. Note that this amount is not necessarily a hard limit and a PSU payment account could have a specific transfer limit (whether higher or lower).
minimum_date_delta_days	Decimal	The minimum number of days in the future for a deferred or periodic payment.
maximum_date_delta_days	Decimal or null	The maximum number of days in the future for a deferred or periodic payment.

An example payment_settings object is the following:

{
  "available_validate_mechanisms": ["webauth"],
  "beneficiary_types": ["iban"],
  "execution_date_types": ["first_open_day", "deferred", "periodic"],
  "execution_frequencies": ["monthly", ...],
  "maximum_number_of_instructions": 10,
  "partial_status_tracking": ["first_open_day"],
  "is_app_to_app_used": {
    "android": false,
    "ios": null
  },
  "bank_provides_payer_account": true,
  "bank_provides_payer_label": null,
  "transfer_date_types_where_trusted_beneficiary_required": ["periodic"],
  "cancellation_available": true,
  "minimum_amount": {
    "first_open_day": 0.,
    "deferred": 0.,
    "instant": 0.
  },
  "maximum_amount": {
    "first_open_day": 4000.,
    "deferred": 4000.,
    "instant": 1000.
  },
  "minimum_date_delta_days": 1,
  "maximum_date_delta_days": 30,
}

ProvidingPayerAccount values

Value	Description
not_used	The payer account is not necessary and must not be given.
optional	The payer account is optional. Providing the account may have an impact on the bank's webview (e.g. the payment account may be preselected for the user, or the user may not have the possibility to change it for another one).
mandatory	The payer account must be provided. The bank does not allow a payment initiation without this information.

PaymentAppToAppUsed object

Name	Type	Description
android	Boolean or Null	Whether redirections can be caught by a native application or not on Android.
ios	Boolean or Null	Whether redirections can be caught by a native application or not on Apple iOS.

For all platforms, null means that the information is not available yet. Note that true does not mean the redirections are necessarily caught by a native application, since the end user may not have installed the appropriate application for this to happen.

An example PaymentAppToAppUsed object is the following:

{
  "android": false,
  "ios": null
}

PaymentAmount object

Value	Type	Required	Description
first_open_day	Decimal	No	The amount limit for first open day payments.
instant	Decimal	No	The amount limit for instant payments.
deferred	Decimal	No	The amount limit for deferred payments.
periodic	Decimal	No	The amount limit for periodic payments.

Product values

Value	Description
bank	Bank product.
wealth	Wealth product.
bill	Bill product.
pay	Pay product.

ConnectorUpdateRequest object

Name	Type	Required	Description
hidden	Boolean	No	Whether the connector is hidden from users.
sync_periodicity	Decimal	No	Number of days between two automatic synchronizations. Overload global sync_periodicity parameter.

ConnectorSourcesList object

Property	Type	Description
sources	Array of ConnectorSource objects	List of connector sources.

ConnectorSource object

Property	Type	Description
id	Integer	ID of the connector source.
id_connector	Integer	ID of the related connector.
name	String	Name of the connector source.
auth_mechanism	AuthMechanism string or null	Authentication mechanism to use to add a connection source.
available_auth_mechanisms	Array of AuthMechanism strings	The list of available mechanisms to add a connection source.
disabled	DateTime or null	If set, this source is ignored on synchronizing the connection.
priority	Integer	The source priority order for the synchronization. Sources must be added following priority order.
account_usages	Array of BankAccountUsage strings	The list of account usages returned by the source.

ConnectorSourceUpdateRequest object

Property	Type	Required	Description
auth_mechanism	AuthMechanism string	No	The authentication mechanism to use for this connector source.
disabled	DateTime or null	No	If set, this source is ignored on synchronizing the connection.