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.

authorization_requiredThe mandate has been created successfully and no further action has been taken.
authorizingThe 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.
authorizedThe end user has completed the authorization journey and the mandate has successfully completed its authorization flow.
failedThe mandate could not be authorized. Either the mandate parameters were invalid, or the user did not successfully complete the consent flow.
revokedThe 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:

  1. authorization_required
  2. authorizing
  3. authorized
  4. 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.