Payment status

Every payment, whether it was started with Start a payment or with Start Request to Pay, carries a status field that describes how far it got in the process. You can read it at any time with Get a payment, or for a whole Business Registry with Get the payments.

These are the only values the field can assume.

status	Meaning	Final
started	The payment has been created on A-Cube, but the payment link has not been opened yet. Nothing has been sent to the Financial Institution.	No
requested	The payment link has been opened: the payment session has been created and the payer has been redirected to the Financial Institution, where the authorisation is still pending.	No
submitted	The payer authorised the payment at the Financial Institution, which accepted it, and came back to A-Cube.	No
waiting	The outcome of the payment is not known yet: either the Financial Institution did not report it, or the payer came back to A-Cube before the authorisation was completed. The final outcome is notified later.	No
confirmed	The payment has been matched with a transaction on the account statement.	Yes
failed	The payment will not be executed.	Yes

Only confirmed proves that the money actually moved, because it is the result of matching the payment with the account statement: a payment still in submitted is not, on its own, evidence that the transfer did not go through.

The payment link

The payment link returned when the payment is created can be opened more than once, for instance after a double click, or if the payer closes the page and opens the link again: it always leads to the same payment session at the Financial Institution, so the payer cannot authorise the same payment twice. Once the payment is submitted, waiting, confirmed or failed, the link can no longer be used to pay.

Where the payer is redirected

When the payer comes back from the Financial Institution:

• if the payment is submitted or waiting, the payer is redirected to the returnUrl given when the payment was created, or shown a page with the details of the payment when no returnUrl was given;
• if the payment is failed, the payer is redirected to the errorUrl, or shown an error page when no errorUrl was given.

Reloading that page leads to the same destination again, without changing the payment.

Since the payer reaches the returnUrl both when the payment is submitted and when it is waiting, do not rely on the redirection alone: read the status of the payment, or use the webhooks.

Failed payments

A payment ends up in failed either because the Financial Institution rejected it, the payer did not complete it or it expired, or because the payment session could never be created in the first place. It can fail also when the amount exceeds the limits configured for your integration, in which case the payer gets a 422 Unprocessable entity on the payment link.

Failed payments carry two extra fields describing what went wrong.

{
  "uuid": "11ce6377-ff28-4c7c-842f-ba500fb94759",
  "status": "failed",
  "errorClass": "InsufficientFunds",
  "errorMessage": "Insufficient funds.",
  "system": "sepa",
  "amount": "345.67",
  "currencyCode": "EUR",
  "description": "Order nr. 12345",
  "endToEndId": "A+C000001",
  "createdAt": "2023-03-30T07:51:34Z"
}

errorClass tells you why the payment failed.

errorClass	Meaning
PaymentFailed	The Financial Institution rejected the payment, or the payment expired before being completed.
InsufficientFunds	The account does not have enough funds.
PaymentValidationError	The Financial Institution did not accept the payment data, for instance the currency.
Unfinished	The payer cancelled or abandoned the payment.
InvalidCredentials	The payer entered wrong credentials or a wrong one-time password.
AccessDenied	The payer did not grant access to the account.
Timeout	The Financial Institution did not answer in time.
ProviderError	The Financial Institution is unavailable or returned an error.
GenericError	Any other error.

New values may be added in the future: handle any value you do not know as GenericError.

errorMessage carries the description reported for that specific failure. It is free text, which may be in the language of the payer, so use it for display or troubleshooting only, never to decide how to handle the failure.

Both fields are omitted when the payment did not fail. errorMessage can also be omitted for a failed payment, when only the class of the error is known.

Webhooks

If you configured a payment webhook, you are notified when the payment becomes:

• submitted and confirmed, with success: true;
• failed, with success: false, together with errorClass and errorMessage.

No notification is sent when the payment becomes waiting: you will be notified as soon as its final outcome is known.