Mandate statuses

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

This diagram shows how a mandate transitions between statuses:

The status of successful mandates transition in the following order:

1. authorization_required
2. authorizing
3. authorized
4. revoked or failed

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.