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.
Definition | Status |
---|---|
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
authorization_required
authorizing
authorized
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 infailure_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
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
failure_stage
The status of the payment at the time of the failure.
Possible values:
authorization_required
authorizing
authorized
failed_at
failed_at
The time of failure, in RFC-3339 format.
Updated 7 months ago