Support the Notify handler (webhooks)

[judgej]

Authorize.Net supports "webhooks" that allow it to feed all authorisation results direct to the merchant site as a server-to-server request. It looks like this needs to be registered with the account and is not something enabled by default in the API (so testing webhooks with the sandbox may not be possible).

On return to the merchant site from the Hosted Payment Page, a GET is performed with the given return URL and NO further details. This means that if a web hook is not used to record the result, then the merchant site must explicitly fetch the transaction details, so an request is needed for that too.

[judgej]

I'm not entirely sure how you fetch a transaction authorised via the Hosted Payment Page. The response that provides the token for the page does not return the transId that the gateway generates for the transaction. The API that provides the details of the transaction seems to require the transId to match the transaction to return:

http://developer.authorize.net/api/reference/#transaction-reporting-get-transaction-details

So how do you get the transaction details without knowing the transaction ID?

It could be that either transId or refId can be used, but that's not explained well in the documentation. The first is the gateway-generated ID and the second is generated and supplied by the merchant site. Some experiments are needed.

[judgej]

The transaction fetch will only work with a transId (the ID generated by the gateway).

The choices seem to be:

• Run the hosted page in an iframe and register a "communicator url" for passing the result details back to the merchant site using JS and AJAX.
• Run the hosted page in a "redirect" mode and set up a web hook to grab the details in a back-channel. This will provide some of the details needed. including the all-important transId, so the getTransactionDetails API will still need to be called up to get the full details.

Those are the two choices.

The webhooks are set up using the webhook API, so this driver probably needs a webhook configuration mode too, so an merchant site can set itself up. Creating a webhook defines the URL and the events that will be sent to that URL. Multiple webhooks can be defined, and enabled and disabled as needed. They can also be set up manually using the account UI.

[judgej]

The admin page to create web hooks looks something like this:

We need to know the minimum hooks that are needed to catch all authorisation results.

[judgej]

The webhooks are listed here and need some decoding to turn them into classes. because the webhooks are newer, and do not support XML, there is no DTD to give us object names, so we are going to have to make some up. I'll check out any official libraries to see if there is anything we can grab from those.

[judgej]

The webhooks management APIs have _links in all their responses. I believe that is the HAL format of HATEOS...possibly? The Content-Type is just application/json; charset=utf-8 and not application/hal+json, so it's not formal HAL. There will be some library that will parse this - the _links at least - so we don't reinvent this.

For example, the Get Notifications API returns this:

{
    "_links": {
        "self": {
            "href": "/rest/v1/notifications?offset=0&limit=100&from_date=3/26/2018 11:08:56 PM&to_date=5/25/2018 11:08:56 PM"
        },
        "next": {
            "href": "/rest/v1/notifications?offset=100&limit=100&from_date=3/26/2018 11:08:56 PM&to_date=5/25/2018 11:08:56 PM"
        },
        "last": {
            "href": "/rest/v1/notifications?offset=199&limit=26&from_date=3/26/2018 11:08:56 PM&to_date=5/25/2018 11:08:56 PM"
        }
    },
    "notifications": [
        {
            "_links": {
                "self": {
                    "href": "/rest/v1/notifications/8f5f0f4e-96c3-46e5-9819-dc535cef2238"
                }
            },
            "notificationId": "8f5f0f4e-96c3-46e5-9819-dc535cef2238",
            "deliveryStatus": "Delivered",
            "eventType": "net.authorize.payment.authcapture.created",
            "eventDate": "2018-03-28T17:30:33.193",
            "webhookId": "2fe49df5-23be-4204-a112-044302543216"
        },
        {
            "_links": {
                "self": {
                    "href": "/rest/v1/notifications/074ce41d-d3f2-40ed-a397-56362c941d7b"
                }
            },
            "notificationId": "074ce41d-d3f2-40ed-a397-56362c941d7b",
            "deliveryStatus": "Delivered",
            "eventType": "net.authorize.payment.authcapture.created",
            "eventDate": "2018-03-28T17:30:33.193",
            "webhookId": "559a12de-c62f-4f88-9008-1d8867645ff0"
        },
        ...etc
    ]
}

[judgej]

It should be noted also that the webhook management API is very much REST oriented. Unlike the payment APIs that share a single endpoint, each resource has its own endpoint. It also has its own way of returning errors. It almost feels like it needs to be a different package.