Mandate statuses

Learn how mandates progress through their lifecycle.

As a mandate goes through its lifecycle, it will transition through multiple mandate statuses. Below are the definitions for each mandate status.

Status	Definition
`authorization_required`	The mandate has been created successfully and no further action has been taken.
`authorizing`	The end user has started the authorization journey by interacting with the Hosted Payments Page or the client's UI and have not completed the journey yet.
`authorized`	The end user has completed the authorization journey and the mandate has successfully completed its authorization flow.
`failed`	The mandate could not be authorized. Either the mandate parameters were invalid, or the user did not successfully complete the consent flow.
`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.

Mandate statuses transition in the following order:

authorization_required
authorizing
authorized
revoked

Mandates with a status of authorisation_required, authorizing, or authorized can also transition 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 2 months ago