Postbacks

How to get 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.

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”

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.

Sending postbacks from website

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 you've added website as landing page, you don't need to add that parameter to URL, it's already sending.

Sending postbacks on PHP

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);

Sending a postbacks on 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>

Sendings postbacks from the website with Click Client

Click Client stores subid in the sessions, so you don't need to worry about sending subid between pages. Use $_SESSION['subid] in the code where sending postback:

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

Sending postbacks by tracking pixel

Use this solution only if others aren't suitable

<img src="%%POSTBACK_URL%%?status=lead&payout=10&currency=usd" width="1" height="1" />

Sending postbacks after submitting form

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 a postback is not working?

Postbacks often don't work because of the following reasons:

  • direct URL is used instead of offers;
  • test postback with unreal subid is sent. Keitaro accepts subid only if the click is in a database;
  • an affiliate network isn't chosen in offer's settings.

All postbacks are logged, and a log can be checked on “Maintenance > Logs > Received Postbacks”.

"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 work testing postbacks in the affiliate network?

All the postback must contain real subid. If you're testing postback without existed subid, Keitaro ignores it.

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 do already exist 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