On-boarding with a Banking Service Provider

The on-boarding journey begins with an end user requesting connection with their banking provider. As can be seen in the below on-boarding 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 on-boarding flow to be simulated. The collections cover the Sage Banking Service - Consumer and Provider API and Sage ID authentication. Download the collections.

Using Postman to simulate the on-boarding flow

This flow simulates a customer on-boarding journey from the Sage application to the finalisation and creation of an organisation and company within the Sage Banking Service.

Step 1.

Make a POST request to the organisations endpoint of the consumer API to mock a Sage user wanting to on-board 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.

Step 2.

With the exception of the initial on-boarding 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.

Step 3.

With the customer’s organisation and company listed in Sage 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.

Step 4.

Make a GET request to the BankAccounts indirectlinkaccount endpoint of the consumer API and obtain the result of the authorisation.

Banking Cloud Consumer API → BankAccounts → GET /indirectlinkaccount (RESULT) - If successful the response will contain the bank accounts available to the user

Step 5.

Make a POST request to the bankaccounts endpoint to simulate the users selecting a bank account from the returned list of available accounts.

Banking Cloud Consumer API → BankAccounts → POST /bankaccounts - If the response from your connector API is successful the

Step 6.

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

POST statements

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. With this in mind, 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 the Sage 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. statements POST

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. statements DELETE