Transfers (obsolete)

The Pay product should be preferred to these services as it handles PSD2-compliant use-cases.

API endpoints

Authentication: endpoints listed in this page require header authentication with a user token.

List recipients

GET https://{domain}.biapi.pro/2.0/users/{userId}/recipients

Path Parameters

Name	Type	Description
userId*	Integer or "me"	ID of the related user.

200: OK List of recipients

Response body: RecipientsList object

409: Conflict No bank account is activated

Response body: Error object with noAccount code

Filtered route alias:

/accounts/{accountId}/recipients

List recipient categories

GET https://{domain}.biapi.pro/2.0/users/{userId}/recipientCategories

Path Parameters

Name	Type	Description
userId*	Integer or "me"	ID of the related user.

200: OK List of recipient categories

Response body: RecipientCategoriesList object

Add a recipient

POST https://{domain}.biapi.pro/2.0/users/{userId}/accounts/{accountId}/recipients

Request body: RecipientCreationRequest object

Path Parameters

Name	Type	Description
userId*	Integer or "me"	ID of the related user.
accountId*	Integer	ID of the related account.

200: OK Recipient created

Response body: Recipient object

Update a recipient

POST https://{domain}.biapi.pro/2.0/users/{userId}/accounts/{accountId}/recipients/{recipientId}

Request body: Key-value object build from the requested fields.

Path Parameters

Name	Type	Description
userId*	Integer or "me"	ID of the related user.
accountId*	Integer	ID of the related account.
recipientId*	Integer	ID of the recipient.

200: OK Recipient updated

Response body: Recipient object

Create a transfer

POST https://{domain}.biapi.pro/2.0/users/{userId}/transfers

Request body: TransferCreationRequest object

Path Parameters

Name	Type	Description
userId*	Integer or "me"	ID of the related user.

200: OK Transfer created

Response body: Transfer object

400: Bad Request Maximum amount exceeded

The maximum transfer amount available, enforced by the bank or our API, has been exceeded. Response body: Error object with maxAmountExceeded code, and optionally a max_amount key with the maximum amount.

400: Bad Request Maximum period amount exceeded

The maximum transfer amount available on a cooling period, enforced by the bank or our API, has been exceeded. Response body: Error object with maxPeriodAmountExceeded code, and optionally a max_amount key with the maximum amount.

List transfers

GET https://{domain}.biapi.pro/2.0/users/{userId}/transfers

Path Parameters

Name	Type	Description
userId*	Integer or "me"	ID of the related user.

200: OK List of transfers

Response body: TransfersList object

409: Conflict No bank account is activated

Response body: Error object with noAccount code

Get a transfer

GET https://{domain}.biapi.pro/2.0/users/{userId}/transfers/{transferId}

Get a single transfer by ID.

Path Parameters

Name	Type	Description
userId*	Integer or "me"	ID of the related user.
transferId*	Integer	ID of the transfer.

200: OK Transfer details

Response body: Transfer object

Update a transfer

POST https://{domain}.biapi.pro/2.0/users/{userId}/transfers/{transferId}

Request body: TransferUpdateRequest object

Path Parameters

Name	Type	Description
userId*	Integer or "me"	ID of the related user.
accountId*	Integer	ID of the related account.
recipientId*	Integer	ID of the recipient.

200: OK Transfer updated

Response body: Transfer object

Data model

RecipientsList object

Property	Type	Description
recipients	Array of Recipient objects	List of recipients.

Recipient object

Property	Type	Description
id	Integer	ID of the recipient.
id_account	Integer	ID of the related emitter bank account.
id_target_account	Integer or null	If this recipient represents a known aggregated account as an internal transfer destination, ID of the related destination bank account.
label	String	Name of the recipient.
iban	String or null	IBAN of the recipient, if available.
bic	String or null	BIC code of the recipient, if available.
bank_name	String or null	Name of the bank holding the recipient account, if available.
enabled_at	DateTime or null	Enable date of the recipents. Transfers to disabled recipients is not possible.
state	RecipientState string of null	The sync status of this recipient. The null value indicates a successful sync.
fields	Array of ConnectorField objects or null	If validation of the recipient requires credentials input, this list of relevant fields that must be prompted to the end-user.
error_message	String or null	If the recipient is in an error state, the optional bank message.

RecipientState values

Value	Description
wrongpass	The authentication on website has failed.
additionalInformationNeeded	Additional information is needed such as an OTP.
websiteUnavailable	The connector website is unavailable.
actionNeeded	An action is needed on the website by the user, scraping is blocked.
decoupled	Requires a user validation on a third-party app or device (ex: digital key).
bug	A bug has occurred during the synchronization.

RecipientCategoriesList object

Property	Type	Description
categories	Array of strings	List of recipient categories.

RecipientCreationRequest object

Property	Type	Required	Description
iban	String	Yes	The IBAN of the recipient.
label	String	Yes	The name of the recipient.
category	String	No	The category of the recipient, if needed.
background	Boolean	No	Flag to make the request asynchronous (i.e. the API will respond immediately and process the registration with the bank in background). When using this option, you must implement polling on the recipient to monitor the state.

TransferCreationRequest object

Name	Type	Required	Description
id_account	Integer	Yes	ID of the emitter account.
amount	Decimal	Yes	Amount of the transfer. The currency is set by the emitter account.
label	String	No	Label of the transfer.
beneficiary_type	BeneficiaryType string	Yes	Type of beneficiary.
id_recipient	Integer	No	ID of the recipient, for the recipient beneficiary type.
beneficiary_number	String	No	Identification of the beneficiary, according to the beneficiary_type: IBAN or phone number.
beneficiary_label	String	No	Name of the beneficiary for the iban or phone_number types.
validated	Boolean	No	Flag to validate the transfer (submit to the bank).
background	Boolean	No	Flag to make the validation request asynchronous (i.e. the API will respond immediately and process the validation with the bank in background). When using this option, you must implement polling on the transfer to monitor the state.

BeneficiaryType values

Value	Description
recipient	Transfer to a registered beneficiary.
iban	Direct transfer to an IBAN (without beneficiary addition).
phone_number	Direct transfer to a phone number (without beneficiary addition).

Transfer object

Property	Type	Description
id	Integer	ID of the transfer.
id_account	Integer or null	ID of the related emitter bank account.
id_recipient	Integer or null	ID of the recipient, for the recipient beneficiary type.
beneficiary_type	BeneficiaryType string	Type of beneficiary.
beneficiary_number	String or null	Identification of the beneficiary, according to the beneficiary_type: IBAN or phone number.
exec_date	Date or null	Execution date of the transfer.
amount	Decimal	Amount of the transfer.
currency	Currency object	Currency of the transfer.
label	String	Label of the transfer.
state	TransferState string or null	State of the transfer.
fields	Array of ConnectorField objects or null	If validation of the transfer requires credentials input, this list of relevant fields must be prompted to the end-user.
validate_mechanism	TransferValidateMechanism string	The mechanism to use to validate the transfer.
error_message	String or null	If the transfer is in an error state, the optional bank message.

TransferState values

Value	Description
created	The transfer is created in our API but not yet validated with the bank.
validating	The transfer is being submitted to the bank.
scheduled	The transfer has been submitted to the bank and is scheduled for future execution.
pending	The transfer has been submitted to the bank, execution is in progress.
done	The transfer has been confirmed by the bank.
canceled	The transfer has been explicitly cancelled by the user.
coming	The transfer is confirmed but the operation is still marked as coming.
deleted	The transfer was not found on the bank.
transactionNotFound	The transfer has been confirmed but the matching transaction is not found on the bank.
wrongpass	The authentication on the website has failed.
additionalInformationNeeded	Additional information is needed such as an OTP.
websiteUnavailable	The connector website is unavailable.
actionNeeded	An action is needed on the website by the user, scraping is blocked.
decoupled	Requires a user validation on a third-party app or device (ex: digital key).
bug	A bug has occurred during the synchronization.

TransferValidateMechanism values

Value	Description
credentials	The transfer will be validated using a set of fields available in the API response.
webauth	The transfer will be validated using the /webauth endpoint.

TransfersList object

Property	Type	Description
transfers	Array of Transfer objects	List of transfers. The list only includes transfers created by our API.
first_date	Date	Minimum available date for results.
last_date	Date	Maximum available date for results.
result_min_date	Date	Minimum date of results in the current response.
result_max_date	Date	Maximum date of results in the current response.

TransferUpdateRequest object

Name	Type	Required	Description
id_account	Integer	No	New ID of the emitter account.
amount	Decimal	No	New transfer amount. The currency is set by the emitter account.
label	String	No	New label of the transfer.
beneficiary_type	BeneficiaryType string	No	New type of beneficiary.
id_recipient	Integer	No	New ID of the recipient, for the recipient beneficiary type.
beneficiary_number	String	No	New identification of the beneficiary, according to the beneficiary_type: IBAN or phone number.
beneficiary_label	String	No	New name of the beneficiary for the iban or phone_number types.
validated	Boolean	No	Flag to validate the transfer (submit to the bank).

To validate a transfer using the credentials mechanism, you must include in the request the values from the connector fields.