Postbacks (incoming)

Keitaro can accept postbacks from partner networks. To receive postback you need to add an affiliate network at the page “Affiliate Networks”. First check if your affiliate network is in the template. In this case, you immediately get the ready postback. If there is no your affiliate network, then you can create a Postback URL by yourself. Read about it below.

How to Create Postback URL

When you add an affiliate network you will see a base address in the field “Postback URL”. Now you need to find documentation about postback settings on the affiliate's website. You need:

  1. List of tokens
  2. Instruction about passing a subid/clickid

The list of tokens will help to form a chain of parameters. For example, there are tokens at the advertising network {SID1}, {STATUS}, {PAYOUT}. So we add to the address such parameters: &subid={SID1}&status={STATUS}&payout={PAYOUT}. The full list of available parameters of Keitaro you can see at the section below.

Now you need to determine through which parameter you can pass your subid. For example, it is passed through sid1. So, you need to type sid1={subid} in field “Offer Params”.

If you don't see any records at the conversion log, see the page “Maintenance > Logs > Received postbacks”.

Where Can I Get Postback URL?

On page “Maintenance > Postack URL” or create a new affiliate network.

Conversion statuses

In Keitaro conversion has 4 states:

  • Lead — lead was received, but the payment has not yet been transferred. In affiliate network this state is called “Hold.”
  • Sale — lead is confirmed, the payment was made.
  • Rejected — lead was rejected by the affiliate network. If previously the conversion had a “Sale” status, the payment is canceled.
  • Rebill — the conversion in this status indicates that the visitor has made another purchase or extension of the service. You can see this conversion in the Conversion report, but the indicators of leads and sales are not increasing at the same time. If the affiliate network supports upsells (rebills), you must enable the “Upsell” option in the settings of the offer.

Possible state transitions:

  • Sale
  • Reject
  • Sale → Rebill (if the option “Upsell” is enabled in the offer)
  • Lead → Sale
  • Lead → Sale → Rebill
  • Lead → Reject (if the option “Upsell” is enabled in the offer)

Such a change of states “Lead → Lead” is also allowed. This allows you to organize a multi-stage lead management. For example, “Cart → Order → Payment → Call”.

The names of the statuses can be any, but they must necessarily be associated with one of the system statuses. You can bind them through the parameters of the postback. For example, we have 3 statuses: accept, confirm, reject. Then we pass in the postback the following:

&lead_status=acceprt&sale_status=confirm&rejected_status=reject

In the conversion report you can add the “Original status” column to see the received statuses.

Postback Parameters

  • subid — unique click code (required)
  • tid — Transaction or action ID
  • payout — money earned
  • cost — costs of the click
  • status — conversion status
  • currency — specify any currency (usd, eur, rub).
  • sub_id_1..10
  • extra_param_1..10
  • return — in case aff. network awaits for specific response. For example, “OK” (return=OK).

These parameters are used to “teach” Keitaro the statuses of the affiliate network

  • sale_status — which status is considered as sale. Example: “&sale_status=status1,status2”
  • lead_status — which status is considered as lead. Example: “&lead_status=status3,status4”
  • rejected_status — which status is considered as rejected. Example: “&rejected_status=status5,status6”

Sending Postbacks from Website

Postbacks allows you to integrate a landnig page, E-shop or CRM with Keitaro.

First, you need to configure the passing of the “Sub ID” click. It is passed via streams by adding a parameter subid={subid} to the URLs (offers, landing pages, direct URL).

If traffic goes directly from the source to the landing page or your site, you can use the tracking script. Read more about it on the page Tracking script.

Here is an example of sending postback on PHP.

1. On the pages where the first visit to your site takes place, you need to take subid and save it to the session:

<?php
if (!headers_sent() && !session_id()) {
      session_start();
}
if (isset($_GET['subid'])) {
    $_SESSION['subid'] = $_GET['subid'];
}

2. After a user made an action we send a postback:

$url = 'http://tds/POSTBACK_KEY/postback?payout=100&status=sale&subid=' . urlencode($_SESSION['subid']);
file_get_contents($url);

Or through a pixel:

<img src="<?php echo $url;?>&return=gif" width="1" height="1" />

Sending a postback with JS

Insert this code to your page:

<script type="text/javascript">
var postbackUrl = 'POSTBACK_URL';
function sendPostback(params, cb) {
    var pattern = new RegExp('subid=([^&]+)');
    var params = params || {};
    params.subid = ((v=window.location.search.match(pattern))==null?'':v[1]);
    params.return = 'img';
    var img = document.createElement('img');
    img.src = postbackUrl + '?' + paramsToString(params);
    img.height=0;
    img.width=0;
    img.onload = cb;
    document.getElementsByTagName("body")[0].append(img);
};
function paramsToString (params) {
    var str = [];
    for (var p in params) {
        if (params.hasOwnProperty(p)) {
            str.push(encodeURIComponent(p) + "=" + encodeURIComponent(params[p]));
        }
    }
    return str.join("&");
};
</script>

Change POSTBACK_URL into yours. You can take Postback URL on “Advertising Networks” page, while adding a new network.

Now you can send a posback calling the fuction: sendPostback(params)

An example:

<script type="javascript/text">
sendPostback({status: 'sale', revenue: 100, currency: 'rub', sub_id_10: 'item 828'})
</script>

An example with callback function:

<script type="javascript/text">
sendPostback({status: 'sale'}, function(){
  $('form').submit();
});
</script>

In case you're using “Preload” method for landing page. You must replace string:

params.subid = ((v=window.location.search.match(pattern))==null?'':v[1]);

to

params.subid = '{subid}';

How to send upsells (rebills)

At first, check that the option “Resale” is enabled at your offers. To send a postback with upsells you need to pass, except “subid”, also the additional parameter “tid”.

http://domain.com/123/postback?subid=123&tid=456

The value of “tid” must be unique for every next upsell.

Incorrect statuses?

To “teach” Keitaro new statuses pass the parameters “lead_status”, “sale_status”, “rejected_status”. In them set new statuses.

Example:

http://tds.com/123/postback?lead_status=register&sale_status=paid,rebill&rejected_status=refund...

Status “register” is lid. Statuses “paid” and “rebill” are the sale. Status “refund” is deviation.

What if postback is not working?

Open page “Maintenace > Logs > Postbacks”. If you see errors there, read the information below.

"Incorrect SubId ..."

Reasons:

  1. Offer visitor subid is not transmitted in the stream;
  2. Subid is not returned in postback;

Solution:

  1. Check that the URL contains subid transmission through {subid} macros. Check subid transmission instructions in Help section at the partner page.
  2. Check that there is subid transmission in postback. Check which macros is used for it in Help section at the partner page. Also try to Make a New Postback URL

"Conversion by pair "SubId + tid" is already exists. Postback ignored."

Reasons:

  1. Postback notification has been sent twice.
  2. Rebill was made, but parameter “tid” wasn't unique.

How is currency converted?

At the time of the receipt of payment the amount of money will be converted according to current quotes from Google Finance to a currency which is set at Keitaro settings.

Why doesn't a tested postback from an affiliate network add a conversion?

Check if during the test an existing sub_id is passed. You can take it from the one of the transitions in the detail report.

Example: connecting postback to admintad.com

  1. On the page “Affiliate networks” press the button “Create”.
  2. Choose from templates “admitad.com”;
  3. Copy “Postback URL”;
  4. Go to admitad.com and open the page “Tools > Postback URL”;
  5. Press “Add Postback URL”;
  6. At the “Status” stroke tick all statuses;;
  7. Paste the previously copied Postback URL into the “Link” field;
  8. Press “Save” at the bottom of the page;
  9. If you need to add offers add subid={subid} to URL.

Which affiliate network templates are already exists in Keitaro?

7offers.ru, actionpay.net, affiliatecube.com, ad1.ru, ad2games.com, adinfo.ru, actionads.ru, actionpay.ru, adwad.ru, advertstar.ru, advertise.ru, admitad.com, biznip.ru, cityads.ru, everad.ru, cpagetti.com, cpaexchange.ru, cpapolice.biz, cpate.ru, clickdealer.com, ctr.ru, gdeslon.ru, gg.agency, himba.ru, hotpartner.biz, iqoption.com, instal.com, kma.biz, leads.su (tradeleads.su), leadprofit.biz, leadtrade.ru, monsterleads.pro, M1-shop.ru, moneysyst.biz, myragondigital.ru, mobilecashout.com, shakes.im, shakes.pro, primelead.com.ua, salesdoubler.com.ua, unileadnetwork.com, wapclick.io, wapcombine.com, wap.click, mcwap.ru, mobionetwork.me, richwap.ru, money4leads.biz, juddy.biz, my.zorkanetwork.com, ero-advertising.com, adult-dealer.net, wap.cash, leadsale.com, cpalead.com, clicktimes.ru, m3dcash.com, leadgid.ru, zoolley.com, expertmobi.com, maxbounty.com, cpaway.com.

To create a new template, please send us the following information:

  1. List of available tokens
  2. Instruction about sending subid/clickid
  3. Payout currency