Payments

API endpoints

Authentication: endpoints listed in this page require header authentication with a service token with the relevant payments:* scope.

List payments

GET https://{domain}.biapi.pro/2.0/payments

By default, payments are ordered by register_date.

Query Parameters

Name	Type	Description
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	Filter by state.
error_code	String	Filter by error_code.
bank_payment_id	String	Filter by bank payment ID.
website	String	Filter by website field value.
payer_identification	String	Filter by payer.identification.
beneficiary_identification	String	Filter by beneficiary.identification.
reference_id	String	Filter by instruction reference ID
execution_date_type	String	Filter byexecution_date
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.

200: OK List of payments

Response body: PaymentListResponse object

Create a payment

POST https://{domain}.biapi.pro/2.0/payments

For more information on the full payment initiation and validation flow, see this guide.

Request body: PaymentInitRequest object

Query Parameters

Name	Type	Description
show_sensitive	Boolean	Set to true to return sensitive fields from identities. Defaults to false.

200: OK Payment created

Response body: Payment resource

Get a payment

GET https://{domain}.biapi.pro/2.0/payments/{paymentId}

This endpoint should only be used for getting a payment's status on redirect, not for polling; see this section of the initiation and validation guide for more information.

Query Parameters

Name	Type	Description
show_sensitive	Boolean	Set to true to return sensitive fields from identities. Defaults to false.

200: OK Payment exists

Response body: Payment resource

Update, validate or cancel a payment

POST https://{domain}.biapi.pro/2.0/payments/{paymentId}

This is used in the following flows:

➖ Cancelling a payment ➖ Implementing your own payment validation webview (advanced)

Request body: one of the following objects.

➖PaymentValidateRequest object ➖PaymentResumeRequest object ➖PaymentSubmitFieldValuesRequest object ➖PaymentSubmitPSUValidationRequest object ➖PaymentConfirmRequest object ➖PaymentCancelRequest object

Query Parameters

Name	Type	Description
show_sensitive	Boolean	Set to true to return sensitive fields from identities. Defaults to false.

200: OK Payment updated

Response body: Payment resource

Generate a payment-scoped token

POST https://{domain}.biapi.pro/2.0/payments/{paymentId}/scopedtoken

This endpoint requires a payment token with the scope payments:admin.

Request body: PaymentTokenRequest object

200: OK Token issued

Response body: PaymentTokenResponse object

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	corporatenon_profit	French SIREN company identification number.
incorporation_number	corporatenon_profitgovernment	Incorporation number.
euid	corporatenon_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.
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.
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).

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.
email	String	Sensitive	Email address. Maximum 255 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

{
    "kind": "individual",
    "first_name": "Jean",
    "last_name": "Dupont",
    "birth_city": "Paris",
    "birth_country": "FR",
    "birth_date": "1990-12-31"
}

Individual without birth data

{
    "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"
}

Company

{
    "kind": "corporate",
    "org_name": "Powens",
    "org_legal_status": "SAS",
    "org_hq_address": "84 RUE BEAUBOURG\n75003 PARIS 3\nFRANCE",
    "scheme_name": "siren",
    "identification": "749867206"
}

Non-profit

{
    "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	Required	The beneficiary information for the payment instruction.
beneficiary_identity	Identity object	Optional	Detailed identity information about the beneficiary.
start_date	Date	Conditional	The starting date for periodic transfers. Required if execution_date_type is periodic.
end_date	Date	Optional	The ending date for periodic transfers. If none is provided, the transfer will be executed indefinitely until stopped manually.
frequency	Execution Frequency string	Conditional	The frequency of execution for periodic transfers. Required if execution_date_type is periodic.
state	PaymentInstructionState string or null	Computed	The current state of the instruction.

Payment resource

Property	Type	Description
id	Integer	The ID of the created payment request.
state	PaymentState string	The state of the payment request.
state_detail	PaymentStateDetail value	The state detail of the payment request.
action	PaymentAction string or null	The current action taking place on 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.
fields	Dictionary of PaymentField objects	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	(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 payment validation webview instead.
client_state	String or null	(Deprecated) The optional state to add to the final callback URL. Prefer using the state parameter to the payment validation webview instead.
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.