Web Hooks and Responses

@Pay may send HTTP requests with details about relevant events (including successful and failed Transactions) to your application. Configure your application’s Hook Endpoints with @Pay on the API settings page of your Merchant Dashboard.


Hook Notifications are HTTP requests with two URL encoded parameters: details, and signature:

1
2
3
4
5
6
7
8
9
POST /atpay/endpoint
Accept: */*
Content-Type: application/x-www-form-urlencoded
Connection: close
Host: example.com
Content-Length: 1337

details=ABC&signature=XYZ

The Hook details are a JSON encoded hash containing information about the Transaction, and the signature is an HMAC SHA1 of the details parameter with your Merchant’s Private Key. Your application should verify the signature of all Hook Notifications.

The Pre-Sale Hook

Before @Pay sends a request to your Payment Gateway, we will evaluate Pre-Sale Hook Notification responses from your application. You may wish to use a Pre-Sale Hook to perform inventory checks.

If your Hook Notification response contains an HTTP status code between 200 and 299, @Pay will continue processing the Transaction. If your Hook Notification response has a status code between 500 and 599 then @Pay will consider the response an error and trigger Error Hook Notifications with further information. Any other status codes indicate @Pay should not process the transaction.

The Transaction Hook

If @Pay completes a request to your Payment Gateway successfully, we will trigger a Transaction Hook Notification.

The Further Action Required Hook

When Further action is required by a customer during Transaction processing we will trigger an FAR Hook Notification. Depending on what action is required, the hook response will include a new verification token, a mailto link and/or a signup url.

The Error Hook

When an error is encountered during Transaction processing, we will trigger an Error Hook Notification. This may result from either inbound email messages or from web-based transactions.

Retries

Except in the case of the Pre-Sale Hook, which is only attempted once, if your Hook Endpoint responds with a status code not between 200 and 299, @Pay will retry the request up to 10 times within the span of 28 hours before dropping it.