Postback instruction for a CMS | Tapfiliate Help Center

Each request must have a header with the user's authentication key.

X-Api-Key: #Your key#

You can find and manage X-Api-Key in your account settings.

Your X-Api-Key - has to be saved in secure storage (e.g. database, environment variables).

Basic concepts

Postback API endpoints accept both GET and POST requests.

When creating a request with the GET method, you need to pass all the necessary parameters in the request URL:

curl -X GET -H 'X-Api-Key: YOUR API KEY HERE' https://api.tapfiliate.com/1.7/pb/con/c/?referral_code=nwjinmy&amount=100&external_id=ORD005

When creating a request with the POST method, you need to pass all the necessary parameters in the request body:

curl -X POST -H 'Content-Type: application/json' -H 'X-Api-Key: YOUR API KEY HERE' https://api.tapfiliate.com/1.7/pb/con/c/ -d '
   {
     "referral_code": "nwjinmy",
     "amount": "100",
     "external_id": "ORD005"
   }'

Required parameters:

1. external id A unique id for this conversion. It can be anything that is meaningful to you, like an order number, user id, email address etc. This id has to be unique for every conversion.

2. You have to also send one of the parameters:

• referral code An affiliate’s referral code. This corresponds to the value of ref= in their referral link

• coupon The affiliate’s coupon code.

• click id The click id. Used to add additional reporting information.

• asset id and source id A source id or an asset id.

If more than one of them is sent, then one will be used, according to priority (from highest to lowest): coupon, click_id, referral_code, asset_id and source_id.

If necessary, you can add additional parameters to the request:

• amount The conversion amount (number).

• currency The three letter ISO currency code.If not passed, the default program currency will be used.

• customer id The id for this customer in your system. The customer id should be unique for each customer. Depending on your program settings, this can be used for recurring / lifetime commissions. You can read more about this here.

• meta data Additional data for the conversion (object).

• user agent The client’s user agent string. Used for statistics and fraud detection.

• ip The client’s IP. Used for fraud detection.

Implementation for PHP

Implementation for WordPress and WooCommerce:

The following code has to be added to the functions.php file of the active theme.

<?php
define('TAP_COOKIE_DAYS', 90); // Number of days cookies are stored for
define('TAP_COOKIE_NAME', 'tap_data'); // Cookie name
define('TAP_CONVERSION_POSTBACK_URL', 'https://api.tapfiliate.com/1.7/pb/con/c/'); // Link to the endpoint for working with conversions
define('TAP_CUSTOMER_POSTBACK_URL', 'https://api.tapfiliate.com/1.7/pb/cus/c/'); // Link to the endpoint for working with customers

function setDataToCookie($data)
{
    setcookie(TAP_COOKIE_NAME, json_encode($data), time() + 60 * 60 * 24 * TAP_COOKIE_DAYS, '/');
}

function parseDataFromUrl()
{
    $resultArray = [];

    if ($assetData = $_GET['aid'] ?? $_GET['asset_id'] ?? $_GET['a'] ?? $_POST['aid'] ?? $_POST['asset_id'] ?? $_POST['a'] ?? null) {
        $resultArray['asset_id'] = $assetData;
    }

    if ($sourceData = $_GET['sid'] ?? $_GET['source_id'] ?? $_GET['s'] ?? $_POST['sid'] ?? $_POST['source_id'] ?? $_POST['s'] ?? null) {
        $resultArray['source_id'] = $sourceData;
    }

    if ($refData = $_GET['refc'] ?? $_GET['referral_code'] ?? $_GET['ref'] ?? $_POST['refc'] ?? $_POST['referral_code'] ?? $_POST['ref'] ?? null) {
        $resultArray['referral_code'] = $refData;
    }

    if (empty(array_filter($resultArray))) {
        return;
    }
    setDataToCookie($resultArray);
}

function sendRequestToPostbackApi($url, $data)
{
    return wp_remote_post($url, [
        'method' => 'POST',
        'timeout' => 45,
        'headers' => [
            'X-Api-Key' => getenv('TAPFILIATE_API_KEY'),
            'Content-type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'body' => json_encode($data),
    ])['body'];
}

function createConversionFromOrderId($orderId)
{
    $data = json_decode(stripslashes($_COOKIE['tap_data']), true);
    $order = wc_get_order($orderId);
    $customerData = array_merge($data, [
        'customer_id' => $order->get_billing_email() ?? $order->get_customer_id(),
        'referral_code' => $data['referral_code'],
        'coupon' => $data['coupon'],
        'asset_id' => $data['asset_id'],
        'source_id' => $data['source_id'],
    ]);

    $customerResponse = json_decode(
        sendRequestToPostbackApi(TAP_CUSTOMER_POSTBACK_URL, array_filter($customerData), true),
        true
    );
    $customer = json_decode($customerResponse, true);
    $requestData = [
        'external_id' => (string) $orderId,
        'referral_code' => $data['referral_code'],
        'currency' => $order->get_currency(),
        'amount' => $order->get_total(),
        'ip' => $order->get_customer_ip_address(),
        'user_agent' => $order->get_customer_user_agent(),
        'customer_id' => $customer['id'],
    ];

    return sendRequestToPostbackApi(TAP_CONVERSION_POSTBACK_URL, $requestData);
}

add_action('parse_request', 'parseDataFromUrl');
add_action('woocommerce_new_order', 'createConversionFromOrderId', 10, 1);

Note: S2S/Postback tracking is an advanced feature. As such, set up of this feature falls outside the scope of our support. You may need a developer to assist in setting this up.