Receiving postbacks

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 set up a postback with an affiliate network (video)

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:

• List of tokens
• 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.

Important! The conversion in Keitaro is tied to a click, thus one click can't be of two or more states at the same time. That's why it's impossible to record a single conversion as a lead and a sale at the same time especially in the cases when the Lead is a Registration that transfers late into Sale=Deposit.

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

In order to carry out mathematical operations with payout (upsell, payment cancellation, revshare) each postback should have a unique tid. If the tid is the same as in the previous postback then the payout amount will be overwritten by the last one.

The tid in the postback allows you to add or subtract payout amount in the following states:

• Lead → Lead.
• Sale → Sale.
• Sale → Rebill.

When the Lead - Sale state changes, the payout amount will be taken from the postback with the sale status.

How to teach Keitaro different statuses

The names of the statuses can be any, but all these statuses should be connected with Keitaro statuses. The connection can be established with postback parameters, e.g. we have 3 statuses accept, confirm, reject, then we need to add to the postback the following:

&lead_status=accept&sale_status=confirm&rejected_status=reject

You can add “Original Status” column in reports to see the received statuses.

Sending postbacks from website

First, you need to configure the passing of the subid of the 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://tracker.com/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>

Open Maintenance > Postback URL, copy postback URL and replace POSTBACK_URL in the code.

Now, we must add parameter ?subid={subid} to website URL.

To send a posback, use function: sendPostback(params), e.g.:

<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 KClient PHP

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

ending 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

Please read sending postbacks on PHP or sending postbacks on JS above.

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://tracker.com/123/postback?lead_status=register&sale_status=paid,rebill&rejected_status=refund...

Status “register” is lead. 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”.

SubId not found "any_subid_value” error

Possible reasons: 1.Save Clicks option is disabled in a stream. 2.This incoming postback is for a click which is already deleted from the database.

Incorrect SubId

Reasons:

• Offer visitor subid is not transmitted in the stream;
• Subid is not returned in postback;

Solution:

• Check that the URL contains subid transmission through {subid} macros. Check subid transmission instructions in Help section at the partner page.
• 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" already exists. Postback ignored.

Reasons:

• Postback notification has been sent twice.
• 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 do test postbacks from affiliate networks not work?

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

How to ignore postbacks of a certain status

Add the statuses you want to ignore to the Postback URL the following way:

&ingore=trash,reject,visit

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.

How to change Postback Key

Login to your server via SFTP, open application/config/config.ini.php file, find postback_key = line and change the key value.

How can a new affiliate network template be added?

Send us a email support@keitaro.io with the information:

1. the name of the network;
2. the parameter for click id;
3. the list of available parameters;
4. the statuses available in the network.