Onboarding new Customers and Bank Accounts
Less than to read
Sage Web Products with an indirect (aggregator) bank
You would initiate this flow if the user has selected a bank that is indirect (dataProvider value on the bank will be ‘indirect’). For more information on the end-points, please refer to Swagger and API Specification.
GET /api/v1/organisations/{organisationId}/companies/{companyId}/indirectlinkaccount?bankId={bankId}&web=true
-
This endpoint returns 302 with a redirect, and when calling this endpoint with the additional web=true param, the returned body will include a pollRoute and pollPeriod.
{ "redirect": "https://…", "pollRoute": "https://…", "pollPeriod": 5000 }
-
Open the redirect URL (in a new window for example), this will allow the user to link their account with the aggregator.
- While the user is in the process of lining their account, you can start to poll the pollRoute – this is a signed URL and can only be used once.
-
If the user has successfully linked their account with the aggregator and we have the account information, we will return 200 with that account information (accountName, accountIdentifier and accountKey) – you will need this for the POST bankAccount.
{ "account": { "accountName": "accountName", "accountKey": "accountKey", "accountIdentifier": "accountIdentifier" }, "success": true }
-
If the user has been unable to link their bank account, we will return 200. However, the account will be null and success will be false.
{ "account": null, "success": false }
-
If the user hasn’t yet completed linking their account, we will return 202 and the body will include a new pollRoute and pollPeriod. The next call to check the status should be done after a timeout of the pollPeriod – you repeat this until you get the 200 response.
-
- Once you have the required account information, complete the POST bankAccount as normal. However, before doing the POST, you will also need to capture the requestedStartDate for transactions from the user – we will attempt to get transactions from the aggregator from this date.
Note: There are no differences to the reAuth flow (for MFA or expired credentials, etc) for web products. You can launch the reAuth flow after checking the bankAccount status, which will be authRequired. You can continue to check the status which will go to ‘active’, once reAuth is successful.
Sage Desktop Products
On-Premise products on-board with Banking Service via the token service. An initial request is sent to the token service (using the appropriate url for the Banking Service environment you’re on-boarding to) before attempting to retrieve a Captcha from Banking Service and POST your organisation.
When the POST organisation call occurs, Banking Service makes a further request to the token service to validate the customer licenceDetails that were sent in that initial request.
On each environment, a single Sage Customer account may be allowed to onboard multiple organisations; this is defined on a per-product basis (the product’s customer ‘organisationLimit’).
Banking Service will respond differently depending on the response from the Token Service.
More Information
More detail around onboarding can be found in Use cases.