Links

Payments

API endpoints

Authentication: endpoints listed in this page require header authentication with a service token with the relevant payments:* scope.
post
https://{domain}.biapi.pro/2.0
/payments
Initiate a payment
get
https://{domain}.biapi.pro/2.0
/payments
List payments
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.

Life cycle

Cancellation

Payment cancellation is allowed only under specific circumstances:
  • The execution date type must be one of the following: first_open_day, deferred, periodic.
  • The current state must be one of the following: created, pending.
When a payment cancellation is requested, only the following parameters are taken into account: client_redirect_uri, client_state.
Some banks require a confirmation by the PSU before the cancellation request is accepted. In such cases the API will return the validation URL in the validate_uri field of the payment object in the response. If this field is empty but the payment is not cancelled yet, it means that the payment cancellation has not been accepted.
Note that the redirect URI is required for such cases, and will be validated against your application's authorized redirect URIs if provided.

Webhooks

Payment state updated

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

Data model

PaymentInitRequest object

Property
Type
Required
Description
id_connector
Integer
No
ID of the bank connector to use to initiate the payment. The bank connector must be eligible to payments creation. The id_connector can be submitted later on if validated is false when you initiate the payment request.
client_redirect_uri
String
Yes
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
No
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
Array of PaymentInstructionRequest objects
Yes
The payment information.
operator_identity
IdentityRequest object
No
Detailed identity information about the entity initiating the payment.
payer_identity
IdentityRequest object
No
Detailed identity information about the payer/debtor.
payer
No
Account information about the payer. This data is required for connectors that need the payer account.
validated
Boolean
No
Set to true to acknowledge payment validation at once. Otherwise, validation is deferred.

PaymentInstructionRequest object

Property
Type
Required
Description
reference_id
String
No
An identifier for the transaction, set by the emitter client. If not provided, a random ID is generated (maximum 31 characters).
amount
Number
Yes
The amount of the payment.
currency
String
Yes
The currency code of the payment amount, a per ISO 4217.
label
String
Yes
Label of the payment.
execution_date_type
ExecutionDate string
Yes
The execution date type of the payment.
execution_date
Date
No
The execution date for the transfer, only for deferred transfers. Must be a UTC date.
beneficiary
No
The beneficiary information for the payment instruction.
beneficiary_identity
IdentityRequest object
No
Detailed identity information about the beneficiary.
start_date
Date
No
The starting date for periodic transfers. Required if execution_date_type is periodic.
end_date
Date
No
The ending date for periodic transfers. If none is provided, the transfer will be executed indefinitely until stopped manually.
frequency
No
The frequency of execution for periodic transfers. Required if execution_date_type is periodic.
The reference_id field can only be 18 characters long if the beneficiary of the payment is in the UK and uses the Faster Payment Scheme, i.e. beneficiary.scheme_name = sort_code_account_number.
When the reference_id is automatically generated, an index is added at the end of each instruction reference for ease of reconciliation (in case of a bulk payment). See Reference ID default values for an example.

PaymentAccountRequest object

Property
Type
Required
Description
scheme_name
Yes
The payment account number type.
identification
String
Yes
The payment account number, of type matching the given scheme_name.
label
String
Yes
Display name of the payment account.
issuer
String
No
The BIC of the payment account (when the scheme_name is iban).
bic
String
No
(Deprecated, use issuer instead) The BIC of the payment account.

IdentityRequest object

Property
Type
Required
Description
id_user
Integer
No
ID of the user related to this payment. If provided, this must be an existing User.
kind
String
No
One of individual, corporate, non_profit, government. Defaults to individual.
external_ref
String
No
External reference assigned by the customer to the entity defined by this Identity. Maximum 255 characters.
first_name
String
No
First name. Maximum 255 characters.
last_name
String
No
Last name. Maximum 255 characters.
birth_city
String
No
City of birth.
birth_country
String
No
Country of birth, as an ISO 3166-1 alpha-2 code.
birth_date
Date
No
Date of birth.
nationality
String
No
Nationality.
postal_address
String
No
Postal address. Maximum 512 characters.
scheme_name
No
Identification number type. Required if identification is provided.
identification
String
No
Identification number. Maximum 255 characters.
issuer
String
No
Issuer of the identification. Maximum 255 characters.
ultimate_owner_text
String
No
Identity text of the first ultimate owner of the entity.
ultimate_owner_extra_text
String
No
Identity text for additional ultimate owners of the entity.
pep
Boolean
No
Is the person politically exposed. Defaults to false. Maximum 255 characters.
org_name
String
No
Entity name of the organization, required if kind is not individual. Maximum 255 characters.
org_legal_status
String
No
Legal status of the organization, required if kind is not individual. Maximum 128 characters.
org_hq_address
String
No
Headquarters address of the organization, required if kind is not individual. Maximum 512 characters.
org_business_address
String
No
Business address of the organization, required if kind is not individual. Maximum 512 characters.

Payment object

Property
Type
Description
id
Integer
The ID of the created payment request.
state
PaymentState string
The state of the payment request.
error_code
PaymentErrorCode string or null
The error code of the payment request.
error_description
String or null
Error message in case of an error.
id_connector
Integer or null
ID of the bank connector to use to initiate the payment.
register_date
DateTime
Creation date of the transfer request.
validate_uri
String or null
The URL that must be presented to the PSU to validate the payment request. The URL is only available after the transfer has been validated.
client_redirect_uri
String or null
The validate_uri callback URL that was provided when configuring the transfer request.
payer
PaymentAccount object
The payer information for the payment.
instructions
Array of PaymentInstruction objects
The list of payment instructions.
payer_identity
Identity object
Detailed identity information about the payer/debtor.

PaymentState values

Value
Final
Description
created
No
The payment request was registered, but not yet validated.
validating
No
The payment request was validated and initialized with the bank. The validate_uri is available.
error
No
An error occurred while initializing the request with the bank. The error_code is available.
pending
No
The payment request has been validated on the bank website, but execution has not been confirmed yet.
rejected
Yes
The payment request has been rejected by the bank or the user. The error_code is available.
done
Yes
The payment has been executed and confirmed by the bank.
accepted
Yes
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
Yes
(Deprecated) Equivalent to accepted.
expired
Yes
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.
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.

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.

PaymentAccount object

Property
Type
Description
scheme_name
The payment account number type.
identification
String
The payment account number, of type matching the given scheme_name.
label
String or null
Display name of the payment account.
issuer
String or null
The BIC of the payment account. (when the scheme_name is iban).
bic
String or null
(Deprecated in favor of issuer) The BIC of the payment account.
merchant_scheme_name
String or null
(Deprecated) For merchant beneficiaries, the type of identifier: siret, siren, rcs, rna.
merchant_identification
String or null
(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.

PaymentAccountSchemeName values

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

PaymentInstruction object

Property
Type
Description
reference_id
String
An identifier for the transaction (maximum 31 characters).
amount
Number
The amount of the payment.
currency
Currency object
The currency of the payment amount.
label
String
Label of the payment.
execution_date_type
ExecutionDate string
The execution date type of the payment.
execution_date
Date or null
The execution date of the payment (available when the payment is deferred or has been validated)
beneficiary
PaymentAccount object
The beneficiary information for the payment.
beneficiary_identity
Identity object
Detailed identity information about the beneficiary.
start_date
Date
The starting date for periodic transfers. Only present if execution_date_type is periodic.
end_date
Date
The ending date for periodic transfers. Only present if end_date was provided during payment creation.
frequency
The frequency of execution for periodic transfers. Only present if execution_date_type is periodic.

Identity object

Property
Type
Sensitive
Description
id_user
Integer
No
ID of the user related to this payment, if any.
kind
String
No
One of individual, corporate, non_profit, government. Defaults to individual.
external_ref
String
No
External reference assigned by the customer to the entity defined by this Identity.
first_name
String
Yes (1)
First name.
last_name
String
Yes (1)
Last name.
birth_city
String
Yes
City of birth.
birth_country
String
Yes
Country of birth, as an ISO 3166-1 alpha-2 code.
birth_date
Date
Yes
Date of birth.
nationality
String
Yes
Nationality.
postal_address
String
Yes
Postal address.
scheme_name
Yes (2)
Identification number type. Required if identification is provided.
identification
String
Yes (2)
Identification number.
issuer
String
Yes (2)
Issuer of the identification.
ultimate_owner_text
String
Yes
Identity text of the first ultimate owner of the entity.
ultimate_owner_extra_text
String
Yes
Identity text for additional ultimate owners of the entity.
pep
Boolean
Yes
Is the person politically exposed. Defaults to false.
org_name
String
No
Entity name of the organization, used if kind is not individual.
org_legal_status
String
No
Legal status of the organization, used if kind is not individual.
org_hq_address
String
Yes
Headquarters address of the organization, used if kind is not individual.
org_business_address
String
Yes
Business address of the organization, used if kind is not individual.
"Sensitive" fields are only returned by the API if the show_sensitive query parameter is used.
(1) These fields are always returned when kind is individual.
(2) These fields are always returned for organizations (kind is not individual).

IdentitySchemeName values

Value
Relevant 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.

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.

PaymentsList object

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

PaymentUpdateRequest object

Property
Type
Required
Description
id_connector
Integer
No
ID of the bank connector to use to initiate the payment. The bank connector must be eligible to payments creation. The transfer will not be able to be validated before the connector is provided.
validated
Boolean
No
Provide true to acknowledge payment validation at once. Otherwise, validation is deferred.
cancel
Boolean
No
Provide true to request the payment cancellation.

PaymentTokenRequest object

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

PaymentToken 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.

Reference ID default values

Default reference IDs have a suffix based on the index of the instruction. The number of digits is chosen to contain the highest index of instruction without any leading zero.
For example a bulk payment with two instructions will have references of the form:
  • <ref-id>-1
  • <ref-id>-2
While a bulk payment with 10 instructions would look like:
  • <ref-id>-01
  • <ref-id>-02
  • ...
  • <ref-id>-10
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"
}
},
{