Onboarding with a Banking Service Provider
The onboarding journey begins with an end user requesting connection with their banking provider. As can be seen in the onboarding flow diagram, there are many touch points outside of the Provider API which play a part in connecting the user with their bank transactions.
To test your integration, we have prepared Postman collections which allow the full onboarding flow to be simulated. The collections cover the Consumer and Provider APIs and Sage ID authentication. Download the Postman collections.
Using Postman to simulate the onboarding flow
This flow simulates a customer onboarding journey from the Sage application to the finalisation and creation of an organisation and company in Banking Service.
Make a POST request to the organisations endpoint of the consumer API to mock a Sage user wanting to onboard with their banking provider.
Banking Service Consumer API → Organisations & Companies → POST /organisations – The result of this request is that the organisation and company are created in the Banking Service.
With the exception of the initial onboarding request made by the end user, all requests made to the Consumer and Provider API must be authenticated. A JWT must be used for all flows.
Make a GET request to the accesstoken endpoint and obtain the auth token required for all subsequent requests.
Banking Service Consumer API → AccessTokens → GET /accessToken - The response returns a JWT for the created organisation and company.
With the customer’s organisation and company listed in Banking Service, a link to their bank accounts can now be established. The linking of the bank account begins a UI flow which directs the customer to the authorisation endpoints specified when registering for access to the Provider API.
This flow is the easiest way to simulate the OAuth authentication flow of your connector API.
Make a GET request to the BankAccounts indirectlinkaccount endpoint of the Consumer API.
Banking Service Consumer API → Banks → GET /bank – This is simulating the redirect of an on-boarding customer to your authorisation endpoint. Copy the returned redirect URL into a web browser to follow your authorisation flow.
Make a GET request to the BankAccounts indirectlinkaccount endpoint of the Consumer API and obtain the result of the authorisation.
Banking Service Consumer API → BankAccounts → GET /indirectlinkaccount (RESULT) - If successful the response will contain the bank accounts available to the user.
Make a POST request to the bankaccounts endpoint to simulate the users selecting a bank account from the returned list of available accounts.
Banking Service Consumer API → BankAccounts → POST /bankaccounts
After successfully linking a bank account, transactions can be pushed to the Provider API for the account. This flow allows you to test and ensure transactions are successfully pushed and synchronised with the customer’s account.
Make a GET request to the transactions endpoint. This simulates the sage application obtaining the transactions pushed via the Provider API by your service.
Banking Service Consumer API → Transactions → GET /transactions
The statements flow is the Provider API’s standard mechanism for uploading transaction data. Statements are uploaded individually for each bank account and while many bank accounts can be processed simultaneously, each may only have a single statement in flight at anyone time. It is important that your implementation iterates all transactions associated with an account prior to sending a single batch, and polls for the request completion before sending subsequent statements.
Using Postman to POST statements
This collection provides endpoint definitions and sample content for exercising various aspects of the Provider API. In order to use these endpoints, a bank account must have been linked to Banking Service using the link bank account flow and a valid Sage ID JWT must be passed.
Banking Service Provider API → statements → POST /Statements POST – Pushes a batch of transactions to the Provider API for a specified bank account. View reference for POST Statements.
When handling an error response for the POST statements request it may be necessary to DELETE the statements. The DELETE operation can only be successfully requested when the Statement is in a status of accepting or failed. After deletion, the Statement and associated resources will no longer be available through any endpoint. View reference for DELETE Statements.