Welcome to our support center

Developers

Creating 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 createContract API can be used to create new subscription templates. Once a new template is created, the returned contract_id can be passed to the subscription gateway for people to subscribe. (eg. https://subscription.cybercompay.com/?contractswipe_id=xxxx)

Please note that you cannot use this API to create active subscriptions directly. Users must subscribe to a subscription template by visiting the subscriptions gateway, loaded by a contract_id.

Parameters

The createContract 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)
  • ct_frequency - The JSON frequency data - See below for how to format this (Compulsory)
  • ct_total_amount - The recurring amount in New Zealand Dollars (Compulsory)
  • ct_initial_amount - The initial setup amount in New Zealand Dollars - this can be set to 0 if not required (Compulsory)
  • ct_tnc - The terms and conditions of the subscription (Compulsory)
  • ct_name - Subscription name (Compulsory)
  • ct_description - Subscription description (Optional)
  • ct_total_amount_aud - The total amount in AUD (Optional)
  • ct_total_amount_cad - The total amount in CAD (Optional)
  • ct_total_amount_cny - The total amount in CNY (Optional)
  • ct_total_amount_eur - The total amount in EUR (Optional)
  • ct_total_amount_gbp - The total amount in GBP (Optional)
  • ct_total_amount_hkd - The total amount in HKD (Optional)
  • ct_total_amount_jpy - The total amount in JPY (Optional)
  • ct_total_amount_sgd - The total amount in SGD (Optional)
  • ct_total_amount_zar - The total amount in ZAR (Optional)
  • ct_total_amount_krw - The total amount in ZAR (Optional)
  • ct_total_amount_usd - The total amount in USD (Optional)
  • ct_initial_amount_aud - The initial amount in AUD (Optional)
  • ct_initial_amount_cad - The initial amount in CAD (Optional)
  • ct_initial_amount_cny - The initial amount in CNY (Optional)
  • ct_initial_amount_eur - The initial amount in EUR (Optional)
  • ct_initial_amount_gbp - The initial amount in GBP (Optional)
  • ct_initial_amount_hkd - The initial amount in HKD (Optional)
  • ct_initial_amount_jpy - The initial amount in JPY (Optional)
  • ct_initial_amount_sgd - The initial amount in SGD (Optional)
  • ct_initial_amount_zar - The initial amount in ZAR (Optional)
  • ct_initial_amount_krw - The initial amount in KRW (Optional)
  • ct_initial_amount_usd - The initial amount in USD (Optional)
  • ct_duration - The JSON duration data. Leave empty if subscription is on-going.
    See below for how to
    format this. (Optional)

Please note, the 'ct_frequency' and 'ct_duration' fields have to be formatted correctly in order for the system to function properly. For on-going subscriptions, leave the 'ct_duration' field empty. Both fields need to in JSON format, structured as below.
Setting up 'ct_frequency'

The field uses the following format:

{"period":" - recurring period - ","number":"- charge number -","start_on":"","end_on":""}

The 'period' parameter is the period to take the payment over:

  • daily - Charge daily
  • weekly - Charge weekly
  • monthly - Charge monthly
  • yearly - Charge yearly

The 'number' parameter is how often to charge over that period. This is between 1 and 30 only. The 'start_on' and 'end_on' parameters should always be an empty string.

So to set up a recurring payment that charges a subscriber every 2 days, 'ct_frequency' should be:

{"period":"daily","number":"2","start_on":"","end_on":""}

For another example, charging a subscriber every month, 'ct_frequency' should be:

{"period":"monthly","number":"1","start_on":"","end_on":""}

Or every three months:

{"period":"monthly","number":"3","start_on":"","end_on":""}

Setting up 'ct_duration'

Leave this field empty if you want your subscription to be on-going. The field uses the following format:

{"period":" - duration period - ","number":" - duration number - "}

The 'period' parameter is the duration the subscription lasts over:

  • day - A day
  • week - A week
  • month - A month
  • year - A year

The 'number' parameter is the number of the period to continue for. This is between 1 and 30 only.

So to set up a recurring payment that lasts 1 week, 'ct_duration' should be:

{"period":"week","number":"1"}

For another example, a subscription thats lasts 6 months would be:

{"period":"month","number":"6"}

Please note that the active subscription billing date, end date and start date get calculated from the day of signup.


Example Request

Example createContract API call:

https://api.cybercompay.com/createContract.php?apikey=b17eeb6c4ed18b11c7adc8b8777e5563&merchant_id=123E59569B8A78&ct_frequency={"period"%3A"weekly"%2C"number"%3A"1"%2C"start_on"%3A""%2C"end_on"%3Anull}&ct_total_amount=20.00&ct_initial_amount=0&ct_tnc=There+are+no+terms+and+conditions&ct_name=Somename


Responses

If the API call was successful, it will return a response in JSON format. This response includes the contract_id from the CyberCom Pay system.

For information on the API response format and possible response codes, please see API Response Format

{"response_code":200,"message":"OK","data":{"contract_id":"2891685B52BB0"}}


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',
    'ct_frequency' => '{"period"%3A"weekly"%2C"number"%3A"1"%2C"start_on"%3A""%2C"end_on"%3Anull}',
    'ct_total_amount' => '20.00',
    'ct_initial_amount' => '0',
    'ct_tnc' => 'There are no terms and conditions',
    'ct_name' => 'Somename'
);



//Make the request to the server
$result = post_to_url("https://merchant.cybercompay.com/examples/createContract.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));