Mandate statuses
Learn how mandates progress through their lifecycle.
As a mandate goes through its lifecycle, it will transition through multiple statuses. Below are the definitions for each mandate status.
Status | Meaning | Terminal status? |
---|---|---|
authorization_required | The mandate has been created successfully and no further action has been taken. | No |
authorizing | The end user has started the authorization journey by interacting with the hosted payment page or the client's UI and has not completed the journey yet. | No |
authorized | The end user has completed the authorization journey and the mandate has successfully completed its authorization flow. | No |
revoked | The mandate was revoked after being authorized, either through by the client revoking the mandate on behalf of the user, or by the user revoking it via their bank. | Yes |
failed | The mandate could not be authorized. Either the mandate parameters were invalid, or the user did not successfully complete the consent flow. | Yes |
This diagram shows how a mandate transitions between statuses:
The status of successful mandates transition in the following order:
authorization_required
authorizing
authorized
revoked
Mandates with a status of authorisation_required
or authorizing
can also transition directly to failed
.
Failed mandates
A variety of different reasons can cause a mandate to transition to the failed
status. To help you identify when and how a mandate failed, you can check the failed_at
,failure_reason
and failure_stage
objects within the json resource when you fetch the mandate.
Here is an example of the JSON resource for a failed mandate:
{
//...
"status": "failed",
"failed_at": "2021-12-25T15:00:00.000Z",
"failure_reason": "provider_rejected",
"failure_stage": "authorizing",
//...
}
Time of failure
The failed_at
object tells you the time that the mandate transitioned to failed
at, in RFC-3339 format.
Failure reasons
You can find the reason why a mandate failed within the failure_reason
object. Example reasons why a mandate can fail are:
authorization_failed
provider_error
provider_rejected
internal_server_error
invalid_sort_code
invalid_request
expired
unknown_error
However, your implementation should be able to handle other values, as we may add more failure reasons in the future.
Failure stages
You can find which status a mandate had before it failed in the failure_stage
object. The possible values are authorisation_required
, authorizing
, or authorized
.
Updated 4 months ago