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 | Date | Minimal date (inclusive). |
max_date | Date | Maximal date (exclusive). |
connector_uuid | String | Filter by connector UUID. |
id_connector | Integer | Filter by connector ID. |
id_connector_source | Integer | Filter by connector source ID. |
state | String | Filter by |
error_code | String | Filter by |
bank_payment_id | String | Filter by bank payment ID. |
website | String | Filter by website field value. |
payer_identification | String | Filter by |
beneficiary_identification | String | Filter by |
reference_id | String | Filter by instruction reference ID |
execution_date_type | String | Filter by |
order_by | String | Order the payments by the specified field. Value can be |
country | String | Filter by country. Several countries can be provided, separated by commas. |
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. |
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. |
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. |
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
Response body: PaymentTokenResponse 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
Name | Type | Required | Description |
---|---|---|---|
all | Boolean | No | Set to true to return incompatibilities for all connectors, including hidden ones. |
Response body: Array of PaymentConnectorIncompatibility resource
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 |
---|---|---|---|
| Integer | Optional | (Deprecated) ID of the bank connector to pre-select for the payment.
This property is deprecated in favor of |
| String | Optional | UUID of the bank connector to pre-select for the payment. The bank connector must be eligible to payments creation. |
| String | Required | The redirect URL to use when building the validation URL. The provided URL must not contain any query parameter, rely on the |
| String | Optional | Optional value that will be added as a |
| Array of PaymentInstruction | Required | The payment information. |
| Identity object | Optional | Detailed identity information about the entity initiating the payment. |
| 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. |
| 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 |
---|---|---|---|
| Integer | Optional | (Deprecated) ID of the bank connector to use to initiate the payment.
This property is deprecated in favor of |
| 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. |
| String | Required | Name of the mechanism to use to validate the payment.
Compatibility note: this is set to |
| String dictionary | Conditional | Encrypted static fields to provide for the payment. See end-to-end encryption for more details on how to encrypt. |
| String | Conditional | (Deprecated) Value to provide for the payment's |
| 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. |
| String | Required | URL to which to redirect the end user after |
| Boolean | Optional | Provide |
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 |
---|---|---|---|
| Boolean | Required | Must be set to |
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 |
---|---|---|---|
| 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 |
---|---|---|---|
| Boolean | Required | Must be set to |
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 |
---|---|---|---|
| Boolean | Required | Must be set to |
PaymentCancelRequest object
Property | Type | Presence | Description |
---|---|---|---|
| String | Required | The redirect URL to use when building the validation URL. The provided URL must not contain any query parameter, rely on the |
| String | Optional | Optional value that will be added as a |
| Boolean | Required | Provide |
PaymentTokenRequest object
Property | Type | Presence | Description |
---|---|---|---|
| Scope string or array | Required | The |
Responses
PaymentListResponse object
Property | Type | Description |
---|---|---|
| Array of Payment objects | List of payments. |
PaymentTokenResponse object
Property | Type | Description |
---|---|---|
| String | The generated service token. |
| String | The attributed permissions for this service token. |
| Integer | The payment ID linked to the token. |
Code sets
IdentityKind values
Value | Description |
---|---|
| Individual (personne physique). |
| Corporate entity (entreprise). |
| Non-profit (association). |
| Government agency (agence gouvernementale). |
IdentitySchemeName values
Value | Relevant identity kind | Description |
---|---|---|
| individual | National identification number. |
| individual | Passport number. |
| individual | Alien registration number. |
| corporatenon_profit | French SIREN company identification number. |
| corporatenon_profitgovernment | Incorporation number. |
| corporatenon_profit | European Unique Identifier. |
| non_profit | French RNA non profit organization identification number. |
PaymentAccountSchemeName values
Value | Description |
---|---|
| International Bank Account Number. |
| United Kingdom local account number. |
ExecutionDate values
Value | Description |
---|---|
| The payment is executed on the first business day of the bank. For most banks, this excludes the current day. |
| The payment will be executed on the given execution date. |
| 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. |
| 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 |
---|---|
| Every day. Note that most banks do not support this frequency. |
| Every week. |
| Every two weeks. |
| Every month. |
| Every two months. |
| Every three months. |
| Every four months. |
| Every six months. |
| Every year. |
PaymentState values
Value | Kind | Description |
---|---|---|
| Intermediate state | The payment request was registered, but not yet validated. |
| Intermediate state | The payment request was validated and initialized with the bank. The |
| Intermediate state | The payment request has been validated on the bank website, but execution has not been confirmed yet. |
| Final state | The payment request has been rejected by the bank or the user. The |
| Final state | The payment has been executed and confirmed by the bank. |
| 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. |
| 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 |
| 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. |
| The payment is currently being cancelled, and a user action is provided in the |
PaymentAction values
Value | Description |
---|---|
| The end user must complete a redirect flow, for which the URL is present in |
| 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. |
| Values for one or more fields are required from the end user. Such fields are provided in |
| A confirmation is required from the client. |
| A validation is required from the end user. |
PaymentErrorCode values
Value | Description |
---|---|
| Identification of the emitter account is invalid, or transfer emission is not possible. |
| The balance of the emitter account is too low. |
| The amount of the payment request is invalid or out of the authorized bounds. |
| The currency of the payment request is invalid or unsupported. |
| The execution date of the payment request is invalid or out of the supported bounds. |
| The beneficiary identification is invalid or unsupported. |
| The label of the payment request does not match the constraints enforced by the bank. |
| The request was aborted by the bank for regulatory reason (e.g. fraud detection). |
| The request was aborted because the end-user failed to identify with the bank. |
| The payment request expired without any interaction with the end-user. |
| The payment request was rejected by the bank without any reason. |
| The payment was explicitly cancelled by the end-user. |
| The payment has been cancelled through the API. |
| The payment confirmation was refused by the client. |
| The bank sent an error message to the user. |
| The request contains invalid data. |
| An action is needed on the website by the user. |
| The connector is currently unavailable, typically happens if the bank's interface is unreachable. |
| 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 |
---|---|---|
| Intermediate state | The instruction's execution has not been confirmed yet. |
| Final state | The instruction has been rejected by the bank or the user. The |
| Final state | The instruction has been executed and confirmed by the bank. |
| 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 |
---|---|
| The field should be displayed as a simple text box. |
| The field should be displayed as a selection widget. |
PaymentConnectorIncompatibilityType values
Value | Description |
---|---|
| The connector is incompatible with the payment. |
| The connector is compatible but some of the payment properties may cause a rejection. |
PaymentConnectorIncompatibilityCode values
Value | Description |
---|---|
| 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. |
| The payment amount is below the minimum amount required by this connector for this payment type. |
| The number of instructions for this bulk payment is above the maximum number of instructions allowed by the connector. |
| The payment execution date is too far for the connector. |
| The payment execution date is not far enough for the connector. |
| The payment type is not supported by the connector. |
| The periodic payment frequency is not supported by the connector. |
| This connector does not support bulk payments. |
| The payment beneficiary identification scheme is not supported by the connector. |
| The connector does not allow providing a payer account. |
| The payment execution date is not allowed by the connector. |
| The payment currency is not supported by the connector. |
| The beneficiary needs to be trusted by the payer account. |
Data structures
PaymentFieldValue object
Property | Type | Description |
---|---|---|
| String | Human-readable description of the choice. |
| String | Technical value to pass to select the value. |
PaymentField object
Property | Type | Description |
---|---|---|
| String | Technical name of the field, for the client to use to identify the corresponding value. |
| PaymentFieldType string | Type of field, to use to display the correct input widget to the end user. |
| String | Human-readable description of the field. |
| String or null | Optional PCRE-compatible pattern for |
| Boolean | Whether the field is required or not. |
| Array of PaymentFieldValue objects | Values to choose from for |
Resources
PaymentAccount resource
Property | Type | Presence | Description |
---|---|---|---|
| PaymentAccountSchemeName string | Required | The payment account number type. |
| String | Required | The payment account number, of type matching the given |
| String | Required | Display name of the payment account. |
| String | Optional | The BIC of the payment account (when the |
merchant_scheme_name
and merchant_identification
have been replaced by the use of payer_identity
and beneficiary_identity
.
Identity resource
Property | Type | Options | Description |
---|---|---|---|
| Integer | ID of the user related to this payment. If provided, this must be an existing User. | |
| IdentityKind string | The kind of entity the identity is linked to.
If not provided, this property is set to | |
| String | External reference assigned by the customer to the entity defined by this Identity. Maximum 255 characters. | |
| String | Sensitive | First name. Maximum 255 characters. |
| String | Sensitive | Last name. Maximum 255 characters. |
| String | Sensitive | City of birth. |
| String | Sensitive | Country of birth, as an ISO 3166-1 alpha-2 code. |
| Date | Sensitive | Date of birth. |
| String | Sensitive | Nationality. |
| String | Sensitive | Postal address. Maximum 512 characters. |
| String | Sensitive | Email address. Maximum 255 characters. |
| IdentitySchemeName string | Sensitive | Identification number type. Required if |
| String | Sensitive | Identification number. Maximum 255 characters. |
| String | Sensitive | Issuer of the identification. Maximum 255 characters. |
| String | Sensitive | Identity text of the first ultimate owner of the entity. |
| String | Sensitive | Identity text for additional ultimate owners of the entity. |
| Boolean | Sensitive | Is the person politically exposed. Defaults to |
| String | Entity name of the organization, required if | |
| String | Legal status of the organization, required if | |
| String | Sensitive | Headquarters address of the organization, required if |
| String | Sensitive | Business address of the organization, required if |
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 |
---|---|---|---|---|
| N/A | Mandatory | Mandatory | Mandatory |
| Mandatory | N/A | N/A | N/A |
| Mandatory | N/A | N/A | N/A |
| Recommended | N/A | N/A | N/A |
| Recommended | N/A | N/A | N/A |
| Recommended | N/A | N/A | N/A |
| N/A | Recommended | Recommended | Recommended |
| N/A | Mandatory | Mandatory | Mandatory |
| N/A | Mandatory | Mandatory | Mandatory |
Examples identities are the following:
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.
Property | Type | Presence | Description |
---|---|---|---|
| String | Optional | The optional end-to-end identifier for the instruction. If not provided, a random identifier is generated (maximum 31 characters). |
| Number | Required | The amount of the payment. |
| String | Required | The currency code of the payment amount, a per ISO 4217. |
| String | Required | Label of the payment. |
| ExecutionDate string | Required | The execution date type of the payment. |
| Date | Conditional | The execution date for the transfer, only for |
| PaymentAccount object | Required | The beneficiary information for the payment instruction. |
| Identity object | Optional | Detailed identity information about the beneficiary. |
| Date | Conditional | The starting date for |
| Date | Optional | The ending date for |
| Execution Frequency string | Conditional | The frequency of execution for |
| PaymentInstructionState string or null | Computed | The current state of the instruction. |
Payment resource
Property | Type | Description |
---|---|---|
| Integer | The ID of the created payment request. |
| PaymentState string | The state of the payment request. |
| PaymentStateDetail value | The state detail of the payment request. |
| PaymentAction string or null | The current action taking place on the payment request. |
| PaymentErrorCode string or null | The error code of the payment request. |
| String or null | Error message in case of an error. |
| Dictionary of PaymentField objects | Fields to provide to the payment for |
| String or null | URL to which to redirect the end user for |
| Integer or null | (Deprecated) ID of the bank connector to use to initiate the payment.
This property is deprecated in favor of |
| UUID or null | UUID of the bank connector to use to initiate the payment. |
| String or null | The chosen validation mechanism for the payment. |
| DateTime | Creation date of the payment request. |
| 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 |
| String or null | (Deprecated) The optional state to add to the final callback URL.
Prefer using the |
| PaymentAccount object | The payer information for the payment. |
| Array of PaymentInstruction objects | The list of payment instructions. |
| Identity object | Detailed identity information about the payer/debtor. |
PaymentConnectorIncompatibility resource
Property | Type | Description |
---|---|---|
| Whether the payment is incompatible with the connector, or if it's simply a warning. | |
| Array of PaymentConnectorIncompatibilityReason objects | The exhaustive list of reasons causing warnings or incompatibilities. |
PaymentConnectorIncompatibilityReason resource
Property | Type | Description |
---|---|---|
| The compatibility code. Indicates the nature of the incompatibility or warning. | |
| Whether the reason caused a warning or incompatibility. | |
| string | Technical description of the incompatibility code. |
| 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 |
| 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 |
Last updated