Skip to main content


One error that is imperative to handle, and hence deserved its own chapter is the REAUTHORIZATION_REQUIRED error.

Banks generally have more stringent security policies than financial platforms or applications do. Some require that users reauthorize access when logging in. Many require reauthorization when performing sensitive actions such as increasing limits, adding beneficiaries, or making once-off payments.

Reauthorization typically requires that the user perform some form of multifactor authentication (MFA). Stitch automatically handles MFA when the user initially links their account. However, when making queries after linking, Stitch will eventually need to create a new banking session, as bank portals enforce a finite session duration.

Below you can see the standard flow, where no MFA is required:

Stitch API no MFA

Below you can now see the flow, where MFA is required, and a reauthorization needs to be performed:

Stitch API MFA

For the banks that require reauthorization during login, the Stitch API is not able to automatically recreate sessions until the user is again present. This is where USER_INTERACTION_REQUIRED comes in.

Structure of a Reauthorization Error

A reauthorization error will look like the JSON response body below:

"errors": [
"message": "Reauthorization required to continue payment.",
"locations": [
"line": 2,
"column": 3
"path": ["userInitiatePayment"],
"extensions": {
"userInteractionUrl": "",
"id": "dWkvNDhhYmZlYTYtY2I1ZC00OGMwLWFjMWUtYzg5ODNjYmFlZTNm"
"data": {
"userInitiatePayment": null

As you can see, there are a few fields that are present in the extensions object. Each field is described in the table below. In the next sections, we'll see how to take these parameters and use them to complete reauthorization.

codeConstant value "USER_INTERACTION_REQUIRED"Error Code
userInteractionUrlA url that you'll need to redirect your users to so that they can complete reauthorizationUrl
idA unique identifier that can be used to query the results of the reauthorization requestID

Building the Reauthorization URL

To complete reauthorization, you'll need to direct your user to the userInteractionUrl with one of your whitelisted redirect URIs added as a query string parameter with the key redirect_uri.

The URL must be URL encoded, and for security purposes must exactly match the value provided to Stitch.

For the Stitch IDE clients, the currently configured redirect URI is, and thus the full URL presented to a user if they encountered the example error above (from the Stitch IDE) would be:

Handling the Reauthorization Callback

Once the user completes or cancels reauthorization, they'll be redirected back to the redirect_uri. The redirect uri will include three query string parameters.

idThe unique id of the payment request the reauthorization is forID
statusThe value "complete" if successful, "closed" if the user clicked close in the UI, or "failed" if something went wrong when attempting the paymentString
externalReferenceThe value that was provided to the externalReference field when running the userInitiatePayment mutation. If the value wasn't part of the request variables, then this field will be omitted from these query parametersString

Querying the Results of Reauthorization

You can also use the id from the original GraphQL error response to poll the reauthorization status. This can be done using the node query:

Simulating Reauthorization with Test Users

Test users

Test users for Standard Bank and Capitec support simulating the reauthorization process.

Triggering reauthorization for these users can be done using via the API using the mutation below. Be sure to select the appropriate test user.

The next API call made will fail with a reauthorization error. You can complete the reauthorization using the OTP returned by the mutation. This OTP will also be present in SafeLink.