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
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:
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.
Payment resource
PaymentConnectorIncompatibility resource
PaymentConnectorIncompatibilityReason resource
Last updated