One error that is imperative to handle, and hence deserved its own chapter is the
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:
"message": "Reauthorization required to continue payment.",
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.
|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
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:
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.
|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 ||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
Simulating Reauthorization with 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.