API - Referrals

Send referral data to your Maian Affiliate system. Please read carefully.

When you place the code on your product sites, a cookie (please take a moment to read the G.D.P.R note on the main API page) is set when the affiliate code is present via the GET parameter. An example would be:

https://www.example.com/?maff=abc123

Once set, the cookie contains the affiliate code and is present on the visitors computer each time they access a page or complete a sale.

The affiliate GET parameter can be changed in the 'control/options.php' file via the 'AFF_GET_PARAM' option.

Referrals use the HTTP_REFERER value. If this isn't available, the cookie is still set, but the affiliate referral url is not logged. You can activate it at the server level (via PHP.ini), but the value is sent by the browsers user agent. Some browsers suppress this value. If you have problems with this, you should set the url value in the API some other way. For example, you could get the affiliate to include their url in a GET parameter and use this value as the referrer.

The following data should be transmitted with your referral calls (shown as standard JSON array):

---

{
  "apikey": "YOUR API KEY",
  "affiliate": "AFFILIATE CODE",
  "referrer": {
    "url": "REFERRAL URL",
    "ip": "REFERRAL IP ADDRESS",
    "product": "PRODUCT ID"
  }
}

---

apikey = Your api key as set in the settings. This must be included with all calls.
affiliate = Affiliate code, this would come from the cookie that is set (see below).
referrer = Referral array containing the referral url, ip address and product ID. Product ID must match the product ID in your Maian Affiliate setup. Url and ip address can be set programmatically, see example below.

You should handle the responses accordingly if required.

An error response will be as follows:

---

{
  "status": "error",
  "message": "ERROR MESSAGE"
}

If successful the API sends back additional data if you need to do further processing. A successful response will be as follows:

---

{
  "status": "ok",
  "data": {
    "referralID": "44",
    "affiliateID": "2",
    "productID": "2",
    "referralUrl": "https://www.example.com",
    "affiliateName": "John Harris",
    "affiliateEmail": "example@gmail.com"
  }
}

The data array is only sent back on a successful response. The ID numbers correspond to the ID numbers in your Maian Affiliate system.

The following is a full code example. Change values accordingly for your own setup. You should change the GET variable if you have renamed it and you should make the cookie name more obscure for security. Remember to use the same cookie var in the commission calls. It is also a good idea to sanitize the affiliate code, for example, if your affiliate codes are alphanumeric, check the value is alphanumeric.

If you get the code directly from the product page in your Maian Affiliate admin area, the key, product ID and a more obscure cookie key are completed for you.

---

<?php
// Check for affiliate code
if (isset($_GET['maff'])) {
  // Set cookie if not already set
  if (!isset($_COOKIE['msw_aff_2018151810_code'])) {
    setcookie('msw_aff_2018151810_code', $_GET['maff'], time() + 60 * 60 * 24 * 180);
  }
  // Prepare array..
  $data = array(
    'apikey' => 'YOUR API KEY HERE..',
    'affiliate' => $_GET['maff'],
    'referrer' => array(
      'url' => (isset($_SERVER['HTTP_REFERER']) ? $_SERVER['HTTP_REFERER'] : ''),
      'ip' => (isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : ''),
      'product' => 'PRODUCT ID HERE..'
    )
  );
  // Send to API..
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://www.path-to-your-maian-affiliate-setup.com/index.php');
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json'
  ));
  curl_setopt($ch, CURLOPT_TIMEOUT, 120);
  $r = json_decode(curl_exec($ch), true);
  curl_close($ch);
  // Do something with response..
  if (isset($r['status'])) {
    switch($r['status']) {
      case 'error':
        // Handle error message..
        break;
      case 'ok':
        // Reload page
        $url = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off' ? 'https' : 'http') . '://' . $_SERVER['HTTP_HOST'] . substr($_SERVER['REQUEST_URI'], 0, strpos($_SERVER['REQUEST_URI'], '?'));
        header("Location: " . $url);
        exit;
        break;
    }
  } else {
    // Check logs folder in Maian Affiliates, something went wrong
  }
}
?>

You can copy and paste the above code if you need to. You should change the api key and product ID values and make sure the CURLOPT_URL path is correct. If the $url value isn't correct for the redirect, enter your page url manually. Example:

$url = 'https://www.example.com/site/';

Your API code for referrals should be on all pages and BEFORE any output is sent to the browser. If you see an error to say 'headers have already been sent' you need to move your code. So, ideally place your code after the opening <?php tag on your main page, before any other code has loaded.

You should also log the affiliate code against the sale so that if you use gateway callbacks you can check for the affiliate code and ping the data to the affiliate system. Storing the code will require you to change your product SQL structure. This is preferred if you don't want to use cookies.

If you enable the API log data will be logged in the "logs" folder each time there is a call from the API. Refer to this for help. You should disable the log when you are ready to go live. Note that general errors, referral errors and commissions errors are all logged separately.