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.

DefinitionStatus
The mandate has been created successfully and no further action has been taken.authorization_required
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.authorizing
The end user has completed the authorization journey and the mandate has successfully completed its authorization flow.authorized
The mandate could not be authorized. Either the mandate parameters were invalid, or the user did not successfully complete the consent flow.failed
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.revoked

The statuses will transition in the following order

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

Stages 1, 2 and 3 may also transition to failed.

🚧

Failed Status

Any type of failure will cause the mandate to transition into failed status. The reason for the failure can be found in failure_reason field in the json resource once the mandate is fetched.

More about failed mandates

You can find out more details about the failure by investigating two fields on a mandate resource. A mandate resource upon failure will look like this.

{
  .
  .
  .
  "status": "failed",
  "failed_at": "2021-12-25T15:00:00.000Z",
  "failure_reason": "provider_rejected",
  "failure_stage": "authorizing",
  .
  .
  .
}

🚧

Failure stage

You can find out at which point of a status lifecycle the mandate has failed by investigating the field named failure_stage. This field can only be one of the statuses that can be observed before failure.

🚧

Failure reason

As we learn more about provider behaviors, we will be continuously updating the list of possible reasons returned on this field. You shouldn't expect this field to always contain one of the listed values. Make sure to handle any undocumented values as a generic failure reason.

failure_reason

The reason of the mandate failure.

Possible Values:

  • authorization_failed: The user failed to authorize the VRP consent.
  • provider_error: The provider had an error unknown to us.
  • invalid_request: The mandate request was invalid.
  • internal_server_error: An error occurred in our internal stack.
  • unknown_error: An unknown error occurred.

failure_stage

The status of the payment at the time of the failure.

Possible values:

  • authorization_required
  • authorizing
  • authorized

failed_at

The time of failure, in RFC-3339 format.