How to detect/handle card failure from Payment Provider's callback URL

Question

I have implemented a payment gateway for SwipeHQ's 1-off payment mechanism. It's similar to PayPal's mechanism in that there's an LPN that notifies CiviCRM of the success/failure of the transaction, and also a callback URL.

SwipeHQ adds a couple of URL parameters to the callback URL to notify of success/failure. These are in addition to the mechanisms in the LPN.

e.g. &user_data=619%2C7%2C5a00dbadde859a90b262eb532f863d98%2C%2C%2C2%2C%2C&response_message=INVALID%20CARD%20NUMBER&response_code=14&result=declined

My issue is that the standard Thankyou page in Civi has no way of picking up this important info and using it to instruct the user to try again. The message there is "Thank you for your payment" or whatever is set up as the thank you message.

So what's the best/right way to handle this?

• is there a hook that could be used on the Thank you page to change the message?
• or might it be easiest to just override the Thank you php and tpl files in order to display appropriate messages? I'd rather that this could be integrated into the payment plugin rather than having to mess with overrides though.
• perhaps just some jQuery added to the page to do some dynamic HTML rewriting based on URL params?
• or as suggested in another question/answer, use the LPN trigger URL to give to the payment provider as the callback, and integrate the checking into that file. It would end with a redirect back to the thank you page on success.

The latter seems like a possibility, but may have some issues:

How would you handle HTML display in the case that it's not "success"? Just spit stuff out directly from the LPN? But this wouldn't have any other templating etc from the CMS. What other pages could be used to redirect to?

Thanks in advance for any advice.

Answer 1

I would -

• make the return page a CiviCRM IPN callback - civicrm/payment/ipn/XX (where XX is the database ID of the payment processor in use).
• from this IPN callback, which is a method in your processor, return a 302 to the Thanks page if the transaction "checks out", and the Unsuccessful page if not

Probably the best "reference" payment processors are NOT those in core, but those based on Omnipay.

• Hitting civicrm/payment/ipn/XX will land you in CRM_Core_Payment::handleIPN() which should in turn call your processor's $processorInstance->$method(); determined via CRM_Core_Payment::handlePaymentMethod().
• Eileen's Github probably has a few Omnipay based processors worth checking out.