The Provider API and your needs
You’ll find an overview of Banking Service and the Provider API in the What is Banking Service? section.
Integrating with Banking Service allows Sage customers to connect bank feeds to products.
Banking Service is product agnostic. This means customers of a range of products will be able to use this service and connect bank feeds.
If you’re looking for integration with a specific product, be aware that some features may be implemented differently across products.
The provider requirements
You need to review the requirements for a successful integration with API. You can still integrate if some items aren’t complete, but you may need further assessment before integrating.
- 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.
- 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.
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:
- Type (for example, credit, debit, direct debit, interest)
- Date posted
- Store any PII of our customers (for example, credentials, transactions)
- Support multiple financial institutions or account types.
- Ensure the transactions models in a consistent shape for all account types.
Register your interest and apply to become a partner
After you have decided to connect your service to Banking Service, go to our Partners site and request access to use our open APIs and integrate with Sage.
A member of the commercial team will be in touch to discuss integration. They will help you assess against the provider requirements and answer your questions.
After registering, we will enable you as a provider in Banking Service. You will then be able to start setting up for development.
Terms and conditions
To use Banking Service, you’ll need to read and accept our terms and conditions. By using our service, you are accepting our terms and conditions.
Read and download our Banking Service Terms and Conditions.
The kick-off call is an introduction to members of our Enablement team. It’s an opportunity to ask any pre-development questions. This will include:
- Introductions to the team members
- Introduction to setup requirements
- Overview of roadmap and the go-live process
- Ongoing support
Getting set up
What you need to provide to us
Before the development phase, we need these endpoints added to our database:
- /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 2: Develop & Test.
At this stage, we only need the URLs added to our sandbox database, so you can develop against it. You can change the URLs at any time.
Resources we will provide to you
After registration, you will receive these resources:
- You’ll get access to our sandbox environment.
- 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 2: Develop & Test.
- An assigned contact from the Enablement team for setup queries.
- Communication channels established for support.
Before you can move forward with your integration you’ll need to give us your endpoints. You’ll also need to review the resources we’ve provided.
Find out what you need to do to develop and test for your integration before your kick-off call.