Understand provider rules
Less than to read
Consuming applications need to be compatible with existing payment providers and new ones.
To support this, each electronic payment provider has validation rules for data submitted to it via Payments Out Service. These rules let applications deliver the appropriate user experience. It also gives prompt and specific feedback if they enter data that the provider will not accept.
An integration may work incorrectly or fail if provider rules aren’t accounted for.
Provider rules metadata
You can get provider rules using the GET Providers endpoint. Look at the Get definitions of supported electronic payments providers guide for more information.
The list of rules is found in the $.data.accountType.validationRules JSON element in the provider file. Each rule has a unique:
ruleIdvalidationelementdefaultLocalInstrumentelement- list of supported local instruments
Go to the Get a list of supported payment types for more information.
By exposing this information as a set of rules, a consuming application can adjust its user interface.
Rules determine if the data is:
- required
- optional
- not allowed
UI labels, descriptions and error messages will display if a user enters invalid data.
A regular expression allows consuming applications to validate data immediately. It can then give feedback to the user, before data is submitted to the API.
Validation
The validation element defines the rules using the following sub-elements:
apiPath– This is the resource the rule applies to.jsonPath– This is the path to the entity within the overall structure.optionalityregexexampledescriptionerrorMessage
apiPath
apiPath within the validation element identifies the resource this rule applies to. For example:
- The apiPath value of ‘Subscriptions’ indicates that the rule should be applied to subscriptions being sent to the API.
- A value of ‘Creditors’ indicates that the rule should be applied to creditors being sent to the API.
- A value of ‘DebtorAccounts’ indicates that the rule should be applied to bank accounts being sent to the API.
- A value of ‘BatchPayments’ indicates that the rule should be applied to a batch of payments being sent to the API.
The following is an example of a subscription payload. additionalData is a string containing JSON where the valid content is defined by the rule metadata:
{
"data": {
"providerId": "1030dba0-e5b8-441e-b875-c546781ed516",
"additionalData": "{\"apcaNumber\" : \"AN517546\"}"
}
}
A rule that applies to this POST could look like this:
{
"ruleId": "9b8f3e10-5328-4e9a-8c40-fe7348b8f005",
"validation": {
"jsonPath": "additionalData.company.legalName",
"apiPath": "Subscriptions",
"optionality": "Optional",
"regex": "^[^<>{}%\\]\\[]{0,255}$",
"uiLabel": "Company Name",
"example": "Acme Inc",
"description": "The companies legal name",
"errorMessage": "Field includes invalid characters"
}
}
This rule applies to a subscription (from the apiPath), and to the element of path additionalData.company.legalName.
Rules may apply to other parts of the payload as well as to additionalData. Any values a user submits may be more restricted by the provider’s rules than those described in Consumer API reference.
jsonPath
jsonPath is the path to the element that the rule describes. It identifies the field the rule applies to. In this case it is looking within additionalData for an object called ‘company’, with a property of ‘legalName’.
optionality
A value of ‘optional’ indicates that this field does not need to exist in the submitted payload. A value of ‘required’ would result in an error if the jsonPath does not exist.
regex
If regex exists under validation then its value will be applied. If the regex is failed, an error will be returned.
example
This is an example of what the data might look like. It could be used in the UI to present a placeholder.
description
This is a description of the field. It could be used in the UI to present a label.
errorMessage
The error message returned if the regex is failed.
For more information, go to the Consumer API reference.
defaultLocalInstrument
This is the provider payment method recommended by Sage Network Platform.
If consuming applications want to avoid asking users which local instrument to use for a creditor or payment, they should use this value. They can also use this value if they want them to confirm a default selection.
localInstruments
This is a list of the local instruments (payment types) that this provider supports. Providers support a subset of Payments Out Service local instruments.
To give a complete set of rules for a provider, combine the provider-specific rule IDs with the provider’s local instruments list.
The provider rule should take precedence over the local instrument rules if it exists at both levels, on the same apiPath and jsonPath.
Its name should be presented to the user for the local instrument in the context of this provider.
How Rules influence entities for the provider ‘CSI’
Subscriptions
All additionalData rules for our first subscription-based provider are set to ‘optional’.
How rules influence creditor POSTs
The rules for creditor POSTs define some fields as mandatory and some optional. If any mandatory fields are not sent in the request then the consuming application will receive an error. If optional fields are omitted from the request they will not cause an error.
Creditor fields could be mandatory when the provider has to fall back on paying a creditor by cheque if other payment methods are not configured. To be able to pay any creditor by cheque, the provider must know every creditor’s address and postal (zip) code. Not providing this information when syncing creditors would return an error to the client.
How rules influence debtorAccount POSTs
The rules for debtorAccount POSTs are all optional. If optional fields are omitted from the request they will not cause an error.
How rules influence posting a batch of payments
The rules for batch payment POSTs define some fields as mandatory and some optional. If any mandatory fields are not sent in the request then the consuming application will receive an error. If optional fields are omitted from the request they will not cause an error.
A batch of payments may define some fields as mandatory when the provider needs to know the debtorAccount and creditorIds to identify the source and recipient of the payment. If those IDs were not provided the payment would fail. By making them mandatory the batch would be validated and failed before it reached the provider for processing.