Developers

Fetching Contracts

Prerequistes

This section expects prior knowledge and understanding from the sections indicated below. Please note that these areas are essential to obtaining a successful response and notifying your server upon completion.

• API Overview
• API Key and Merchant ID
• Subscription & Contract APIs

Overview

The fetchContract API allows the server to get all contracts that meet a specified criteria. This call is capable of searching for both subscriptions and the templates in which created them.

Please note that the search_by and keyword parameters may be passed multiples times, however the server expects to have square brackets after the parameters to symbolise an array.

Parameters

If you omit the 'search_by' and 'keyword' parameters, the API will return every subscription in your account, both templates and active types. In order to filter these results, you can pass the API the filtering parameters with corresponding values.

The fetchContract API takes the following parameters:

• merchant_id - The merchant ID that can be found within the merchant console. (Compulsory)
• apikey - The API Key associated with the merchant ID.
  This is used to authorise and identify the caller of the request. (Compulsory)
• search_by - The field you want to search by
• keyword - The keyword to search by

Pass into 'search_by' parameter:

• contract_id - The id of the contract you want to fetch
• contact_id - The id of the person (contact) you want to search for
• status - The status of the contract you want to search for (active, inactive, suspended)
• start - The start date of the contract you want to search for (in Y-m-d format)
• end - The end date of the contract you want to search for (in Y-m-d format)
• currency - The currency of the subscription you want to search for (To view supported currencies click here)
• type - The type of contract you want to search for (template or subscription)

Example Request

The following API call shows how all templates and active subscriptions may be retrieved:

By passing the search and keyword parameters we can limit the records returned. An example can be seen below, where the type = 'subscription' and the status = 'active':

Responses

If the API call was successful, it will return the subscription data in JSON format.

{  
   "response_code":200,
   "message":"OK",
   "data":{  
      "0":{  
         "ct_auto_renew":"yes",
         "ct_button_id":"2",
         "ct_chid":"B24E26261C19A",
         "ct_contid":"B24E26261B437",
         "ct_currency":"NZD",
         "ct_date":"1367898502",
         "ct_description":"Includes monthly subscription of the 52 page magazine for 12 months.",
         "ct_duration":"\"period\":\"day\",\"number\":\"4\"",
         "ct_end":"1368100800",
         "ct_frequency":"{\"period\":\"daily\",\"number\":\"1\",\"start_on\":1367794756,
		\"end_on\":1368100800}",
         "ct_initial_amount":"2",
         "ct_last_charge_date":"1367928000",
         "ct_last_successful_payment_date":"1367755200",
         "ct_mcid":"afc9b037-8074-452a-b1e2-ce181e93fbce",
         "ct_name":"Magazine Subscription",
         "ct_next_charge_date":"0",
         "ct_nzd_amount":"2",
         "ct_nzd_initial_amount":"2",
         "ct_payment_status":"complete",
         "ct_primary_txid":"EB26107284524",
         "ct_start":"1367794756",
         "ct_status":"active",
         "ct_suspended_merchant":"yes",
         "ct_templateid":"B249FD2EA2F18",
         "ct_tnc":"sample conditions",
         "ct_token":"EB2630D8AF573",
         "ct_total_amount":"2",
         "ct_type":"subscription",
         "contract_id":"2075DA3F0A0248"
      }
   }
}

A active subscription contract will have the following parameters:

• ct_contid - The contact_id of the subscriber
• ct_currency - The currency the subscription is in
• ct_date - The date the subscription was created
• ct_description - Description of the subscription
• ct_duration - How long the subscription lasts (in JSON format)
• ct_frequency - How often the recurring payment is made (in JSON format)
• ct_start - The start date of the subscription (timestamp)
• ct_end - The end date of the subscription (timestamp)
• ct_status - The status of the contract (active, inactive, suspended)
• ct_total_amount - The the recurring amount being charged
• ct_type - The type of contract (template or subscription)
• ct_last_charge_date - The date the subscriber was last charged (timestamp)
• ct_last_successful_payment_date - The date the subscriber was last sucessfully charged (timestamp)
• ct_next_charge_date - The next charge date (timestamp)

Test Code

Below is an example code that will work against a test section of the server. Although this is intended to simulate server behaviour, characteristics and responses are not always the same.

Please note that no transactions will be sent online and the server will not store any information from these requests. For more information on this, please see Testing Without An Account

<?php
/**
 * Function used to make POST requests to the server using SSL.
 * 
 * @param type $url The API URL that we want to send the request to.
 * @param type $data POST data that will be sent to the server.
 * @return false Returns the HTML response as a String. If an error has occured null will be returned. 
 */
function post_to_url($url, $data) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
    $html = curl_exec($ch);
    if (curl_errno($ch) !== 0) {
        curl_close($ch);
        return false;
    }
    curl_close($ch);
    return $html;
}

//The POST data that will be sent to the server.
$postData = array(
    'apikey' => 'ida8463534kawhdi347d39h078dt3383',
    'merchant_id' => '123E59334B8338',
    'search_by[]' => 'type',
    'search_by[]' => 'status',
    'keyword[]' => 'subscription',
    'keyword[]' => 'active'
);

//Make the request to the server
$result = post_to_url("https://merchant.cybercompay.com/examples/fetchContracts.php", $postData);

//If we have encountered an error display something back to the customer.
if ($result === false) {
    echo 'We have encountered an error!';
    exit;
}

//Print the results.
print_r(json_decode($result));