Links

Payments

API endpoints

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.

Webhooks

Payment state updated

A PAYMENT_STATE_UPDATED webhook is emitted after a payment has been updated.
Webhook request body: Payment resource
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.

Request payloads

PaymentInitRequest object

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:
  • The connector has been pre-selected.
  • The website field is required by the connector.
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
Identity object
Optional
Detailed identity information about the entity initiating the payment.
payer
PaymentAccount object
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
Identity object
Optional
Detailed identity information about the payer/debtor.

PaymentValidateRequest object

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
PaymentAccount object
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.

PaymentCancelRequest object

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.

PaymentTokenRequest object

Property
Type
Presence
Description
scope
Scope string or array
Required
The service permissions to authorize for this token. The scope payments:admin cannot be granted to a restricted payment token.

Responses

PaymentListResponse object

Property
Type
Description
payments
Array of Payment objects
List of payments.

PaymentTokenResponse object

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.

Code sets

IdentityKind values

Value
Description
individual
Individual (personne physique).
corporate
Corporate entity (entreprise).
non_profit
Non-profit (association).
government
Government agency (agence gouvernementale).

IdentitySchemeName values

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.

PaymentAccountSchemeName values

Value
Description
iban
International Bank Account Number.
sort_code_account_number
United Kingdom local account number.

ExecutionDate values

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.

ExecutionFrequency values

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.

PaymentState values

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.

PaymentStateDetail values

Value
Description
(null)
No state detail.
cancelling_webauth
The payment is currently being cancelled, and a callback is currently expected.

PaymentErrorCode values

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.

Resources

PaymentAccount resource

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.

Identity resource

Property
Type
Options
Description
id_user
Integer
ID of the user related to this payment. If provided, this must be an existing User.
kind
IdentityKind string
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
Country of birth, as an ISO 3166-1 alpha-2 code.
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"
}

PaymentInstruction resource

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.
Example
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
ExecutionDate string
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
PaymentAccount object