Handling Events

Events keep your application data synced with the gateway, so that you are always up to date. Also, they provide a way for you to react to the events which happen outside of your control/view, e.g. subscription charge failed.

Setup

In order to start receiving Events, you need to create a Callback URL (using the Administration tool).

This URL is the endpoint used by your application to listen for Events. Whenever an Event is triggered inside a gateway, you will get a POST notification to the Callback URL, with the body of the message being the Event itself.

Parsing of received data

Luckily, you don't need to parse the data received on the Callback URL directly; everything you need to do is to feed the Library method parse(incomingData) with the received data.

// First read POST data received on your Callback URL using your framework
$postBody = 'post-body-received-on-your-callback-url';
$event = Pencepay_Event::parse($postBody, true);

// Handle Event here any way you wish
$event->eventType;

You got yourself an Event now, and can use it to do what you need, e.g. send an email to a customer.

Security

Notice the second parameter in the parse method. If you pass a true here, library will assume that the received Event is insecure, and re-retrieve it using just the received Event UID from the gateway directly. Why? So that you can be sure you got it from the gateway, and not from an imposter trying to hack your system with false Events.

Of course, you still need to check in your system that you do multiple important actions (e.g. adding double credits) to the customer based on an imposter sending several (valid) Events to your Callback URl. We suggest saving an Event UID with the action you took, to be sure you apply your action only once.

Events are sent from our servers at 89.19.240.*