Understand provider rules

Consuming applications need to be compatible with payment providers.

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 followed by the consumer.

---

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:

• ruleId
• validation element

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.
• optionality
• regex
• example
• description
• errorMessage

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 Provider 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.

Local Instruments supported by payments out are

• CHECK - An electronic cheque like a PDF or similar that is printed by the creditor
• BACS - UK electronic Payment
• NETWORK - Payment type is decided by the provider
• VCARD - Virtual Card, pre loaded credit card
• ACH - US electronic payment
• EMAIL - Payment details sent via email
• CHECKPRINTED - Cheque is printed and mailed by the provider

If you provide another payment type that is not covered by the above list, please contact sage.

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 will 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.