Incoming postback: receiving conversions from an affiliate network

An incoming postback is the request with which an affiliate network tells the tracker about a lead, a sale or a rejection. You take the address in the panel and enter it in the network settings, replacing the macros in it with that network's macros. The general flow of receiving conversions is described on the How the tracker receives conversions page.

Where to get the address

The address is shown in two places in the panel. Both addresses work: the first points to the tracking domain, the second to the panel domain, and some parameters are named differently.

The Networks section («Сети»)

All roles except the financier can see the section. The owner and the admin can add and delete networks.

1. Open Networks.
2. In the Conversion postback URL («URL постбэка приёма конверсий») block, click Copy («Копировать»).
3. Paste the address into the affiliate network's postback settings.
4. Replace {click_id}, {status}, {payout} and {txid} with the network's macros.

The address looks like this:

https://track.example.com/api/v1/postback?subid={click_id}&status={status}&payout={payout}&txid={txid}

If an affiliate network is added to the list, the Postback URL («URL постбэка») column shows its address with additional parameters. Copy it with the copy («копировать») button in the network's row.

The wizard on the Postback tab

The owner and the admin can see the tab.

1. Open Settings → Postback («Настройки → Postback»). The block is called Incoming S2S postback («Входящий S2S postback»).
2. Choose a Source («Источник»).
3. Choose a Status («Статус»): lead, sale, rejected or hold. lead is selected by default.
4. If the source has a secret, enter it in the Source secret («Секрет источника») field. The panel does not show a saved secret.
5. Click Copy template («Копировать шаблон»). The message “Copied” («Скопировано») appears.
6. In the affiliate network, replace {subid}, {payout} and {transaction_id} with its macros.
7. If the network does not pay in dollars, replace USD with the payout currency code.

The wizard template:

https://panel.example.com/api/v1/postback?subid={subid}&status=lead&payout={payout}&currency=USD&tid={transaction_id}

The status value in the template is fixed. If the network passes the status as a macro, put the macro in place of the value.

The Copy template button is unavailable until a source is selected, and for a source with a secret — until the secret is entered.

Request parameters

For the network to return the click ID, pass it in the offer link with the {subid} macro, for example sub1={subid}. The parameter name is set by the network. The list of macros is on the Macros in links and pages page.

GET, POST and domains

The tracker accepts a postback with the GET and POST methods. In a POST body, parameters are passed as application/x-www-form-urlencoded or as a JSON object with the Content-Type: application/json header. The body size is up to 1 MiB. If a parameter is in both the address and the body, the value from the address is used.

The /api/v1/postback path works on the panel domain, on the main tracking domain and on campaign domains added in the panel. No authorization is needed.

How the status is determined

The tracker checks the status value in this order:

1. The lists in the postback itself. A value from lead_status is recorded as lead, from sale_status as sale, from rejected_status as rejected. With a value from ignore_status, the conversion is not recorded.
2. Conversion types on the Settings → Conversions («Настройки → Конверсии») tab. The first type in creation order whose values contain this status is used.
3. If there are no matches, the status is recorded as it came, in lowercase.

Example: the network sends approved, declined and pending, and you do not need to count pending conversions. Add to the address:

&sale_status=approved&rejected_status=declined&ignore_status=pending

The hold status cannot be set through the lists in the address — create a conversion type for it.

Payout and currency

Where the amount comes from depends on the offer settings:

• The offer has the Payout from postback parameter («Выплата из параметра постбэка») checkbox enabled — the amount is taken from the payout parameter. A different parameter name is set through the API with the payout_param field; see Admin API: offers.
• The offer has a payout greater than zero — the offer payout is recorded, and the value from the postback is not used. For the lead and rejected statuses, 0 is recorded. A postback without status counts as a lead, and 0 is recorded for it too. The payout is recorded in the offer currency; the currency parameter does not affect it.
• In other cases, and also when the click came without an offer, the amount is taken from the payout parameter.

The amount is converted to USD at the rate for the date the postback was received. Rates are configured on the Settings → Currencies («Настройки → Валюты») tab; see Currencies and rates. If there is no rate for the payout currency or for the currency of the cost from cost, the tracker responds with code 422 and does not record the conversion.

An amount that could not be parsed, that is negative or that exceeds the limit is recorded as 0. The Logs → Postbacks («Логи → Postbacks») log gets the line “The payout in the postback was not recognized or is invalid — 0 recorded” («Выплата в postback не распознана или недопустима — записан 0»).

Transaction ID

The tracker uses txid to tell a repeated postback from a new conversion for the same click:

• Same txid, same status and same payout — the repeat is skipped, no duplicate is created.
• Same txid, same status, a different payout in the postback — the conversion payout is corrected.
• Same txid, new status — the conversion is updated.
• After sale, a lead or hold arrives with the same txid — the postback is skipped, and the sale stays.
• txid is not passed — the click keeps one conversion with the latest status and amount, and the event goes to the recipients every time. The exception is a lead or hold after a sale that was also received without txid: such a postback is skipped, and the sale stays.

The tracker treats an unreplaced macro like {txid}, ${txid}, [txid], %txid%, #txid# or <txid> as an empty value. If the click already has a conversion recorded under such a value, postbacks with it keep updating that conversion. This does not apply to a value like {txid}: it is always treated as empty. The detailed rules are on the Transaction ID, duplicates and conversion corrections page.

Source secret

If the source has a secret, the tracker accepts a postback only with the correct secret parameter. The secret is set on the traffic source, not on the network: the tracker checks the secret of the source the click came from. A click without a source does not require a secret. The owner and the admin can set a secret.

1. In the Sources («Источники») section, choose a source.
2. Enter a value in the Postback/lead secret («Секрет постбэка/лида») field.
3. Click Save («Сохранить»).
4. Add the &secret=value parameter to the postback address in the affiliate network. The Settings → Postback wizard adds it by itself; add it manually to the address from the Networks section.

A saved secret is shown in the field as ***. To change the secret, enter a new value and save. An empty field and *** keep the previous secret. To remove the secret, click Delete («Удалить») next to the field, then Save.

Tracker responses

Errors come as JSON with the code and message fields; the table gives the message value. The maintenance response comes as plain text. On 429 and 503 responses, the network should retry the request later.

A click reaches the statistics with a short delay, so the tracker looks for it for about 1.5 seconds before responding with 404.

Receiving postbacks does not depend on the license: with an expired license, conversions keep being recorded. What happens to outgoing events is described on the License expiry: what is closed and what keeps working page.

Testing

To test, send a postback manually. The Logs («Логи») section is available to the owner and the admin. An example address, where SUBID is the ID of a test click:

https://track.example.com/api/v1/postback?subid=SUBID&status=lead&payout=1&txid=test-1

If the click's source has a secret, add &secret=value to the address.

1. Follow the campaign link.
2. In Logs → Clicks and leads («Логи → Клики и лиды»), copy the value from the Subid column for your click. Search is described on the Click and lead search page.
3. Open the postback address with this subid in your browser.
4. Make sure the tracker responded ok.
5. In Logs → Postbacks, enter the subid in the search field. When the click is found, the log has a “Processing subid …” line with the campaign ID and status. A secret rejection, a click that was not found and a duplicate are also written to this log.
6. In the campaign, click Statistics («Статистика»).
7. Find the conversion on the Conversion log («Лог конверсий») tab; see Campaign conversion log.

If the conversion did not appear, open the Postback not arriving: what to check page.