Use PaymentGatewayException:: createForPayment()

I've patched around this for years because the error message was useless for users. I received UNPROCESSABLE_ENTITY:INSTRUMENT_DECLINED which is effectively a permanent error which came up as "unexpected... try again" which they really shouldn't be. The end-user message was actually contained in the body of the returned response instead of returned "message" - neither of which is given to the user. See full error response below.

Payment Gateway actually has 3 newer exceptions which provide a little more clarity:

Drupal\commerce_payment\Exception\DeclineException (extends PaymentGatewayException)
Drupal\commerce_payment\Exception\HardDeclineException (extends DeclineException)
Drupal\commerce_payment\Exception\SoftDeclineException (extends DeclineException)

I converted most payment gateway exceptions into either Hard or Soft exceptions and changed the messaging appropriately.

For the Payment Gateway implementation to be able to set a USEFUL and meaningful error message to the end user would be excellent - the existing hard-coded error message is in Commerce, so it would require changes there.

When I was coding my work-arounds (hacks), I could see that being able to set the useful returned message and have it printed out instead of the hard-coded messages would be the best way to do it. ie add "get/setUserErrorMessage(translatable $msg)" which would really be given to the user instead of the generic one - fallback to generic if no user message set.

For reference, this is the full error received from paypal in my case, as the json decoded contents of the GuzzleHttp\Exception\BadResponseException::getResponse()

Array
(
    [name] => UNPROCESSABLE_ENTITY
    [details] => Array
        (
            [0] => Array
                (
                    [issue] => INSTRUMENT_DECLINED
                    [description] => The instrument presented  was either declined by the processor or bank, or it can't be used for this payment.
                )

        )

    [message] => The requested action could not be performed, semantically incorrect, or failed business validation.
    [debug_id] => XXXXXXXXXXXXX
    [links] => Array
        (
            [0] => Array
                (
                    [href] => https://developer.paypal.com/docs/api/orders/v2/#error-INSTRUMENT_DECLINED
                    [rel] => information_link
                    [method] => GET
                )

            [1] => Array
                (
                    [href] => https://www.paypal.com/checkoutnow?token=XXXXXXXXXXXXXXXXX
                    [rel] => redirect
                    [method] => GET
                )

        )
)