Skip to content
Developerhome
Product homepage
Payments Out Service

Onboard a Sage application

  Less than to read

You can onboard and integrate a cloud application with Payments Out Service via the REST API in 4 steps:

  • Create an organisation
  • Get an access token for the organisation
  • Create a company
  • Get an access token for the company

An organisation represents a Sage customer using a Sage product and Sage Network Platform services.

When you create an organisation, you receive a JSON payload. This contains the values that allow you to obtain a JSON Web Token (JWT). Use the JWT to authenticate your HTTP requests against the REST API.

A company represents an institution whose outgoing payments you want to process.

A company is always linked to a particular organisation. Depending on the country where you use the service, an organisation can have one or several companies.

Create an organisation

Send a POST request with the following headers and body.

An organisation will be created if your request is successful. You’ll receive a JSON response like the one shown in the Example response section.

Headers

POST /auth-v1/organisations HTTP/1.1
Host: api-money.sage.com
Content-Type: application/json
X-Application: {app name}
X-Nonce: {unique value}
X-Signature: {signature}

Where:

  • POST /auth-v1/organisations is the Payments Out Service endpoint where you send your request.
  • api-money.sage.com is the your request’s base URL.
  • {app name} is the name of an app supported by, and in the format accepted by Payments Out Service. For example: sage.intacct.
  • {unique value} is an arbitrary unique value, such as a GUID. In each HTTP request you must use a new X-Nonce value.
  • {signature} is the signature for your request. Read our generating an X-signature guide for more information.

Body

{
    "name": "{organisation name}",
    "sageCRMId": "{app serial number}",
    "primaryCountry": "{country code}",
    "adminEmail": "{admin email}",
    "defaultLanguage": "{language code}",
    "externalId": "{external ID}"
}

Where:

  • {organisation name} is the name for the organisation you want to create. For example: My organisation.

  • SageCRMId value is provided by Sage and is the unique identifier for the Sage customer in the CRM system holding customer details. This is used for various purposes, including providing aggregated management information and contacting the customer if problems occur.

    Make sure to submit the correct SageCRMId value. Providing the wrong SageCRMId value may prevent Payments Out Service from working properly.

  • {country code} is your country in the ISO 3166-1 Alpha-3 format. For example: GBR.
  • {admin email} is the app administrator’s contact email. Make sure you specify a valid email.
  • {language code} is the default language for your organisation in the ISO 639-1 format. For example: EN.
  • {external ID} is the unique organisation identifier. It’s used to identify the organisation in the consuming application. It is provided to the application in any notifications sent from Payments Out Service.

Example response

{
    "organisationId" : "0969b85d-c63a-46cd-90ae-65821757f9e0",
    "name" : "My organisation",
    "sageCRMId" : "3c7071a3-ee44-1dda-c764-d3e09b1502dc",
    "primaryCountry" : "GBR",
    "adminEmail" : "[email protected]",
    "defaultLanguage": "EN",
    "externalId" : null,
    "primarySigningKey" : "GGWWFWWA059696B162774F469AA0B206B40AD7245CAC2A9E610898A4FCAC"
}

Where:

  • organisationID contains an automatically generated unique ID of the created organisation. Use this ID to retrieve or update the organisation via the REST API.
  • primarySigningkey contains the secret you will need to generate an X-Signature value in the next step. Read our generating an X-signature guide for more information.
  • name, SageCRMId, primaryCountry, adminEmail, defaultLanguage, externalId – These contain the values defined in your request body.

Get an access token for the organisation

To work with an organisation via the REST API, you need to obtain an access token and use it to sign your HTTP requests.

The token is generated using the organisation unique ID (organisationId). It allows you to work with that organisation only.

To work with another organisation you’ll need to obtain a new access token.

To get an access token, send a GET request with the following headers.

You’ll get an access token in the JSON response if your request is successful. Each access token expires after a certain amount of time. To obtain a new valid access token for the organisation, resend your GET request.

Headers

GET /auth-v1/accesstoken HTTP/1.1
Host: api-money.sage.com
X-Organisation-Id: {organisation ID}
X-Nonce: {unique value}
X-Signature: {signature}
X-Application: {app name}

Where:

  • GET /auth-v1/accesstoken is the REST API endpoint where you send your request.

  • api-money.sage.com is your request’s base URL.

  • {organisation ID} is the ID of the organisation you’re generating an access token for.

  • {unique value} is an arbitrary unique value, such as a GUID. In each HTTP request you must use a new value.

  • {signature} is the signature for your request. Read our generating an X-signature guide for more information.

  • {app name} is the name of an app supported by, and in the format accepted by Payments Out Service. For example: sage.intacct.

For more information about this REST resource and its parameters, go to the Onboarding and authentication API reference.

Example response

An access token looks like:

{
    "jwt": "AAAAAAAAAAA.wtwwwnifjaoisdfafMC4wLjAiLCJvcmdhbmlzYXRpb25KKKKKKKJZCI6ImFiMWY3OGIyLTM4NGUtNGUyMC1iMzY2LTZmOTBiODc2M2U2ZSIsInNvdXJjZVByb2R1Y3QiOiJzYWdlLmJyYXppbC5vbmUiLCJraWQiOiI3NTdiNTBmZDhmNDYxODAyNTI2MTFiMDY2ODI2NTBiNDYyYmYyYmE4MzNkMzExYYwMDI3IiwiaXAiOiI4MS4xMjguMjMzLjIwMiIsImlzcyI6IndwYi1hdXRoIiwiY2hhbm5lbCI6Im9ubGluZS1jaGFubmVsIiwiZXhwIjoxNTU2MDE1Njc3LCJzZXJ2aWNlSWQiOiJ3cGItYXV0aC1zZXJ2aWNlIiwiaWF0IjoxNTU2MDE0NDc3fQ.afe3qfgewgpkhidaMgo_nmrrWMEeGvq5q2yFElgZ79AnjQ74yyt1WgXKn8gNH90RwdNXStozG2cTsg8PvPvM0lWV0sRZM3yVOJs2FvZp5aSzFuFq6m2xcjwkLxTys3x1Knx3oZkXTYMoEbI3_ZvwSvxV3DK2cNT888gsTXQuwgJstR2Qpud5abcJIY64-oVnshyuJrgO391n7FHCnn1Hm-9eSegLSIl0zJYN0xVYuT21iRxZk0sObZMC12FC0qNh2gdi-kOUMEdzkJ0iEYeDp4b3tFnUSN0ijBT4XHSyY_sxrOLz-pphGiKQn0LAgJuqLLT-Q"
}

Create a company

Send a POST request with the following headers and body.

A company will be created if your request is successful. You’ll receive a JSON response similar to the one shown in the Example response section.

Headers

POST /auth-v1/companies HTTP/1.1
Host: api-money.sage.com
Content-Type: application/json
Authorization: Bearer {JWT}
X-Application: {app name}

Where:

  • POST /auth-v1/companies is the Payments Out Service endpoint where you send your request.

  • api-money.sage.com is your request’s base URL.

  • Bearer {JWT} is the authorization string for your request. {JWT} is the JSON Web Token you obtained in Get an access token for the organisation.

  • {app name} is the name of an app supported by, and in the format accepted by Payments Out Service. For example: sage.intacct.

Body

{
    "name" : "{company name}",
    "externalId" : "{external ID}",
    "taxNumber" : "{tax number}",
    "standardIndustrialCode" : "{SIC}",
    "contactTelNo" : "{phone}",
    "contactEmail" : "{email}"
}

Where:

  • {company name} is the name of the company you want to create.

  • {external ID} is the external ID for the company. If you don’t want to assign an external ID, set this value to null.

  • {tax number} is the tax number of the company.

  • {SIC} is the Standard Industrial Classification (SIC) code for the company. For details, see the Division of Corporation Finance: Standard Industrial Classification (SIC) Code List.

  • contactTelNo is the company telephone number.

  • contactEmail is the company email.

Example response

{
    "companyId": "a9ad9268-afe0-4550-b4fb-5d0ba80a58b8",
    "organisationId": "661c3957-8cf0-4eaf-b446-601344674c3c",
    "name": "My company",
    "externalId": "MyCompanyExternalID-12345",
    "logoUrl": "",
    "address": {
        "addressLine1": "",
        "addressLine2": "",
        "addressLine3": "",
        "addressLine4": "",
        "countrySubdivision": "",
        "postalCode": "",
        "country": ""
    },
    "taxNumber": "123456789",
    "standardIndustrialCode": "1799",
    "contactTelNo": "123456789",
    "contactEmail": "[email protected]"
}

Where:

  • companyId contains an automatically generated unique ID of the created company. You can use this ID to retrieve or update the company details via the REST API.

  • organisationId contains the unique ID of the organisation where you created the company. This is the organisation created in Create an organisation.

  • logoUrl contains the URL used to upload or update the company logo. If this parameter is empty, you can create an upload URL yourself. For information on how to upload a company logo go to the upload a company logo guide.

  • address contains the company address. If this parameter is empty, you can update it with your company’s address.

  • name, externalID, taxNumber, standardIndustrialCode, contactTelNo, and contactEmail – These contain the values you defined in the body of your request.

Get an access token for the company

To work with a company via the Consumer API, you need to obtain an access token and use it to sign your HTTP requests.

The company and organisation’s unique IDs (companyId, organisationId) are used to generate the token. They allow you to work with that company only.

To work with another company you’ll need to obtain a new access token.

Send a GET request with the following headers.

You’ll receive an access token in the JSON response if your request is successful.

Each access token expires after a certain amount of time. To obtain a new access token for the company, send your GET request again.

Headers

GET /auth-v1/accesstoken HTTP/1.1
Host: api-money.sage.com
X-Organisation-Id: {organisation ID}
X-Company-Id: {company ID}
X-Nonce: {unique value}
X-Signature: {signature}
X-Application: {app name}
X-Audience: paymentsout
X-Scope: all

Where:

  • GET /auth-v1/accesstoken is the Consumer API endpoint where you send your request.
  • api-money.sage.com is your request’s base URL.
  • {organisation ID} is the ID of the organisation that includes the company.
  • {company ID} is the ID of the company you want to generate an access token for.
  • {unique value} is an arbitrary unique value, such as a GUID. In each HTTP request you must use a new value.
  • {signature} is the signature for your request. Read our generating an X-signature guide for more information.
  • {app name} is the name of an app supported by, and in the format accepted by Payments Out Service. For example: sage.intacct.
  • X-Audience must have the value paymentsout
  • X-Scope must have the value all

For more information about this REST resource and its parameters, go to the Onboarding and authentication API reference.

Example response

An access token looks like:

{
    "jwt": "AAAAAAAAAAA.wtwwwnifjaoisdfafMC4wLjAiLCJvcmdhbmlzYXRpb25KKKKKKKJZCI6ImFiMWY3OGIyLTM4NGUtNGUyMC1iMzY2LTZmOTBiODc2M2U2ZSIsInNvdXJjZVByb2R1Y3QiOiJzYWdlLmJyYXppbC5vbmUiLCJraWQiOiI3NTdiNTBmZDhmNDYxODAyNTI2MTFiMDY2ODI2NTBiNDYyYmYyYmE4MzNkMzExYYwMDI3IiwiaXAiOiI4MS4xMjguMjMzLjIwMiIsImlzcyI6IndwYi1hdXRoIiwiY2hhbm5lbCI6Im9ubGluZS1jaGFubmVsIiwiZXhwIjoxNTU2MDE1Njc3LCJzZXJ2aWNlSWQiOiJ3cGItYXV0aC1zZXJ2aWNlIiwiaWF0IjoxNTU2MDE0NDc3fQ.afe3qfgewgpkhidaMgo_nmrrWMEeGvq5q2yFElgZ79AnjQ74yyt1WgXKn8gNH90RwdNXStozG2cTsg8PvPvM0lWV0sRZM3yVOJs2FvZp5aSzFuFq6m2xcjwkLxTys3x1Knx3oZkXTYMoEbI3_ZvwSvxV3DK2cNT888gsTXQuwgJstR2Qpud5abcJIY64-oVnshyuJrgO391n7FHCnn1Hm-9eSegLSIl0zJYN0xVYuT21iRxZk0sObZMC12FC0qNh2gdi-kOUMEdzkJ0iEYeDp4b3tFnUSN0ijBT4XHSyY_sxrOLz-pphGiKQn0LAgJuqLLT-Q"
}