Serverside Callback Integration

Callback Structure and Behaviour

To ensure that users receive their virtual currency or premium service after successfully completing an offer or payment, you need to create a callback URL on your server. Fyber is going to request this callback URL whenever a new transaction has been completed.

There are several HTTP GET parameters we are adding to the callback URL whenever we notify you about the payout to a user. The URL below is an example for a callback request to your system.

  1. uid: The ID of the user to be credited.
  2. sid: (optional, recommended) The request signature, which you should verify to ensure the request’s authenticity. It will be included if you have specified a security token when creating your application. The sid is computed as a SHA1 hash of the request parameters: sid = sha1(security_token + user_id + amount + _trans_id_ + pub0 + pub1 + pub2 + …) The security token should be stored inside your application in a way that is absolutely inaccessible to users.
  3. amount: The amount of virtual currency the user gets credited. This may also be a floating-point number. Please convert it into an integer by cutting off the digits after the decimal point. This will ensure consistency between the amount of currency displayed in the offerwall and what the user actually should be credited. However, for the calculation of the SID it is mandatory to use the original floating-point amount as it was sent during the callback request.
  4. _trans_id_ (optional, recommended) The unique transaction ID in the form of a UUID (“Universally Unique Identifier”). Use this to check whether the transaction has already been processed in your system. Example ID: “82b11630-9623-11de-9207-002084162f67”. To receive it, add ?_trans_id_= to your callback URL when setting up your application.
  5. custom parameters: (optional) It is possible to pass custom parameters (called pub0, pub1, … , pub9) to the Fyber platform when requesting the offers, so you can perform any kind of tracking you need. The custom parameters will be passed back to your system during the callback. Just add the parameters when requesting the offers.

Whitelisting Fyber IPs

If your server has restrictive security settings and/or is protected by a firewall, you may have to unblock Fyber’s servers’ IP addresses in order to receive callback requests. They are as follows:

IP Address
146.0.239.0/24
85.195.83.44

Note: In 146.0.239.0/24, /24 is a subnet mask - see this explanation for more details on subnet masks. You need to whitelist multiple IP addresses.

Fyber Response

Fyber’s server will decide whether the callback request was successful based on the HTTP status code of your response:

  • Response: A successful callback needs to return a blank HTTP 200 status code. Please ensure that you only return a blank HTTP 200 status code if crediting the user was successful.

  • Redirects: Fyber’s servers will follow HTTP redirects (status code 301 / 302), however, all redirect locations must be absolute URLs, as specified in the W3C standard: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.30

  • Unsuccessful callbacks: If an error occurs on your side, please do not send back the error message to us with an HTTP 200 status code. Fyber’s system would interpret the callback as successful and show the user that he received his virtual currency. Instead, send an HTTP error code (4xx or 5xx) and Fyber’s server will resend the request to the callback URL up to 25 times, with increasing delays.

  • Duplicates: If you identify the callback request as a duplicate based on the trans_id, we recommend you to send a HTTP 200 status code response and ignore the request. Otherwise Fyber’s server would try to resend the callback as indicated above.

Please test your callback handling with the callback test available on the Application tab in the control panel.

PHP Code example

<?php
$security_token = <INSERT YOUR SECURITY TOKEN HERE>;
$amount = $_GET['amount'];
$userid = $_GET['uid'];
$transid = $_GET['_trans_id_'];

// Transaction ID: Only set/available if requested by attaching the _trans_id_ parameter to the callback url.
// _trans_id_ is always included in the SID calculation, so please ensure to have it as a param of your callback url

// The statement below assumes you don't have any pubX parameters defined.
// These are parameters set when redirecting the user to the Fyber offerwall.
// All pubX (i.e. pub0, pub1, pub2, ...) are passed through unmodified to
// the callback. Note that they are included in numerical order in the sid
// computation, e.g.
// $sha1_of_important_data = sha1($security_token . $userid . $amount . $transid . $_GET['pub0'] .$_GET['pub1'] ....); would be the sid in that case.

$sha1_of_important_data = sha1($security_token . $userid . $amount . $transid);

if ( $_GET['sid'] == $sha1_of_important_data ) {
    //<CALL WAS GOOD, PAYOUT TO USER, SEND HTTP200 CODE AS ANSWER >
}else{
    //CALL WAS WRONG, DO NOT PAYOUT TO USER, SEND HTTP400 CODE AS ANSWER header ("HTTP/1.0 400 Bad Request: wrong SID");
}
?>