Map Sage Pay Direct error codes to properties

[judgej]

CC validation at the REST API level provides error messages that include the "property" field that tells you which field is in error. An example is cardDetails.cardholderName which may come with a message to indicate it contains invalid characters.

Many errors are generated by the underlying Sage Pay Direct, and that does NOT provide metadata to indicate which field is in error. However, it does provide a status code that can be mapped to a property.

The status codes we know are listed here: https://github.com/academe/SagePay/blob/master/src/Academe/SagePay/Metadata/error-codes.tsv (there are some new ones 2009-2019 that need to be added, and are not even in Sage Pay's online database of error codes at time of writing).

For example error code 5055 has the message "A Postcode field contains invalid characters." From this we can map to a property billingAddress.postalCode. That is the property name, in dot-notation to indicate structure, that this field was sent to Sage Pay in the Request\Payment message. This is not an official name of this property, but does follow the convention that this REST API seems to implement, so far.

[judgej]

We may also want to provide a user-safe error message that can be used by default, but that's not an important issue at this stage. What we want to achieve with this issue is to be able to programmatically identify which field or fields is in error, so it can be highlighted to the end user to improve the UX.

[judgej]

Field names we are using:

• amount
• currency
• customerFirstName
• customerLastName
• customerEmail
• customerPhone
• billingAddress.address1
• billingAddress.address2
• billingAddress.city
• billingAddress.state
• billingAddress.postalCode
• billingAddress.country
• shippingDetails.recipientFirstName
• shippingDetails.recipientLastName
• shippingDetails.shippingAddress1
• shippingDetails.shippingAddress2
• shippingDetails.shippingCity
• shippingDetails.shippingState
• shippingDetails.shippingPostalCode
• shippingDetails.shippingCountry
• shippingDetails.recipientFirstName
• shippingDetails.recipientLastName

These have been added to the error master-list here:

https://github.com/academe/SagePay/blob/master/src/Academe/SagePay/Metadata/error-codes.tsv

The subset of that list with property values can be imported to this package for the mapping.

[judgej]

The non-cached helper method Helper::readErrorPropertyMap() will return the mappings as an array:

array(93) {
  [3015]=>
  array(3) {
    ["code"]=>
    int(3015)
    ["property"]=>
    string(23) "billingAddress.address1"
    ["message"]=>
    string(37) "The BillingAddress value is too long."
  }
  [3028]=>
  array(3) {
    ["code"]=>
    int(3028)
    ["property"]=>
    string(23) "billingAddress.address1"
    ["message"]=>
    string(31) "The BillingAddress is too long."
  }
  ...
}

[judgej]

clientMessage text added for all the mapped messages, which is added along with the property name if none are supplied by Sage Pay.

Further down the line, providing metadata to describe the validation rule that has failed will be useful. These may include identifying:

• Missing required filed.
• Field too long.
• Field containing invalid characters.
• Field containing an invalid value (e.g. invalid state "ZZ")
• Some other error,