# Receiving postbacks
- How to set up a postback with an affiliate network (video)
- How to get postback URL
- Where Can I Get Postback URL?
- Postback Parameters
- Conversion statuses
- How to teach Keitaro different statuses
- Sending postbacks from website
- How to send upsells (rebills)
- Incorrect statuses
- What if a postback is not working?
- SubId not found "anysubidvalue” error
- Incorrect SubId
- Conversion by pair "SubId + tid" already exists. Postback ignored.
- How is currency converted?
- Why do test postbacks from affiliate networks not work?
- How to ignore postbacks of a certain status
- Which affiliate network templates do already exist in Keitaro?
- How to change Postback Key
- How can a new affiliate network template be added?
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.
# Postback Parameters
subid
— unique click code (required)tid
— Transaction or action IDpayout
— money earnedcost
— costs of the clickstatus
— conversion statuscurrency
— 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.
# 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.
- 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'];
}
- 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>
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¤cy=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:
- the name of the network;
- the parameter for click id;
- the list of available parameters;
- the statuses available in the network.