Payments

Last updated 9 months ago

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

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

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

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:

Request body: one of the following objects.

Query Parameters

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

Response body: Array of PaymentConnectorIncompatibility resource

Webhooks

Payment state updated

A PAYMENT_STATE_UPDATED webhook is emitted after a payment state has been updated.

Webhook request body: Payment resource

The PAYMENT_STATE_UPDATED event data will be triggered for every payment state change.

If your domain was created before 2024/09/13, the old behaviour of the webhook is used instead.

The PAYMENT_STATE_UPDATED event data will only be sent when the payment state is updated in a non-interactive operation. This corresponds to two scenarios:

The payment request has been validated by the PSU, and during a regular background check on the payment with the bank, we have detected a change in its state.
The payment request has been validated by the PSU, but they have not been redirected to our callback (network issues, browser closed too early, crash, anomalous behavior of the bank's interface, ...). This case falls back to background checks, as described above.

Please note that if the validation flow succeeds and the new state is communicated in your callback, the webhook will not be triggered until a later update.

To switch to the new behaviour of the webhook, please set the configuration key payment.state_updated_webhook.systematic to '1', or contact the support team.

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.

PaymentValidateRequest object

This section is only useful if you're implementing your own webview; see the corresponding guide for more details.

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.

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.

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.

PaymentConfirmRequest object

This section is only useful if you're confirming payments manually.

This is the expected payload when the current action is confirm.

PaymentCancelRequest object

PaymentTokenRequest object

Responses

PaymentListResponse object

PaymentTokenResponse object

Code sets

IdentityKind values

IdentitySchemeName values

PaymentAccountSchemeName values

ExecutionDate values

The periodic date type is not available by default. Please check with your commercial contact to enable this feature.

ExecutionFrequency values

PaymentState values

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

PaymentAction values

PaymentErrorCode values

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

PaymentFieldType values

PaymentConnectorIncompatibilityType values

PaymentConnectorIncompatibilityCode values

Data structures

PaymentFieldValue object

PaymentField object

Resources

PaymentAccount resource

merchant_scheme_name and merchant_identification have been replaced by the use of payer_identity and beneficiary_identity.

Identity resource

Fields marked sensitive are only returned by the API if the show_sensitive query parameter is used.

Required properties are the following:

Examples identities are the following:

{
    "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": "corporate",
    "org_name": "Powens",
    "org_legal_status": "SAS",
    "org_hq_address": "84 RUE BEAUBOURG\n75003 PARIS 3\nFRANCE",
    "scheme_name": "siren",
    "identification": "749867206"
}

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

API endpoints

List payments

Query Parameters

Create a payment

Query Parameters

Get a payment

Query Parameters

Update, validate or cancel a payment

Query Parameters

Generate a payment-scoped token

List a payment connector incompatibilities

Query Parameters

Webhooks

Payment state updated

Request payloads

PaymentInitRequest object

PaymentValidateRequest object

PaymentResumeRequest object

PaymentSubmitFieldValuesRequest object

PaymentSubmitPSUValidationRequest object

PaymentConfirmRequest object

PaymentCancelRequest object

PaymentTokenRequest object

Responses

PaymentListResponse object

PaymentTokenResponse object

Code sets

IdentityKind values

IdentitySchemeName values

PaymentAccountSchemeName values

ExecutionDate values

ExecutionFrequency values

PaymentState values

PaymentStateDetail values

PaymentAction values

PaymentErrorCode values

PaymentInstructionState values

PaymentFieldType values

PaymentConnectorIncompatibilityType values

PaymentConnectorIncompatibilityCode values

Data structures

PaymentFieldValue object

PaymentField object

Resources

PaymentAccount resource

Identity resource

PaymentInstruction resource

Payment resource

PaymentConnectorIncompatibility resource

PaymentConnectorIncompatibilityReason resource