4. Establish provider configuration
Less than to read
What is the purpose of a provider configuration
To partner with the Payments Out Service you need an active configuration. The purpose of the 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 metadata in terms of capabilities such as language and operational data requirements.
Create a provider JSON file
Sage needs to know about you as a provider and your capabilities so this information can be exposed to consuming products.
Information on how to create a provider files can be found in the guides.
How to get the provider configuration
Sage will initiate the onboarding process. As part of this we’ll tell you what your unique provider identifier is. This is a unique guid specific to your organisation.
There will be skeleton configuration created by Sage initially, as part of onboarding. It is the responsibility of the provider to maintain this configuration and keep it up to date with future changes.
When you have the provider identifier, you can get the provider configuration by sending a GET request requesting your provider configuration using the Provider 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 assigned to you. This will have been sent to you by Sage as part of 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, and a JSON representation of the current provider configuration.
How and why you should 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.
How to persist the provider configuration
Configuration changes can be made using 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 assigned to you. This will have been sent to you by Sage as part of 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
This 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_.+-]+@[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, and a JSON representation of the current provider configuration.