Payments
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
.- 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.
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.
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 | Yes | The payment information. | |
operator_identity | No | Detailed identity information about the entity initiating the payment. | |
payer_identity | 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 |
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 | 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 | 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.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. |
Property | Type | Required | Description |
---|---|---|---|
id_user | Integer | No | |
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 | |
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. |
Property | Type | Description |
---|---|---|
id | Integer | The ID of the created payment request. |
state | The state of the payment request. | |
error_code | 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 | The payer information for the payment. | |
instructions | The list of payment instructions. | |
payer_identity | Detailed identity information about the payer/debtor. |
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.
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 | 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
.Value | Description |
---|---|
iban | International Bank Account Number. |
sort_code_account_number | United Kingdom local account number. |
Property | Type | Description |
---|---|---|
reference_id | String | An identifier for the transaction (maximum 31 characters). |
amount | Number | The amount of the payment. |
currency | The currency of the payment amount. | |
label | String | Label of the payment. |
execution_date_type | 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 | The beneficiary information for the payment. | |
beneficiary_identity | 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 . |
Property | Type | Sensitive | Description |
---|---|---|---|
id_user | Integer | No | |
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 | |
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
).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. |
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. |
Property | Type | Description |
---|---|---|
payments | List of payments. |
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 |
Property | Type | Required | Description |
---|---|---|---|
scope | Yes | The service permissions to authorize for this token. The scope payments:admin cannot be granted to a restricted payment token. |
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. |
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
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"
}
},
{