Onboarding new Customers and Bank Accounts

Less than 5 minutes 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.

If the initial request was not sent to the Token Service, a 404 not found is thrown by Banking Service.
If the customer is not a valid sage customer, a 400 error is thrown from Banking Service.
If the customer is a valid customer, and the customer ‘organisationLimit’ has been exceeded, Banking Service will throw a 409 conflict error.
If the customer is a valid customer and the customer ‘organisationLimit’ has not been exceeded, Banking Service will create the organisation and return a 200.

On our QA environment, all products have an unlimited organisationLimit.
On Pre-Prod, all products have an organisationLimit of 15.
On Prod, all products have an organisationLimit of 1.

More Information

More detail around onboarding can be found in Use cases.