Overview

This page contains all the information and steps required to get started using the Sage Business Cloud Payroll Plus API.

Once you have done all the heavy-lifting with registration and authentication setup, the tutorial shows how to actually make it work and invoke a first set of API calls.

Please note that currently, as mentioned in the API overview, this API is only supported in the German product version, but you can still use it from anywhere (albeit the actual UI pages in the product are in German).

The API was initially designed for integration with partner products that would benefit from exchanging data with Sage Business Cloud Payroll Plus. It can be used for other use cases of course, for example for developers interested in getting experience with the API and the product to come up with new ideas that do not yet exist as a product to integrate with. So, for simplicity, this document refers to your application as the client integrating with the Sage Business Cloud Payroll Plus API.

The steps described will allow you to get up and running with the Sage Business Cloud Payroll Plus API.

Prerequisites

The following prerequisites must be met in order to be able to use the API of Sage Business Cloud Payroll Plus:

Registration of your application

To integrate the Sage Business Cloud Payroll Plus API into your application, the product must first be registered with Sage:

Send an email to [email protected]

The following data is required for registration:

Sage then assigns the product-specific API credentials:

The Client Secret is to be treated confidentially and is known only to you and to Sage. In combination with the Client ID, the unique identification of your application takes place.

Authentication

This section explains how to use OAuth 2.0 to allow users to authorize your application (the client) to access their data without sharing their actual login details.

With every API request, you must supply a valid access token within the authorization header:

Authorization:  Bearer ‹Access Token›

Obtaining an Access Token

The steps outlined here explain how to obtain the access token.

Authorization request

Redirect the user to the authorization endpoint, https://lohnabrechnung-plus.sage.com/api/v1/authorize, with the relevant URL query parameters:

Parameter Description
client_id Partner product-specific client ID (see registering your application)
response_type The type of response. This is always code.
redirect_uri Your application callback URL. This is where your users will be sent after authorizing.
state A string used to protect against CSRF attacks. Although state is optional, we recommend including this. This should be a string that cannot be guessed. Note: If the value of the state parameter returned in the response does not match the state that was provided in the original request, it does not originate from the original request and you must not continue.

Example redirect URL:

https://lohnabrechnung-plus.sage.com/api/v1/authorize?client_id=4b64axxxxxxxxxx00710
        &state=4Whsv35d82bdbay6
        &redirect_uri=https://myapp.com/auth/callback

When this endpoint is hit, the user is prompted to sign in to Sage Business Cloud Payroll Plus and then is redirected to the callback URL along with an authorization code which can be read from the response:

GET /auth/callback?code=12a0f9c12cxxxxxxxxxxxxxxx92a48cc1f237ead
                  &state=...
                  &error_description=...
                  &error_uri=...

Error handling:

GET /auth/callback?error=...
                  &state=...
                  &error_description=...
                  &error_uri=...

Possible errors:

Error code Description
access_denied This error occurs when the user chooses not to authorise your application.
invalid_request This error occurs when a required parameter is missing, invalid or provided more than once.
server_error This generic error occurs when the authorization server encounters something unexpected that prevents it from fulfilling the request.
temporarily_unavailable This error occurs when the authorization server is unavailable. We recommend waiting for 10 minutes before retrying.
unauthorized_client This error occurs when the client is not authorized to perform this action. This may be due to an incorrect client_id value.
unsupported_response_type This error occurs when the authorization server does not support the method being used to request the code. You should ensure that the response_type in your request is code.

Exchange the authorization code for the access token

To exchange the authorization code for an access token, you should now make a POST request to the token endpoint:

https://api.lohnabrechnung-plus.sage.com/v1/token

Required parameters:

Name description
code The authorization code provided in the response from the previous step.
client_id Partner product-specific Client ID (see registering your application)
client_secret Partner product-specific Client Secret (see registering your application)
redirect_uri Your application callback URL. This is where your users will be sent after authorizing.
grant_type This must be authorization_code

Example request:

POST https://api.lohnabrechnung-plus.sage.com/v1/token
    ?code=...
    &client_id=...
    &client_secret=...
    &grant_type=authorization_code
    &redirect_uri=...

Example response :

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "...",
    "token_type": "Bearer"
}

The OAuth implementation in Sage Business Cloud Payroll Plus uses JSON-Web-Token (JWT).

The access token (access_token) and the token type (token_type) need to be securely stored within your application in connection with the customer account.

Please note that the token information is a piece of confidential information between Sage and your application. It must not be divulged to any third party as this does compromise the confidentiality and integrity of customer data.

Error Handling

Errors can occur when requesting an access token. Possible causes are:

The HTTP response sent by Sage Business Cloud Payroll Plus is structured like this:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "error": "...",
    "error_description": "...",
    "error_uri": "..."
}

Possible error codes:

Error code Description
access_denied This error occurs when the user chooses not to authorise your application.
invalid_request This error occurs when a required parameter is missing, invalid or provided more than once.
server_error This generic error occurs when the authorization server encounters something unexpected that prevents it from fulfilling the request.
temporarily_unavailable This error occurs when the authorization server is unavailable. We recommend waiting for 10 minutes before retrying.
unauthorized_client This error occurs when the client is not authorized to perform this action. This may be due to an incorrect client_id value.
unsupported_response_type This error occurs when the authorization server does not support the method being used to request the code. You should ensure that the response_type in your request is code.