Skip to main content

Callback

It's a recurring problem that information about a completed payment doesn't reach the webshop, which has the unfortunate outcome that the order information isn't created, the order status isn't updated, and the order confirmation email isn't sent to the customer.

To avoid this, ePay offers a callback service, which is a way to make sure that the shop system receives the vital payment information.

ePay's callback service

The callback service from ePay consists of a Microsoft. NET WebClient component.

The WebClient is a very simple component which - contrary to ordinary browsers - cannot handle flash, javascript, frames, iframes or other advanced logic. The component can only activate a webpage with a number of GET parameters. It is your responsibillity to catch these parameters and update your system with them.

How to define callbacks​

Callbacks are established in two ways: Either by using the parameter callbackurl in the payment form or by defining the URL in the ePay administration under Settings -> Payment system. If you use one of these two methods, the defined URL will be put on queue with the same GET parameters as your accepturl.

Notice

Callbacks only work on ports: 80 and 443

How callbacks work​

ePay has a service that calls the URL destinations in the callback queue. When callbacks are activated, the service calls the URLs that haven't been called or that failed to receive the call. A callback is asynchronously compared to the rest of the payment process, in which it's expected that the accepturl is called before the callbackurl.

If an error occurs in the callback, for instance, if your URL cannot be accessed by the callback servers, or your URL returns an error (404, 500, etc.), ePay tries to call your URL once every hour for a maximum of 24 times (1 day).

Example of a callback​

Below is an illustration of how the callback operates. The following is a description of the process during callback.

Illustration of how the callback operates

  1. A customer places an order in a webshop. The payment information is sent to the ePay payment server. An accepturl and a callbackurl are contained in the payment information. It's important that the order is stored in the database of the webshop before the order is paid. Otherwise the order information is lost in case of communication errors!

  2. The payment is approved by ePay, and a response to the webshop's callbackurl is created and put in queue on ePay's server. If instantcallback is 0, this call happens asynchronously. Otherwise, it happens instantly (before the customer is sent to the accepturl).

  3. The customer is now sent to the store's accepturl and shown an order confirmation. It is no longer necessary to update the order in the system or send an order confirmation as this happens later through the callback.

  4. Every minute the ePay callback server sends a callback to the receivers that are on queue. Please note that it might take longer during peak traffic times. For this reason, it's important that the shop doesn't expect callbacks within a certain time period or before the accepturl is called. The latter is especially noteworthy as the entire process takes place asynchronously!

  5. Callbacks are sent to the webshop's callbackurl. The same information is sent as GET parameters to the accepturl. The information includes among other things: Order ID, timestamp, amount, currency, Fraud Fighter notifications, and MD5 security check.

  6. If an error occurs during the callback process, the ePay server will resend the call after an hour. Possible sources of error could be the callback server failing to access the webshop's callbackurl or an error in the shop's system (HTTP error code 404, 500, etc.). In general, the callback server sees anything but HTTP code 200 as an error. HTTP code 200 means OK.

Each time an error occurs an email is sent to the email address set up to receive system errors, including callback errors, in your ePay administration. It's up to the administrator of the webshop to investigate the cause of the callback error.

Instant callback​

If you need to receive the callback before the user is redirected to the accepturl, you can add the parameter instantcallback to the payment form as shown here:

<input type="HIDDEN" name="instantcallback" value="1" />

ePay will send callbacks before the customer is sent to your accepturl.

However, if the call cannot be made (for instance, if the webshop server returns an error 500), the callback is put on queue. Once every hour for up to 24 hours ePay will make the call again.

Block IP address​

Some developers block the IP address from which the callback is made, apparently due to safety concerns. However, we do not recommend this as the server transmitting the callbacks might change in case of, for instance, operation and maintenance.

Instead of blocking the IP address, you should use MD5 security check. Moreover, you can remove the parameter callbackurl from the payment form, and enter the hidden URL to which the callback is made in your ePay administration under Settings -> Payment system.