Payments
Last updated
Last updated
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
By default, payments are ordered by register_date
.
Name | Type | Description |
---|---|---|
Response body: PaymentListResponse object
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
Response body: Payment resource
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.
Response body: Payment resource
POST
https://{domain}.biapi.pro/2.0/payments/{paymentId}
This is used in the following flows:
Request body: one of the following objects.
Response body: Payment resource
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
.
GET
https://{domain}.biapi.pro/2.0/payments/{paymentId}/incompatibilities
Response body: Array of PaymentConnectorIncompatibility resource
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.
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.
This section is only useful if you're implementing your own webview; see the corresponding guide for more details.
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
.
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
.
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
.
This section is only useful if you're confirming payments manually.
This is the expected payload when the current action is confirm
.
The periodic
date type is not available by default. Please check with your commercial contact to enable this feature.
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.
Forward compatibility requirement: additional codes may be added in the future. When implementing error handling, always fallback to a generic case for unknown values.
merchant_scheme_name
and merchant_identification
have been replaced by the use of payer_identity
and beneficiary_identity
.
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:
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.
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
PaymentValidateRequest object PaymentResumeRequest object PaymentSubmitFieldValuesRequest object PaymentSubmitPSUValidationRequest object PaymentConfirmRequest object PaymentCancelRequest object
Name | Type | Description |
---|---|---|
Name | Type | Required | Description |
---|---|---|---|
Property | Type | Presence | Description |
---|---|---|---|
Property | Type | Presence | Description |
---|---|---|---|
Property | Type | Presence | Description |
---|---|---|---|
Property | Type | Presence | Description |
---|---|---|---|
Property | Type | Presence | Description |
---|---|---|---|
Property | Type | Presence | Description |
---|---|---|---|
Property | Type | Presence | Description |
---|---|---|---|
Property | Type | Presence | Description |
---|---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Value | Description |
---|---|
Value | Relevant identity kind | Description |
---|---|---|
Value | Description |
---|---|
Value | Description |
---|---|
Value | Description |
---|---|
Value | Kind | Description |
---|---|---|
Value | Description |
---|---|
Value | Description |
---|---|
Value | Description |
---|---|
Value | Kind | Description |
---|---|---|
Value | Description |
---|---|
Value | Description |
---|---|
Value | Description |
---|---|
Property | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | Presence | Description |
---|---|---|---|
Property | Type | Options | Description |
---|---|---|---|
Property | Individual | Corporate | Non-profit | Government |
---|---|---|---|---|
Property | Type | Presence | Description |
---|---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|