Understand provider json
Less than to read
Consuming applications need to know that your provider exists and what its functionality is.
To support this, a provider must generate a json file that describes the provider’s functionality and requirements.
Provider rules metadata
The json Rules that you provide tell the consuming application what they need to do to integrate with you.
For your provider to be understood by Sage you must provide rules, some of these values are provided by Sage and others are provided by you.
Top level fields
You must provide json with the following fields for Sage to understand your provider.
- providerId: Guid, this is the provider identifier provided by Sage, this should never change as is unique to your organisation
- name: String, supplied by the provider, the name of your provider as you would like it to appear in a Sage product
- author: String, this represents the author of this configuration data. This is normally the name of you organisation
- country: Array of 2-character ISO country code Strings, countries where it you can make payments using this providers service. Specify each country using the ISO 3166-1 Alpha-2 format.
- defaultLanguage: String, supplied by the provider, the language that text will be returned in by default
- supportedLanguages: Array of Strings, supplied by provider, languages that can be returned if an x-accept-language header is provided
- logo: String, the link to your organisations or services logo that you would like to appear in sage products
- logoSvg: String, as with logo but in a Svg format
- termsOfUse: String, the link to the terms of use for this provider
- privacyAgreement: String, the link to the privacy agreement relating to this provider
- notificationUrl: String, supplied by the provider, the url that Sage will send messages to
- providerHeaderKeyName: String, supplied by the provider, header name Sage should include on posts
- providerHeaderKeyValue: String, supplied by the provider, header value Sage should include on posts (this can help identify it is sage posting against notification endpoint)
- accountType: Object (see below)
accountType
- capabilities: Object of type capabilities (see below), supplied by the provider, describes the functionality of the provider
- name: String, supplied by the provider, the type of account the provider deals with, usually
Corporate - description: String, supplied by the provider, text that may appear in Sage UI to describe the provider
- maximumPaymentCount: Int, the maximum payments that can be processed in a batch of payments, Sage Network Platform supports a maximum of 2000
- maximumInvoicesPerPayment: Int the maximum invoice details that can be included per payment in the batch, Sage Network Platform supports a maximum of 100
- validationRules: Array Objects of type Rules
- defaultLocalInstrument: Guid, supplied by the provider, the Guid of the Sage Network Platform local instrument (payment method) that the provider would use as default
- localInstruments: Array of objects of type LocalInstrument
capabilities
An array of enumerated values that describe the capabilities of the provider, Providers can add capabilities but they should first be agreed with Sage so that they can be documented and capabilities are standardised across providers.
- SubscriptionRequired: A subscription to this provider is required before any payments can be made. To be able to make payments with this provider a subscription must be made via the consumer v3/subscription endpoint
- DebtorAccountRequired: The provider holds a copy of the consumer debtor/bank account(s) details, these must be sent to the provider via the consumer api-msg-v1/debtoraccountputs endpoint
- CreditorRequired: The provider holds a copy of the consumer creditor/vendor details, these must be sent to the provider via the consumer api-msg-v1/creditorputs endpoint
- DebtorQueries: The provider supports querying the debtor/bank account information it holds using the api-msg-v1/debtoraccountlistqueries endpoint
- CreditorQueries: The provider supports querying the creditor/vendor information it holds using the api-msg-v1/creditorlistqueries endpoint
- IFramePermitted: The provider allows any UI it serves to be embedded in an iFrame
- SubscriptionUpdateMessage: The provider sends a notification when a subscription is updated (status change etc)
- BatchpaymentsUpdateMessage: The provider sends a notification when a batch of payments is updated (status change etc)
- PaymentsUpdateMessage: The provider sends a notification when a payment is updated (status change etc)
Rules
An array of validation rules
- ruleId: Guid, supplied by the provider
- validation: Object of type Validation
Validation
- jsonPath: String, supplied by the provider, the path in the entity (apiPath) that this data is bound to
- apiPath: String, supplied by the provider, the entity that the jsonPath belongs to. One of
Subscriptions, BatchPayments, Creditors, CreditorPuts, DebtorAccounts, DebtorAccountsPuts - optionality: String, supplied by the provider,
Optional, Required - regex: String, supplied by the provider, a regular expression that describes the field type, size and any limits
- uiLabel: String, supplied by the provider, Text that will appear as a label in this field when built using dynamic UI
- example: String, supplied by the provider, Example that will appear as a hint in this field when built using dynamic UI
- description: String, supplied by the provider, Description that will appear as a tooltip in this field when built using dynamic UI
- errorMessage: String, supplied by the provider, Error message that will appear as an error against this field when built using dynamic UI
LocalInstrument
Array of local instruments
- id: Guid, supplied by the provider
- value: String, supplied by the provider, name of local instrument (paymmet type)
The following is an example of a provider payload.
{
"providerId": "38a33184-be4a-4fe0-a8c4-53197eac6439",
"clientId": "xxx",
"clientApiKey": "xxx",
"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"
}
]
}
}