Reauthorization

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:

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

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": {
        "code": "USER_INTERACTION_REQUIRED",
        "userInteractionUrl": "https://secure.stitch.money/connect/payment-request/48abfea6-cb5d-48c0-ac1e-c8983cbaee3f",
        "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.

Field	Description	Type
code	Constant value "USER_INTERACTION_REQUIRED"	Error Code
userInteractionUrl	A url that you'll need to redirect your users to so that they can complete reauthorization	Url
id	A unique identifier that can be used to query the results of the reauthorization request	ID

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 https://ide.stitch.money/, and thus the full URL presented to a user if they encountered the example error above (from the Stitch IDE) would be:

https://secure.stitch.money/connect/authorization/48abfea6-cb5d-48c0-ac1e-c8983cbaee3f?redirect_uri=https%3A%2F%2Fstitch.money%2Fide%2F

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.

Field	Description	Type
id	The unique id of the payment request the reauthorization is for	ID
status	The value "complete" if successful, "closed" if the user clicked close in the UI, or "failed" if something went wrong when attempting the payment	String
externalReference	The 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 parameters	String

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:

Open in IDE ↗

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.

Open in IDE ↗

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.