Skip to content
Developerhome

4. Establish Provider Configuration

  Less than to read

Provider Configuration

What is the purpose of a Provider Configuration

To be able to successful partner with the Payments Out Service you need to have an active configuration. The purpose of this configuration is to:

  • Provide data related to the secure integration of the service to Sage.
  • Surface end user data relating to the name and branding of this payment provider. This will enable users to find and use you as a provider
  • Provide meta data in terms of capabilities such as language and operational data requirements.

How to get the provider configuration

Sage will initiate the initial onboarding process and as part of this will communicate what your unique provider identifier is. This is a unique Guid specific to your organisation.

Initially there will be skeleton configuration created by Sage as part of the initial onboarding process. It is the responsibility of the provider to maintain this configuration and keep it up to date with any future changes.

Once you have this provider identifier you can use this obtain your provider configuration.

To get the provider configuration you will send a GET request, requesting your provider configuration using the providers API.

Headers

GET /api-provider-v1/providers/{providerId} HTTP/1.1
Host: api-payout.sage.com
x-application: {app name}
x-fapi-interaction-id: {UUID}
x-api-key: {api key}

Where:

  • {providerId} is the unique identifier that has been assigned to you. This will have been sent to you by Sage as part of initial onboarding.

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

  • {UUID} is a Universally Unique Identifier to write into logs. This value is used to debug your application’s integration with Payments Out Service. Use a new UUID for each request. UUIDs must conform to RFC 4122.

  • {api key} is the API key for the Provider API.

For information about these parameters, go to the Provider API reference.

Response

The response from this request will be a Http Status Code of 200 with a json representation of the current provider configuration. More details of the various properties of this configuration are explained below.

How and why to customise the provider configuration

The provider configuration needs to be configured so Payments Out Service knows how to communicate with your provider. This will include details of communication endpoints and other security provisions to ensure that it is only Sage calling your service. There are also details that will be surfaced to sage customer to help them find and use your service. Rules can also be defined that details the capabilities of your service and what data will need to be supplied.

For information about this configuration, go to the Understanding provider json.

To understand more about the provider rules, go to Understanding provider rules.

How to persist the provider configuration

Configuration changes can be made via the PATCH providers endpoints.

Headers

PATCH /api-provider-v1/providers/{providerId} HTTP/1.1
Host: api-payout.sage.com
x-application: {app name}
x-fapi-interaction-id: {UUID}
x-api-key: {api key}

Where:

  • {providerId} is the unique identifier that has been assigned to you. This will have been sent to you by Sage as part of initial onboarding.

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

  • {UUID} is a Universally Unique Identifier to write into logs. This value is used to debug your application’s integration with Payments Out Service. Use a new UUID for each request. UUIDs must conform to RFC 4122.

  • {api key} is the API key for the Provider API.

For information about these parameters, go to the Provider API reference.

Body

Below is an example of a PATCH payload

{
  "name": "TestProvider1",
  "country": [
    "AU"
  ],
  "defaultLanguage": "en",
  "supportedLanguages": [ "en" ],
  "notificationUrl": "https://xxx/api/webhook",
  "providerHeaderKeyName": "x-sage-auth-key",
  "providerHeaderKeyValue": "xxx",
  "accountType": {
    "capabilities": [
      "SubscriptionRequired",
      "DebtorAccountRequired",
      "CreditorRequired",
      "DebtorQueries",
      "CreditorQueries"
    ],
    "name": "Corporate",
    "accountTypeId": "xxx",
    "description": "Test Provider 1",
    "maximumPaymentCount": 2000,
    "maximumInvoicesPerPayment": 50,
    "validationRules": [
      {
        "ruleId": "xxx",
        "validation": {
          "jsonPath": "additionalData.companyname",
          "apiPath": "Subscriptions",
          "optionality": "Required",
          "regex": "^[^<>\"{}\\]\\[]{0,255}$",
          "uiLabel": "Company Name",
          "example": "Acme Inc",
          "description": "The companies legal name",
          "errorMessage": "name includes invalid characters"
        }
      },
      {
        "ruleId": "xxx",
        "validation": {
          "jsonPath": "additionalData.email",
          "apiPath": "Subscriptions",
          "optionality": "Optional",
          "regex": "(?=^.{5,71}$)(^[a-zA-Z0-9_.+-][email protected][a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$)",
          "uiLabel": "Email",
          "example": "[email protected]",
          "description": "Email Address",
          "errorMessage": "Email address includes invalid characters"
        }
      }
    ],
    "defaultlocalinstrument": "xxx",
    "localInstruments": [
      {
        "id": "85f7caf8-4566-4719-a2fa-983134a95f50",
        "value": "VCARD"
      },
      {
        "id": "0242ebf6-a1fa-4d32-a998-9d609b4f57b0",
        "value": "CHECK"
      },
      {
        "id": "94443c6a-256d-4e5e-b9d8-0946461ad89c",
        "value": "ACH"
      }
    ]
  }
}

Response

The response from this request will be a Http Status Code of 200 with a json representation of the current provider configuration.