Comment on page

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. 
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
Array of
PaymentInstruction 
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.
validate
_mechanism
String
Required
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
Conditional
Encrypted static fields to provide for the payment.

See end-to-end encryption for more details on how to encrypt.
website
String
Conditional
(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
​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.
webview_url
String
Required
URL to which to redirect the end user after redirect actions, for the validation process.
validated
Boolean
Optional
Provide true to acknowledge payment validation at once. Otherwise, validation is deferred.
PaymentResumeRequest object
This section is only useful if you're implementing your own webview; see the corresponding guide for more details.
This is the expected payload when the current action is decoupled.
Property
Type
Presence
Description
resume
Boolean
Required
Must be set to true.
PaymentSubmitFieldValuesRequest object
This section is only useful if you're implementing your own webview; see the corresponding guide for more details.
This is the expected payload when the current action is additionalInformationNeeded.
Property
Type
Presence
Description
fields
String dictionary
Required
Cleartext fields to provide for the payment.
PaymentSubmitPSUValidationRequest object
This section is only useful if you're implementing your own webview; see the corresponding guide for more details.
This is the expected payload when the current action is psuValidation.
Property
Type
Presence
Description
psu_validate
Boolean
Required
Must be set to true if the PSU has validated the payment (or if PSU validation is considered implicit), or false otherwise.
PaymentConfirmRequest object
This section is only useful if you're confirming payments manually.
This is the expected payload when the current action is confirm.
Property
Type
Presence
Description
confirm
Boolean
Required
Must be set to true if the payment should be confirmed, or false otherwise.
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.
partial
Final state
(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.
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.
PaymentAction values
Value
Description
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.
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.
PaymentInstructionState values
Value
Kind
Description
pending
Intermediate state
The instruction's execution has not been confirmed yet.
rejected
Final state
The instruction has been rejected by the bank or the user. The error_code is available.
done
Final state
The instruction has been executed and confirmed by the bank.
accepted
Final state
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.
PaymentFieldType values
Value
Description
text
The field should be displayed as a simple text box.
list
The field should be displayed as a selection widget.
Data structures
PaymentFieldValue object
Property
Type
Description
label
String
Human-readable description of the choice.
value
String
Technical value to pass to select the value.
PaymentField object
Property
Type
Description
name
String
Technical name of the field, for the client to use to identify the corresponding value.
type
​PaymentFieldType string
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
Array of PaymentFieldValue objects
Values to choose from for list fields.
Resources
PaymentAccount resource
Property
Type
Presence
Description
scheme_name
​PaymentAccountSchemeName string
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
​IdentitySchemeName string
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":

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

Value	Description
`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.

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.
`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`	Array of PaymentInstruction	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.

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

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.
`partial`	Final state	(Only for bulk payments) At least one instruction was rejected, and at least one instruction was either done or accepted.

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.

Value	Kind	Description
`pending`	Intermediate state	The instruction's execution has not been confirmed yet.
`rejected`	Final state	The instruction has been rejected by the bank or the user. The `error_code` is available.
`done`	Final state	The instruction has been executed and confirmed by the bank.
`accepted`	Final state	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.

Value	Description
`text`	The field should be displayed as a simple text box.
`list`	The field should be displayed as a selection widget.

Property	Type	Description
`label`	String	Human-readable description of the choice.
`value`	String	Technical value to pass to select the value.

Property	Type	Description
`name`	String	Technical name of the field, for the client to use to identify the corresponding value.
`type`	PaymentFieldType string	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`	Array of PaymentFieldValue objects	Values to choose from for `list` fields.

Property	Type	Presence	Description
`scheme_name`	PaymentAccountSchemeName string	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`.

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`	IdentitySchemeName string	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.

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