NotificationInterface method(s) for responding to the gateway

[judgej]

On the heals of #148, there is no common defined way to respond to the remote gateway after recieving a notification.

All notifications must be responded to appropriately, so that the remote gateway knows the notification has been received, handled, passed any signature tests etc. This has been left up to each driver to define so far, which is great until you want to wrap the notification handlers in a generic way.

Ideally the response will be a HTTP response object, but I'm not sure if Omnipay 2.x will support that?

At the moment we have drivers that echo the result text and leave the merchant site to exit with a 200 code. We may not need more than that for the drivers we have now, and may be enough for 2.x. Or maybe we should have methods to return the HTTP code, body and any additional headers that may be needed, so the merchant site can construct the response that the gateway needs? Not sure if that makes returning a PSR-7 response object later more difficult - I expect not.

Any thoughts?

Before I start proposing method names, I need a better feeling about what the various gateways are expecting back from the drivers. I also believe the drivers should NOT exit after responding, since the merchant site may need to do further processing; they should just provide the data and/or tools for responding appropriately in a standard way.

[barryvdh]

We can return a response, just like the redirect response (Symfony, not psr7), with a method to send the headers and echo content.
Also, no need to worry about 2.x as 3.0 is pending release soon.

[judgej]

Would calling send() on the notification object make sense? It may be more consistent with other messages, but I suppose getResponse() is probably more appropriate.

I'll probably just roll out whatever we decide on the few 2.x drivers I have and we can leave it as a recommendation rather than changing the spec. For 3.x we can make it more formal.

[barryvdh]

Of something like redirect: reply() and replyResponse() or something.

Something related about this, I want (or already did actually) to drop the exit after sending. This breaks the response flow, perhaps unexpected. But it's breaking so for 3.x only.

[judgej]

I've gone for getResponse() on the PAYONE driver in a branch for now, and will see how that goes (Aimeos is trying this out). The name can change if something else is better.

Yes, the exit needs to go. By returning the Symfony response object, the site can send() the response immediately, and still carry on processing/closing down etc.

In addition, sometimes the site needs to feed some results into the response, such as an indication of whether the notification was accepted or not, and sometimes a text message if it was rejected for any reason. This is also the point at which the final redirect URL is provided, to take the user to the final payment screen. It will be gateway-specific, but I think there needs to be some flexibility in data that is provided for the acknowledgement.

And one more thing, the transaction status has one of three possible values: success, pending or failed. I'm finding a additional status of error would be handy. This would be used if, for example, any hash signature checks failed or some data is not what was expected. An exception is no good, because we still need to acknowledge the notification server request.

https://github.com/thephpleague/omnipay-common/blob/master/src/Common/Message/NotificationInterface.php#L10

[judgej]

I'm trying to use the acceptNotification interface on a new Authorize.Net driver with Omnipay 3.0 beta. I'm having difficulty getting it to fit my use-case.

For a typical Omnipay request message, the message is given the objects to make a request to the remote gateway (or fake a request) and then get a response in return. That response is fed into an Omnipay response object for the merchant site to act on.

For the notification messages, what needs to happen is usually the other way around. In this case a server request comes in to the merchant site. The notification message grabs and parses all the data (including HTTP headers for some gateways) in it to provide a standard interface to the merchant site. Now, sometimes the gateway needs a specific response so it knows the notification has been received and accepted, often based on the notification data that was sent and some additional response from the merchant site. Some gateways do not need a specific response (just a HTTP 200 will do for them). But either way, the notification message needs to return a HTTP response - something to return to the gateway.

In order for this notification message to be successfully initialised, it extends the Omnipay AbstractRequest. This, I believe, sort of turns the purpose of the class upside down. I think we need an AbstractNotification class to put more meaning on these methods. For example, getData should return the parsed ServerRequest data, and not the parameters that have been fed in to send to the gateway. The sendData method should not be trying to send anything to the gateway, but instead return the HTTP response that the merchant site should return to the gateway once it has finished logging and processing the notification just received.

Right now, every time I implement a notification handler, I feel like I'm fighting against Omnipay, trying to shoe-horn the wrong things into it. I'm going to try to create an AbstractNotification in the 3.0 Authorize.Net API driver to explore this a little further.