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

NameTypeDescription

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

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.

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

NameTypeDescription

show_sensitive

Boolean

Set to true to return sensitive fields from identities. Defaults to false.

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

NameTypeDescription

show_sensitive

Boolean

Set to true to return sensitive fields from identities. Defaults to false.

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

NameTypeDescription

show_sensitive

Boolean

Set to true to return sensitive fields from identities. Defaults to false.

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

Note that using the show_sensitive parameter requires a payment token with scope payments:admin or payments:allow-sensitive.

List a payment connector incompatibilities

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

Query Parameters

NameTypeRequiredDescription

all

Boolean

No

Set to true to return incompatibilities for all connectors, including hidden ones.

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.

PropertyTypePresenceDescription

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

Required

The payment information.

operator_identity

Identity object

Optional

Detailed identity information about the entity initiating the payment.

payer

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.

PropertyTypePresenceDescription

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

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.

PropertyTypePresenceDescription

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.

PropertyTypePresenceDescription

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.

PropertyTypePresenceDescription

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.

PropertyTypePresenceDescription

confirm

Boolean

Required

Must be set to true if the payment should be confirmed, or false otherwise.

PaymentCancelRequest object

PropertyTypePresenceDescription

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

PropertyTypePresenceDescription

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

PropertyTypeDescription

payments

Array of Payment objects

List of payments.

PaymentTokenResponse object

PropertyTypeDescription

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

ValueDescription

individual

Individual (personne physique).

corporate

Corporate entity (entreprise).

non_profit

Non-profit (association).

government

Government agency (agence gouvernementale).

IdentitySchemeName values

ValueRelevant identity kindDescription

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

ValueDescription

iban

International Bank Account Number.

sort_code_account_number

United Kingdom local account number.

ExecutionDate values

ValueDescription

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

ValueDescription

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

ValueKindDescription

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

ValueDescription

(null)

No state detail.

cancelling

The payment is currently being cancelled, and a user action is provided in the action field .

PaymentAction values

ValueDescription

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

ValueDescription

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.

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.

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

ValueKindDescription

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

ValueDescription

text

The field should be displayed as a simple text box.

list

The field should be displayed as a selection widget.

PaymentConnectorIncompatibilityType values

ValueDescription

incompatible

The connector is incompatible with the payment.

warning

The connector is compatible but some of the payment properties may cause a rejection.

PaymentConnectorIncompatibilityCode values

ValueDescription

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.

Data structures

PaymentFieldValue object

PropertyTypeDescription

label

String

Human-readable description of the choice.

value

String

Technical value to pass to select the value.

PaymentField object

PropertyTypeDescription

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

Array of PaymentFieldValue objects

Values to choose from for list fields.

Resources

PaymentAccount resource

PropertyTypePresenceDescription

scheme_name

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

PropertyTypeOptionsDescription

id_user

Integer

ID of the user related to this payment. If provided, this must be an existing User.

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

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

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:

PropertyIndividualCorporateNon-profitGovernment

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:

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

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"
      }
    }
  ]
}
PropertyTypePresenceDescription

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

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

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

Conditional

The frequency of execution for periodic transfers. Required if execution_date_type is periodic.

state

Computed

The current state of the instruction.

Payment resource

PropertyTypeDescription

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

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

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.

PaymentConnectorIncompatibility resource

PropertyTypeDescription

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.

PaymentConnectorIncompatibilityReason resource

PropertyTypeDescription

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.

Last updated