Skip to content

2. Get set up

  Less than to read

Provider requirements

You need to review the following requirements for a successful integration with the API.

Partner requirements

  • You are required to provide a support process and issue logging portal to be used to esculate issues from the Sage team.
  • Only send cleared transactions.
  • Each transaction should have a unique ID. Statements containing transaction IDs that have been sent previously will return an error and won’t be processed. It is safe to resubmit a statement if there’s uncertainty around a previous delivery. For example, connection times out before a response is received, 500 error.
  • Each upload containing transactions must have a correctly signed (positive or negative) ending balance.
  • You can only submit one statement at a time for a single bank account. The HTTP response for the first statement must be received before you submit further statements.
  • Transactions must be no more than 2 weeks older than the newest transaction.
  • Send transactions in the order they appear on the account statement.
  • Transactions should be sent in near real-time.
  • The Provider API will throttle requests at a pre-agreed rate (default 10 requests per second) and may return a 429 error response. In the event of a 429 error response, the integration should default to an appropriate back off before retrying.

Authentication requirements

  • Use Sage ID access tokens until they expire. New tokens are not required for each new request.
  • Your integration should ensure client credentials and API keys are stored securely.
  • You should notify us immediately of any breach of credentials.
  • Providers who have chosen to create a connector API to support notifications must validate the API key header and Sage ID token sent in any notification.

Technical requirements

You are responsible for maintaining the provider connector.

The integration you build must:

  • Have, or intend to build for this integration, a UI flow that can be served via a redirect. This allows the customer to securely log in to their account and includes multi-factor authentication.
  • Assign a unique immutable identifier to each transaction. The identifier for a transaction must never change. The same transaction identifier should not occur more than once for a bank account.
  • Support filtering transactions so that only posted/cleared transactions are sent to Provider API. Banking Service doesn’t support pending or uncleared transactions.
  • Have the ability to page requests to Provider API. Each statement can contain a maximum of 1,000 transactions. If more than this are available for a bank account, they must be sent in multiple requests.
  • Support rolling balances. You must send balances with each statement. The balance must equal the previous balance, plus the total of the transactions being sent.
  • Support the minimum set of required data, you can find out more in Provider API. The minimum dataset is:
    • Amount
    • Type (for example: credit, debit, direct debit, interest)
    • Date posted
    • Status
    • Description
  • Store any PII of our customers securely (for example: credentials, transactions).
  • Support multiple financial institutions or account types.
  • Ensure the transactions models in a consistent shape for all account types.
  • Allow the user to select a start date in which they would like to recieve transactions from.

Get set up

What you need to provide us

Before the development phase, we need your connector API endpoints to add to our database. These endpoints allow the Banking Service to send and recieve information from your solution. Learn more about the Connector API.

The endpoints we require are:

  • /auth – for generating UI to authenticate a customer account.
  • /authrefresh – for generating UI to reauthenticate a customer.
  • /notification – for receiving calls when events occur on Banking Service (or Provider API) that need the provider’s attention.
  • /availableaccounts – multi-account linking is an optional feature that uses this endpoint. It’s adopted by some Sage products to let users onboard multiple accounts at one time.

We explain how to implement these endpoints in Stage 3: Integrate.

At this stage, we only need the URLs added to our sandbox database, so you can begin development and testing. You can change the URLs at any time.

Resources we will provide to you

After applying your interest using the form below, you will receive these resources:

  • Your sandbox credentials (Client ID, Client Secret and API Key).
  • A provider-specific Postman environment. This contains your client credentials and keys to allow you run the Postman collections. You can find out more about this in Stage 3: Integrate.
  • Communication channels established for support.

What’s next?

While waiting for your sandbox credentials, read our documentation and find out what is required to integrate with the Banking Service.

Was this helpful?