PayPal module shows raw JSON error (“CARD_TYPE_NOT_SUPPORTED”) directly to users — need help sanitizing message

[JesusSuarz]

Hi everyone,

I’ve been dealing with an issue related to the official PayPal module in WHMCS. When trying to complete a credit card payment through PayPal Card Fields, WHMCS sometimes displays the raw JSON error response from PayPal directly on the checkout page.

For example, if a user tries to pay with an unsupported card type such as Maestro, the page shows something like this:

/v2/checkout/orders/3P84404894957445F/confirm-payment-source returned status 422 (Corr ID: f7102346dddd8).
{"name":"UNPROCESSABLE_ENTITY","details":[{"issue":"CARD_TYPE_NOT_SUPPORTED","description":"CARD_TYPE_NOT_SUPPORTED"}],"message":"The requested action could not be performed, semantically incorrect, or failed business validation.","debug_id":"f7102346dddd8","links":[{"href":"https://developer.paypal.com/api/rest/reference/orders/v2/errors/#CARD_TYPE_NOT_SUPPORTED","rel":"information_link","method":"GET"}]}

 

This response is clearly not meant to be shown to the end user, it looks like a system crash and includes unnecessary technical details. Ideally, the user should just see a friendly message such as: “Your card type is not supported. Please try another payment method.”

I contacted WHMCS support, and they confirmed that this behavior has already been reported under Case #WHMCS-24146. However, they suggested using a hook like ShoppingCartValidateCheckout to intercept and sanitize the message before it’s displayed, but they couldn’t provide implementation examples.

So I’m looking for community input on how to handle this properly.

Main questions:

1. Has anyone managed to intercept these raw PayPal error messages and replace them with a cleaner message using a hook?

2. Is ShoppingCartValidateCheckout the correct hook to use, or is there a better one for this case?

3. Would it be more reliable to handle this with backend PHP (via a hook) or client-side JavaScript?

4. Has anyone found a temporary workaround for Case #WHMCS-24146?

Any example hook or suggestion would be really appreciated. The goal is just to prevent exposing raw API responses and improve the user experience during checkout.

Thanks in advance to anyone who can help or share some code examples.