Payments
Last updated
Was this helpful?
Last updated
Was this helpful?
Authentication: endpoints listed in this page require with a service token with the relevant payments:*
scope.
GET
https://{domain}.biapi.pro/2.0/payments
By default, payments are ordered by register_date
.
show_sensitive
Boolean
Set to true to return sensitive fields from identities. Defaults to false.
limit
Integer
Limit the number of results.
offset
Integer
First result offset.
reverse
Boolean
Reverse the results order (by date).
filter
String
Specify the date field to use when using min_date
and max_date
filters. Value can be register_date
or validate_date
min_date
Date
Minimal date (inclusive).
max_date
Date
Maximal date (exclusive).
connector_uuid
String
Filter by connector UUID. null
can be used to filter payments without an associated connector.
id_connector
Integer
Filter by connector ID. null
can be provided to filter payments without an associated connector.
id_connector_source
Integer
Filter by connector source ID.
state
String
error_code
String
bank_payment_id
String
Filter by bank payment ID.
website
String
Filter by website field value.
payer_identification
String
beneficiary_identification
String
reference_id
String
Filter by instruction reference ID
execution_date_type
String
order_by
String
Order the payments by the specified field. Value can be id
, register_date
, validate_date
, state
, connectors
, amount
, instruction_count
, execution_date_type
.
country
String
Filter by country. Several countries can be provided, separated by commas.
Response body: PaymentListResponse object
POST
https://{domain}.biapi.pro/2.0/payments
Request body: PaymentInitRequest object
show_sensitive
Boolean
Set to true to return sensitive fields from identities. Defaults to false.
Response body: Payment resource
GET
https://{domain}.biapi.pro/2.0/payments/{paymentId}
show_sensitive
Boolean
Set to true to return sensitive fields from identities. Defaults to false.
Response body: Payment resource
POST
https://{domain}.biapi.pro/2.0/payments/{paymentId}
This is used in the following flows:
Request body: one of the following objects.
show_sensitive
Boolean
Set to true to return sensitive fields from identities. Defaults to false.
Response body: Payment resource
POST
https://{domain}.biapi.pro/2.0/payments/{paymentId}/scopedtoken
This endpoint requires a payment token with the scope payments:validate
.
Request body: PaymentTokenRequest object
Response body: PaymentTokenResponse object
Note that using the show_sensitive
parameter requires a payment token with scope payments:validate
or payments:allow-sensitive
.
GET
https://{domain}.biapi.pro/2.0/payments/{paymentId}/incompatibilities
all
Boolean
No
Set to true to return incompatibilities for all connectors, including hidden ones.
Response body: Array of PaymentConnectorIncompatibility resource
A PAYMENT_STATE_UPDATED
webhook is emitted after a payment state has been updated.
Webhook request body: Payment resource
The PAYMENT_STATE_UPDATED
event data will be triggered for every payment state change.
If your domain was created before 2024/09/13, the old behaviour of the webhook is used instead.
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.
To switch to the new behaviour of the webhook, please set the configuration key payment.state_updated_webhook.systematic
to '1'
, or contact the support team.
id_connector
Integer
(Deprecated) ID of the bank connector to pre-select for the payment.
This property is deprecated in favor of connector_uuid
.
connector_uuid
String
UUID of the bank connector to pre-select for the payment. The bank connector must be eligible to payments creation.
client_redirect_uri
String
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 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
The payment information.
operator_identity
Detailed identity information about the entity initiating the payment.
payer
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
Detailed identity information about the payer/debtor.
id_connector
Integer
(Deprecated) ID of the bank connector to use to initiate the payment.
This property is deprecated in favor of connector_uuid
.
connector_uuid
UUID
validate
_mechanism
String
Name of the mechanism to use to validate the payment.
Compatibility note: this is set to webauth
when not provided for now.
fields
String dictionary
website
String
(Deprecated) Value to provide for the payment's website
field, if such a field is required by the connector for payments.
This property is deprecated in favor of fields
, which can be used to communicate more fields than just website
.
payer
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.
webview_url
String
URL to which to redirect the end user after redirect
actions, for the validation process.
validated
Boolean
Provide true
to acknowledge payment validation at once. Otherwise, validation is deferred.
This is the expected payload when the current action is decoupled
.
resume
Boolean
Must be set to true
.
This is the expected payload when the current action is additionalInformationNeeded
.
fields
String dictionary
Cleartext fields to provide for the payment.
This is the expected payload when the current action is psuValidation
.
psu_validate
Boolean
Must be set to true
if the PSU has validated the payment (or if PSU validation is considered implicit), or false
otherwise.
This section is only useful if you're confirming payments manually.
This is the expected payload when the current action is confirm
.
confirm
Boolean
Must be set to true
if the payment should be confirmed, or false
otherwise.
client_redirect
_uri
String
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 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
Provide true
to request payment cancellation.
scope
The service
permissions to authorize for this token. The scope payments:admin
cannot be granted to a restricted payment token.
payments
List of payments.
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.
individual
Individual (personne physique).
corporate
Corporate entity (entreprise).
non_profit
Non-profit (association).
government
Government agency (agence gouvernementale).
national_id_number
National identification number.
passport_number
Passport number.
alien_reg_number
Alien registration number.
siren
French SIREN company identification number.
incorporation_number
Incorporation number.
euid
European Unique Identifier.
rna
French RNA non profit organization identification number.
iban
International Bank Account Number.
sort_code_account_number
United Kingdom local account number.
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.
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.
created
The payment request was registered, but not yet validated.
validating
The payment request was validated and initialized with the bank. The validate_uri
is available.
pending
The payment request has been validated on the bank website, but execution has not been confirmed yet.
rejected
The payment request has been rejected by the bank or the user. The error_code
is available.
done
The payment has been executed and confirmed by the bank.
accepted
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.
expired
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.
partial
(Only for bulk payments) At least one instruction was rejected, and at least one instruction was either done or accepted.
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.
(null)
No state detail.
cancelling
The payment is currently being cancelled, and a user action is provided in the action
field .
redirect
The end user must complete a redirect flow, for which the URL is present in validate_uri
.
decoupled
A validation is required from the end user on a side channel, e.g. a mobile app or on a link sent in an email or an SMS.
additionalInformation
Needed
Values for one or more fields are required from the end user. Such fields are provided in fields
.
confirm
A confirmation is required from the client.
psuValidation
A validation is required from the end user.
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.
invalidReferenceId
The reference ID of the payment request is not accepted 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.
CancelledByClient
The payment has been cancelled through the API.
confirmationRefused
The payment confirmation was refused by the client.
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.
pending
The instruction's execution has not been confirmed yet.
rejected
The instruction has been rejected by the bank or the user. The error_code
is available.
done
The instruction has been executed and confirmed by the bank.
accepted
The instruction has passed acceptance checks from the banks and is awaiting execution. However the bank will not give us further update on the payment state.
text
The field should be displayed as a simple text box.
list
The field should be displayed as a selection widget.
incompatible
The connector is incompatible with the payment.
warning
The connector is compatible but some of the payment properties may cause a rejection.
maxAmount
The payment amount is above the known global transfer limit for this connector for this payment type. The PSU may still be able to unlock this limit with their bank.
minAmount
The payment amount is below the minimum amount required by this connector for this payment type.
maxBulk
The number of instructions for this bulk payment is above the maximum number of instructions allowed by the connector.
maxDateDelta
The payment execution date is too far for the connector.
minDateDelta
The payment execution date is not far enough for the connector.
nspDateType
The payment type is not supported by the connector.
nspFrequency
The periodic payment frequency is not supported by the connector.
nspBulk
This connector does not support bulk payments.
nspBenefScheme
The payment beneficiary identification scheme is not supported by the connector.
nspPayer
The connector does not allow providing a payer account.
nspExecDate
The payment execution date is not allowed by the connector.
nspCurrency
The payment currency is not supported by the connector.
trustBenef
The beneficiary needs to be trusted by the payer account.
label
String
Human-readable description of the choice.
value
String
Technical value to pass to select the value.
name
String
Technical name of the field, for the client to use to identify the corresponding value.
type
Type of field, to use to display the correct input widget to the end user.
label
String
Human-readable description of the field.
regex
String or null
Optional PCRE-compatible pattern for text
fields.
required
Boolean
Whether the field is required or not.
values
Values to choose from for list
fields.
scheme_name
The payment account number type.
identification
String
The payment account number, of type matching the given scheme_name
.
label
String
Display name of the payment account.
issuer
String
The BIC of the payment account (when the scheme_name
is iban
).
merchant_scheme_name
and merchant_identification
have been replaced by the use of payer_identity
and beneficiary_identity
.
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
First name. Maximum 255 characters.
last_name
String
Last name. Maximum 255 characters.
birth_city
String
City of birth.
birth_country
String
birth_date
Date
Date of birth.
nationality
String
Nationality.
postal_address
String
Postal address. Maximum 512 characters.
email
String
Email address. Maximum 255 characters.
scheme_name
Identification number type. Required if identification
is provided.
identification
String
Identification number. Maximum 255 characters.
issuer
String
Issuer of the identification. Maximum 255 characters.
ultimate_owner
_text
String
Identity text of the first ultimate owner of the entity.
ultimate_owner
_extra_text
String
Identity text for additional ultimate owners of the entity.
pep
Boolean
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
Headquarters address of the organization, required if kind
is not individual
. Maximum 512 characters.
org_business_address
String
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:
kind
first_name
last_name
birth_city
birth_country
birth_date
org_name
scheme_name
identification
Examples identities are the following:
reference_id
String
The optional end-to-end identifier for the instruction. If not provided, a random identifier is generated (maximum 31 characters).
amount
Number
The amount of the payment.
currency
String
The currency code of the payment amount, a per ISO 4217.
label
String
Label of the payment.
execution_date_type
The execution date type of the payment.
execution_date
Date
The execution date for the transfer, only for deferred
transfers. Must be a UTC date.
beneficiary
The beneficiary information for the payment instruction.
beneficiary_identity
Detailed identity information about the beneficiary.
start_date
Date
The starting date for periodic
transfers. Required if execution_date_type
is periodic
.
end_date
Date
The ending date for periodic
transfers. If none is provided, the transfer will be executed indefinitely until stopped manually.
frequency
The frequency of execution for periodic
transfers. Required if execution_date_type
is periodic
.
state
The current state of the instruction.
id
Integer
The ID of the created payment request.
state
The state of the payment request.
state_detail
The state detail of the payment request.
action
The current action taking place on the payment request.
error_code
The error code of the payment request.
error
_description
String or null
Error message in case of an error.
fields
Fields to provide to the payment for additionalInformationNeeded
actions.
validate_uri
String or null
URL to which to redirect the end user for redirect
actions.
id_connector
Integer or null
(Deprecated) ID of the bank connector to use to initiate the payment.
This property is deprecated in favor of connector_uuid
.
connector_uuid
UUID or null
UUID of the bank connector to use to initiate the payment.
validate
_mechanism
String or null
The chosen validation mechanism for the payment.
register_date
DateTime
Creation date of the payment request.
client_redirect_uri
String or null
client_state
String or null
payer
The payer information for the payment.
instructions
The list of payment instructions.
payer_identity
Detailed identity information about the payer/debtor.
type
Whether the payment is incompatible with the connector, or if it's simply a warning.
reasons
The exhaustive list of reasons causing warnings or incompatibilities.
code
The compatibility code. Indicates the nature of the incompatibility or warning.
type
Whether the reason caused a warning or incompatibility.
description
string
Technical description of the incompatibility code.
value_connector
String or Decimal or Bool or Array or Object
For parametrized incompatibility rules, this is the value associated to the connector to put in comparison with the value exposed in value_payment
.
value_payment
String or Decimal or Bool or Array or Object
For parametrized incompatibility rules, this is the value associated to the payment to put in comparison with the value exposed in value_connector
.
Filter by .
Filter by .
Filter by .
Filter by .
Filter by
For more information on the full payment initiation and validation flow, see .
This endpoint should only be used for getting a payment's status on redirect, not for polling; see for more information.
PaymentValidateRequest object PaymentResumeRequest object PaymentSubmitFieldValuesRequest object PaymentSubmitPSUValidationRequest object PaymentConfirmRequest object PaymentCancelRequest 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 .
Array of
object
object
object
This section is only useful if you're implementing your own webview; see for more details.
UUID of the bank connector to use to initiate the payment. Note that it may have been pre-selected at payment creation; see for more information. The bank connector must be eligible to payments creation.
Encrypted static fields to provide for the payment. See for more details on how to encrypt.
object
This section is only useful if you're implementing your own webview; see for more details.
This section is only useful if you're implementing your own webview; see for more details.
This section is only useful if you're implementing your own webview; see for more details.
string or array
Array of objects
string
Array of objects
string
ID of the related to this payment. If provided, this must be an existing User.
string
Country of birth, as an .
string
string
object
object
string
string or null
string
value
string or null
string or null
Dictionary of objects
(Deprecated) The final callback URL to redirect the end user to at the end of the payment validation process.
Prefer using the redirect_uri
parameter to the instead.
(Deprecated) The optional state to add to the final callback URL.
Prefer using the state
parameter to the instead.
object
Array of objects
object
string
Array of objects
string
string