Payments
Authentication: endpoints listed in this page require header authentication with a service token with the relevant
payments:*
scope.get
https://{domain}.biapi.pro/2.0
/payments
List payments
post
https://{domain}.biapi.pro/2.0
/payments
Create a payment
get
https://{domain}.biapi.pro/2.0
/payments/{paymentId}
Get a payment
post
https://{domain}.biapi.pro/2.0
/payments/{paymentId}
Update, validate or cancel a payment
post
https://{domain}.biapi.pro/2.0
/payments/{paymentId}/scopedtoken
Generate a payment-scoped token
Note that using the
show_sensitive
parameter requires a payment token with scope payments:admin
or payments:allow-sensitive
.A
PAYMENT_STATE_UPDATED
webhook is emitted after a payment has been updated.The
PAYMENT_STATE_UPDATED
event data will only be sent when the payment state is updated in a non-interactive operation. This corresponds to two scenarios:- The payment request has been validated by the PSU, and during a regular background check on the payment with the bank, we have detected a change in its state.
- The payment request has been validated by the PSU, but they have not been redirected to our callback (network issues, browser closed too early, crash, anomalous behavior of the bank's interface, ...). This case falls back to background checks, as described above.
Please note that if the validation flow succeeds and the new state is communicated in your callback, the webhook will not be triggered until a later update.
This model is presented with two-step payment validation in mind, where the initial request is done by your client implementation and the validate request is done by the webview, as described in the payment webview implementation guide.
Property | Type | Presence | Description |
---|---|---|---|
id_connector | Integer | Optional | (Deprecated) ID of the bank connector to pre-select for the payment.
This property is deprecated in favor of connector_uuid . |
connector_uuid | String | Optional | UUID of the bank connector to pre-select for the payment.
The bank connector must be eligible to payments creation. |
website | String | Conditional | Value to provide for the payment's website field.
Note that this field is required in the following conditions:
|
client_redirect_uri | String | Required | The redirect URL to use when building the validation URL. The provided URL must not contain any query parameter, rely on the client_state parameter for state management. |
client_state | String | Optional | Optional value that will be added as a state query parameter to the redirect URL after validation. If provided, must be 2000 characters or less. |
instructions | Required | The payment information. | |
operator_identity | Optional | Detailed identity information about the entity initiating the payment. | |
payer | Optional | Account information about the payer. This should be provided here in case the information is known beforehand; otherwise, the webview is responsible for requiring it from the end user if necessary. | |
payer_identity | Optional | Detailed identity information about the payer/debtor. |
This section is only useful if you're implementing your own webview; see the corresponding guide for more details.
Property | Type | Presence | Description |
---|---|---|---|
id_connector | Integer | Optional | (Deprecated) ID of the bank connector to use to initiate the payment.
This property is deprecated in favor of connector_uuid . |
connector_uuid | UUID | Conditional | UUID of the bank connector to use to initiate the payment. Note that it may have been pre-selected at payment creation; see Select a connector for the payment for more information.
The bank connector must be eligible to payments creation. |
website | String | Conditional | Value to provide for the payment's website field, if such a field is required by the connector for payments. |
payer | Conditional | Account information about the payer. This data is required for connectors that need the payer account, if no payer account data has been provided at payment creation. | |
validated | Boolean | Optional | Provide true to acknowledge payment validation at once. Otherwise, validation is deferred. |
Property | Type | Presence | Description |
---|---|---|---|
client_redirect
_uri | String | Required | The redirect URL to use when building the validation URL. The provided URL must not contain any query parameter, rely on the client_state parameter for state management. |
client_state | String | Optional | Optional value that will be added as a state query parameter to the redirect URL after validation. If provided, must be 2000 characters or less. |
cancel | Boolean | Required | Provide true to request payment cancellation. |
Property | Type | Presence | Description |
---|---|---|---|
scope | Required | The service permissions to authorize for this token. The scope payments:admin cannot be granted to a restricted payment token. |
Property | Type | Description |
---|---|---|
payments | List of payments. |
Property | Type | Description |
---|---|---|
token | String | The generated service token. |
scope | String | The attributed permissions for this service token. |
id_payment | Integer | The payment ID linked to the token. |
Value | Description |
---|---|
individual | Individual (personne physique). |
corporate | Corporate entity (entreprise). |
non_profit | Non-profit (association). |
government | Government agency (agence gouvernementale). |
Value | Relevant identity kind | Description |
---|---|---|
national_id_number | individual | National identification number. |
passport_number | individual | Passport number. |
alien_reg_number | individual | Alien registration number. |
siren | corporate non_profit | French SIREN company identification number. |
incorporation_number | corporate non_profit government | Incorporation number. |
euid | corporate non_profit | European Unique Identifier. |
rna | non_profit | French RNA non profit organization identification number. |
Value | Description |
---|---|
iban | International Bank Account Number. |
sort_code_account_number | United Kingdom local account number. |
Value | Description |
---|---|
first_open_day | The payment is executed on the first business day of the bank. For most banks, this excludes the current day. |
deferred | The payment will be executed on the given execution date. |
instant | The payment will be executed in a short time delay, depending on the payer and beneficiary banks. For most banks, the payment status is final after the payment confirmation. |
periodic | The payment is executed periodically at the given frequency. |
The
periodic
date type is not available by default. Please check with your commercial contact to enable this feature.Value | Description |
---|---|
daily | Every day. Note that most banks do not support this frequency. |
weekly | Every week. |
two-weekly | Every two weeks. |
monthly | Every month. |
two-monthly | Every two months. |
quarterly | Every three months. |
four-monthly | Every four months. |
semiannually | Every six months. |
yearly | Every year. |
Value | Kind | Description |
---|---|---|
created | Intermediate state | The payment request was registered, but not yet validated. |
validating | Intermediate state | The payment request was validated and initialized with the bank. The validate_uri is available. |
error | Intermediate state | An error occurred while initializing the request with the bank. The error_code is available. |
pending | Intermediate state | The payment request has been validated on the bank website, but execution has not been confirmed yet. |
rejected | Final state | The payment request has been rejected by the bank or the user. The error_code is available. |
done | Final state | The payment has been executed and confirmed by the bank. |
accepted | Final state | The payment has passed acceptance checks from the banks and is awaiting execution. However the bank will not give us further update on the payment state. |
accepted_no_bank_status | Final state | (Deprecated) Equivalent to accepted . |
expired | Final state | The payment has automatically expired because it did not have a definitive status (ie done or rejected) N days after its execution. N value is configurable with the payment.manual_expire_time_days configuration key. |
The full state diagram is the following:
Payment in a final state will not change of state anymore, this is considered as an ending of the payment flow.
Forward compatibility requirement: additional states may be added in the future. When implementing state handling, always fallback to a non-resolvable generic case for unknown values.
Value | Description |
---|---|
(null) | No state detail. |
cancelling_webauth | The payment is currently being cancelled, and a callback is currently expected. |
Value | Description |
---|---|
invalidEmitter | Identification of the emitter account is invalid, or transfer emission is not possible. |
insufficientFunds | The balance of the emitter account is too low. |
invalidAmount | The amount of the payment request is invalid or out of the authorized bounds. |
invalidCurrency | The currency of the payment request is invalid or unsupported. |
invalidDate | The execution date of the payment request is invalid or out of the supported bounds. |
invalidBeneficiary | The beneficiary identification is invalid or unsupported. |
invalidLabel | The label of the payment request does not match the constraints enforced by the bank. |
regulatoryReason | The request was aborted by the bank for regulatory reason (e.g. fraud detection). |
authenticationFailed | The request was aborted because the end-user failed to identify with the bank. |
noAnswerFromCustomer | The payment request expired without any interaction with the end-user. |
noSpecifiedReason | The payment request was rejected by the bank without any reason. |
CancelledByUser | The payment was explicitly cancelled by the end-user. |
bankMessage | The bank sent an error message to the user. |
invalidValue | The request contains invalid data. |
actionNeeded | An action is needed on the website by the user. |
websiteUnavailable | The connector is currently unavailable, typically happens if the bank's interface is unreachable. |
bug | A bug has occurred during the request validation. |
Forward compatibility requirement: additional codes may be added in the future. When implementing error handling, always fallback to a generic case for unknown values.
Property | Type | Presence | Description |
---|---|---|---|
scheme_name | Required | The payment account number type. | |
identification | String | Required | The payment account number, of type matching the given scheme_name . |
label | String | Required | Display name of the payment account. |
issuer | String | Optional | The BIC of the payment account (when the scheme_name is iban ). |
bic | String | Optional | (Deprecated, use issuer instead) The BIC of the payment account. |
merchant_scheme_name | String or null | Optional | (Deprecated) For merchant beneficiaries, the type of identifier: siret , siren , rcs , rna . |
merchant_identification | String or null | Optional | (Deprecated) For merchant beneficiaries, the identifier, of type matching the merchant_scheme_name . |
merchant_scheme_name
and merchant_identification
have been replaced by the use of payer_identity
and beneficiary_identity
.Property | Type | Options | Description |
---|---|---|---|
id_user | Integer | ||
kind | The kind of entity the identity is linked to.
If not provided, this property is set to individual . | ||
external_ref | String | External reference assigned by the customer to the entity defined by this Identity. Maximum 255 characters. | |
first_name | String | Sensitive | First name. Maximum 255 characters. |
last_name | String | Sensitive | Last name. Maximum 255 characters. |
birth_city | String | Sensitive | City of birth. |
birth_country | String | Sensitive | |
birth_date | Date | Sensitive | Date of birth. |
nationality | String | Sensitive | Nationality. |
postal_address | String | Sensitive | Postal address. Maximum 512 characters. |
scheme_name | Sensitive | Identification number type. Required if identification is provided. | |
identification | String | Sensitive | Identification number. Maximum 255 characters. |
issuer | String | Sensitive | Issuer of the identification. Maximum 255 characters. |
ultimate_owner
_text | String | Sensitive | Identity text of the first ultimate owner of the entity. |
ultimate_owner
_extra_text | String | Sensitive | Identity text for additional ultimate owners of the entity. |
pep | Boolean | Sensitive | Is the person politically exposed. Defaults to false . Maximum 255 characters. |
org_name | String | Entity name of the organization, required if kind is not individual . Maximum 255 characters. | |
org_legal_status | String | Legal status of the organization, required if kind is not individual . Maximum 128 characters. | |
org_hq_address | String | Sensitive | Headquarters address of the organization, required if kind is not individual . Maximum 512 characters. |
org_business_address | String | Sensitive | Business address of the organization, required if kind is not individual . Maximum 512 characters. |
Fields marked sensitive are only returned by the API if the
show_sensitive
query parameter is used.Required properties are the following:
Property | Individual | Corporate | Non-profit | Government |
---|---|---|---|---|
kind | N/A | Mandatory | Mandatory | Mandatory |
first_name | Mandatory | N/A | N/A | N/A |
last_name | Mandatory | N/A | N/A | N/A |
birth_city | Recommended | N/A | N/A | N/A |
birth_country | Recommended | N/A | N/A | N/A |
birth_date | Recommended | N/A | N/A | N/A |
org_name | N/A | Recommended | Recommended | Recommended |
scheme_name | N/A | Mandatory | Mandatory | Mandatory |
identification | N/A | Mandatory | Mandatory | Mandatory |
Examples identities are the following:
Individual
Individual without birth data
Company
Non-profit
{
"kind": "individual",
"first_name": "Jean",
"last_name": "Dupont",
"birth_city": "Paris",
"birth_country": "FR",
"birth_date": "1990-12-31"
}
{
"kind": "individual",
"first_name": "Jean",
"last_name": "Dupont",
"nationality": "FR",
"postal_address": "Appartement 25\nEntrée B Résidence Les Iris\n3 Boulevard du Levant\n95220 HERBLAY",
"external_ref": "MY-CUSTOMER-REFERENCE-012345678"
}
{
"kind": "corporate",
"org_name": "Powens",
"org_legal_status": "SAS",
"org_hq_address": "84 RUE BEAUBOURG\n75003 PARIS 3\nFRANCE",
"scheme_name": "siren",
"identification": "749867206"
}
{
"kind": "non_profit",
"org_name": "Scouts et Guides de France",
"org_legal_status": "Association loi du 1er juillet 1901",
"org_hq_address": "21-37-BAT D 2E ETAGE, 21 RUE DE STALINGRAD, 94110 ARCUEIL",
"scheme_name": "rna",
"identification": "W751001142"
}
End-to-end identifiers (represented by the
reference_id
property) vary in length depending on the payment instrument used:- SEPA Credit Transfers use 31 characters long end-to-end identifiers.
- Domestic UK payments using Faster Payments use 18 characters long end-to-end identifiers.
It is recommended not to provide end-to-end identifiers, so that the API can generate such of correct lengths depending on the situation.
See an example when creating a bulk payment with 2 instructions without providing the
reference_id
:Request
POST /payments
{
"client_redirect_uri": "http://example.org",
"instructions": [
{
"label": "Payment test",
"amount": "1",
"currency": "EUR",
"execution_date_type": "first_open_day",
"beneficiary": {
"scheme_name": "iban",
"identification": "FR4630003000704114151355Z51",
"label": "Fake IBAN"
}
},
{
"label": "Payment test 2",
"amount": "1",
"currency": "EUR",
"execution_date_type": "first_open_day",
"beneficiary": {
"scheme_name": "iban",
"identification": "FR1420041010050500013M02606",
"label": "Fake IBAN"
}
}
]
}
Response
{
"id": 1975,
"state": "created",
"error_code": null,
"error_description": null,
"register_date": "2022-09-29 08:05:30",
"validate_uri": null,
"client_redirect_uri": "http://example.org",
"state_detail": null,
"id_connector": null,
"instructions": [
{
"reference_id": "10mrPLcJVSlf7YFnX6MsfmRfnQT-1",
"execution_date_type": "first_open_day",
"label": "Payment test",
"amount": 1.0000000000,
"currency": {
"id": "EUR",
"symbol": "€",
"prefix": false,
"crypto": false,
"precision": 2,
"marketcap": null,
"datetime": null,
"name": "Euro"
},
"exec_date": null,
"execution_date": null,
"beneficiary": {
"id": 6313,
"id_account": null,
"label": "Fake IBAN",
"scheme_name": "iban",
"identification": "FR4630003000704114151355Z51",
"issuer": "SOGEFRPPXXX",
"disabled_date": null,
"merchant_scheme_name": null,
"merchant_identification": null,
"bic": "SOGEFRPPXXX"
}
},
{
"reference_id": "10mrPLcJVSlf7YFnX6MsfmRfnQT-2",
"execution_date_type": "first_open_day",
"label": "Payment test 2",
"amount": 1.0000000000,
"currency": {
"id": "EUR",
"symbol": "€",
"prefix": false,
"crypto": false,
"precision": 2,
"marketcap": null,
"datetime": null,
"name": "Euro"
},
"exec_date": null,
"execution_date": null,
"beneficiary": {
"id": 6314,
"id_account": null,
"label": "Fake IBAN",
"scheme_name": "iban",
"identification": "FR1420041010050500013M02606",
"issuer": "SOGEFRPPXXX",
"disabled_date": null,
"merchant_scheme_name": null,
"merchant_identification": null,
"bic": "SOGEFRPPXXX"
}
}
]
}
Property | Type | Presence | Description |
---|---|---|---|
reference_id | String | Optional | The optional end-to-end identifier for the instruction. If not provided, a random identifier is generated (maximum 31 characters). |
amount | Number | Required | The amount of the payment. |
currency | String | Required | The currency code of the payment amount, a per ISO 4217. |
label | String | Required | Label of the payment. |
execution_date_type | Required | The execution date type of the payment. | |
execution_date | Date | Conditional | The execution date for the transfer, only for deferred transfers. Must be a UTC date. |
beneficiary |