How do you go from a user who has chosen the bank they are willing to connect to having the bank account data available to you? This guide will help you understand where your users are in the process.
The guide assumes you are familiar with the steps as described in the quickstart guide and describes what happens between steps 4 and 5, when you have redirected your user to GC but we have not yet redirected them back to us.
Let's start with requisition statuses that occur in the normal successful authorisation flow:
CR - not yet redirected, flow not started
GC - still on the GoCardless screen (has not clicked “Agree” and has not been redirected to bank)
UA* - on the bank's page, logging in
GA* - on the bank's page, logged in, confirming access
LN - done and ready, you will see accounts under the requisition and can access data. At this, and only at this point does the requisition become billable.
* depending on the bank you might not see the GA status at all, so we recommend to think of the UA and GA statuses as the same
SA - an optional status. The status means that you are using the account selection feature and the user is in our screen, choosing which of their accounts to grant you access to.
RJ - consider this an error status - either you are using the SSN verification feature and the SSN did not match, or the user has entered their login credentials or one-time password wrong. You can restart the flow from a new requisition. (the rejected one is not billable) Note that not all banks will go into this status in the latter case, many will just stay in UA or GA.
EX - you no longer have access because the End User Agreement has expired. Note that we will only change the status to EX if you have tried to access one of the accounts under the requisition, this is because we never process any resources unless you are requesting them, and the same goes for transactions, balances and details - we only fetch data form the bank when you make the API call for the resource, synchronously. Can an Expired requisition be billable? Only for the period when it was not expired yet - if it expired on the 2nd of November it will still be counted towards your use in November, but not in December.
How long does the authorisation flow take?
From the moment the user has been redirected to us, to the moment we redirect them back to you, the times in seconds for successful connections are:
median: 74
90th percentile: 163
95th percentile: 224
98th percentile: 355
99th percentile: 581
In other words, half the users are done in 1 minute 15 seconds or less, while one in a hundred will take 10 minutes, either because their doorbell rang mid-flow, or because they are waiting for SMS code to arrive.
You can use the above information to estimate whether the user has abandoned the flow or is fumbling for the external code calculator in their drawer.
Account statuses
So the user has linked the requisition and now you can query the account endpoint. Accounts have their own statuses because there can be multiple accounts under one requisition, and one account can be under multiple requisitions.
The GET /api/v2/accounts/:id/ endpoint, aka account metadata endpoint, will return the following statuses:
DISCOVERED - we know it exists, we have assigned it an ID, but we can't access it yet as we are still “negotiating” the access with the bank's server.
PROCESSING - similar to “Discovered”, but includes the cases we are pulling the initial extended transaction history - this is done when more than 90 days of transactions are requested during the authorisation flow because many banks only allow you to look at the oldest history for the first few minutes.
READY - you can query data
(this is where we redirect the user back to you, unless you chose redirect_immediate)
ERROR - the last call to the account resulted in an error (if the bank's server is down and/or returns 503, this does not count as an error, and neither does hitting either type of Rate Limits 1 2 )
SUSPENDED - you triggered an error on the bank's side 10 times in a row and we have “locked” this account as not to give cause for the bank to block us. The only way to “unlock” this account is to create a new requisition.
Do you have to implement the logic to check account statuses?
It depends:
If you never request transaction history longer than 90 days and do not use redirect_immediate, you are very likely to get away with not checking account statuses - either you get data or you get an error, in which case you can trigger the authorization flow again. If the account is not ready when you query it, you can wait a few seconds and try again (just out for rate limits however).
If you work with extended history, if your users have a lot of transactions (e.g. commercial accounting) and especially if you want to minimise friction for your users, these statuses will be useful.
Comments
0 comments
Article is closed for comments.