Introduction

Welcome to the official documentation of Affbay Postbacks API.

Postback a sales transaction notification from payment processors to the merchant's affiliate system site. More specifically, it is a web service written for an affiliate sales tracking software system for a third-party merchant system to send (via GET or POST) the data to.

The term "Postback" is used here to describe what the payment processor does with the transaction receipt, which is to "Post Back" to the merchant's affiliate program, notifying it of a successful transaction, so that it can then credit affiliates with their earnings.

Affbay, as every respected affiliate network, offers a full postback implementation web service.

How Postbacks Are Handled?

First, you need to create your own infrastructure that will handle postback requests sent by Affbay. You can use any tool available or prepare your own scripted application. You will need three endpoints:

  1. Sales
  2. Holds
  3. Rejections

NOTE: Please be aware postbacks are optional and you do not need to provide them. Also, you can provide just postbacks for one or two endpoints, but you need to be aware that this is in your interest and responsibility to receive the whole spectrum of postbacks in order to track leads your campaigns are generating. Alternatively, you can use built-in system provided by Affbay.

You are allowed to use custom variables and structure of your URLs, as per Postback URL Structure section of this document, within the restrictions defined in Reserved variables section of this document.

Postback URLs may also transfer Google Tracking ID, Facebook Pixel ID or any tags. You set them directly under Offers > Product Campaign.

Once you have your postback URLs, populate fields (you can find them under Offers > Product Campaign) and save your campaign. From now on any lead update will result in a payload being sent on a proper endpoint (according to lead update type). You will need to collect them, as how described in this and previous section of this document.

Reserved Variables

As every affiliate network, Affbay reserves its right to reserve and restrict usage of some variables. Those variables are used to enhance its tracking capabilities in order to provide a better service and by that – be honest and true with their customers all over the world.

When using Affbay to generate your campaign links, we “attach” certain variables once the link is being opened. Please be aware that in order for the whole system to work properly, you are not able nor allowed to re-use those variables, as this will cause conflicts and may result in leads not being tracked properly.

The variables currently restricted on Affbay are as follows:

Variable Usage Restricted
click_id Tracking clicks across the campaign. Yes
comment Collects Call Center comment on lead Yes
contact_id Internal contact ID Yes
pub_id Contact public ID Yes
aff_id Affiliate ID Yes
campaign_id Affbay campaign ID Yes
scheme User's payout scheme (CPA/CPL) Yes
payout User's actual payout in USD Yes

NOTE: Please be aware that it is in your interest to avoid overwriting restricted variables in your postback handles as it may cause in mislead results and discrepancies between our records.

Please remember not to use restricted variables in any postback URL!

Custom Variables

ONLY S2S AFFILIATES

You are allowed to use up to seven custom variables. You can set them globally under Settings > Custom variables . You can use those variables to generate your campaign links (you need to replace them with your values that will be kept during the whole route of a lead) and you can also collect them from postback payload.

What is important is not to override reserved variables (as per section above) by your custom variables, as this may result in system malfunction and discrepancies or invalid postback payload.

Please have a look at our FAQ section

How does variables work?

We have noticed a lot of confusion on how does post back variables (both custom and system) actually work.

First of all, as per Custom Variables section, you can set your own variables and then use them for product-specific or global post back URLs, as long as you follow the structure guidelines.

So, how variables actually works? Let's have, for example, click_id system variable. For the use in an URL, you need to wrap variable name with single curly brackets , so a URL-ready variable looks like {click_id}.
Now you can insert it anywhere within the URL (remember: structure guidelines!) and save it.

Once a postback is being sent, Affbay will replace {click_id} with a value of parameter "click_id" you've provided along with the contact data. What particular variable will return once replaced will be explained below.

What values variables are passing through?

This depends on type of variables. For system variables:

Variable Value Example
click_id A value of the 'click_id' parameter sent along lead contact information 12345
comment A free-text comment by Call Center agent often explaining current status in a more specific way Call back tomorrow
contact_id Affbay's internal identifier of the particular lead (contact) 54534444
pub_id External (received from the call center) identifier of the particular lead (contact) 6457564564556
aff_id Affbay's internal identifier of the affiliate (you) 7454
campaign_id Affbay's internal identifier of product campaign fb7fcf80-5377-11e8-aa04-c39afd27e476
scheme User's payout scheme cpa
payout User's actual payout in USD 32.99

ONLY S2S AFFILIATES

For custom variables those values are gathered directly from campaign URL generated for your Affbay campaign. For example, le'ts say you've created a new campaign for one of our products and beforehand you've set custom variables: cid, external_id and set_id. Affbay-generated campaign url will look like:

https://id.hottest-price/fb7fcf80-5377-11e8-aa04-c39afd27e476?cid={cid}&external_id={external_id}&set_id={set_id}

When you provide this URL to your system, it has to replace curly bracket values with your system-specific values so, for example, URL used by a visitor through your network will look like:

https://id.hottest-price/fb7fcf80-5377-11e8-aa04-c39afd27e476?cid=1234567890&external_id=9999999&set_id=affbay

As you can see, your system has replaced {cid} with 1234567890, {external_id} with 9999999 and {set_id} with affbay. Those values will then be attached lead's data and saved along.

You will be able to receive those custom variables's data in post backs just as you'd with system variables.

You can provide postback URL containing all your custom variables as well as default system variables, so for example:

https://tracker.example/postback?cid={cid}&contact_id={external_id}&set_id={set_id}&external_id={contact_id}

In this example you're returning external_id as your native contact ID while returning Affbay's contact_id as external contact ID.

Remember - Affbay's post back configuration is flexible and covering all cases in this documentation is simply impossible. Please be aware that due to the number of combinations of settings while setting up postback URLs with variables we are responsible just to successfully attempt to deliver a post pack to a provided URL, just as Internet providors are only responsible for the infrastructure to the router. We do not hold any responsibility for any mistakes or misused variables within any post back URL.

Structure

We do not enforce any postback URL structure, as the system is able to pick up anything you provide. Moreover, it is in your responsibility to provide a valid URL and to properly receive the payload we send. The simplest way to do this is to use query string variables. This looks like this:

https://domain.com/?variable1=value1&variable2&value2

In order to recover the payload you simply need to receive the GET query string using your chosen programming language.

Please be aware, again, that it’s your responsibility from the moment we send a payload to your postback URL (which you also have to provide valid) until the data has been received and processed.
You will need to properly recover data from any postback URL structure and process it using your own capability.

We do not have access and any influence on how this is handled the moment we send you a postback request.

Types

Affbay currently serves three publicly available events, offering post back functionality for each of them:

Event Usage
HOLD A lead has been created; Lead has been called/contact has been established and product was sold and now waiting for the payment;
SOLD Lead has converted; Payment received;
REJECTED Lead has declined offer; Lead overdue; Any other reason (invalid data etc);

We make two attempts delivering a post back: one via GET and, if this one failed, via POST request.

We do not support authentication on any post back URL and any request type.

Product-specific post backs

ONLY S2S AFFILIATES

If, for any reason, you need to setup product-specific post backs you can do it directly on product details page under campaign details.

Contact & support

We try to make this documentation as simple and accessible as possible. However, we do understand that technical terms and aspects can be difficult and may often lead to misstatements or not provide all information needed. Therefore, when you should have any further questions or need an explaination of anything mentioned in this document, please do not hesitate to give us a shout, as we encourage all our partners to do so, in order to prevent service disruptions and errors on either side.

The best way to contact us is to drop us an email at support@affbay.asia or using our contact form.

We target to give you a first-off reply within 24 bussiness hours.