Developers

Create Subscription Identifier

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
• Live Payment Notification (LPN)

Overview

This API is used to create ad-hoc subscriptions, where you pass in the relevant subscription details generated on your system.

A subscription identifier is a temporary record held in the CyberCom Pay Checkout system that identifies subscriptions sent to the Subscriptions page for a particular item being subscribed too. Identifiers are setup for subscriptions using the createSubscriptionIdentifier API. You simply pass the item's details and the API will return the item's identifier. Then when a user clicks to subscribe, the corresponding identifier is sent to the Subscriptions page, where the items details (subscribers details, subscription price etc) are displayed.

Parameters

The API takes the following parameters as either GET or POST data:

• merchant_id - The merchant ID that can be found within the merchant console. (Compulsory)
• api_key - The API Key associated with the merchant ID. This is used to authorise and identify the caller of the request. (Compulsory)
• contract_id - The contract_id for the subscription plan to set up the identifier for (Compulsory)
• td_email - The subscriber's email address (Compulsory)
• td_first_name - The subscriber's first name (Compulsory)
• td_last_name - The subscriber's last name (Compulsory)
• td_address - The subscriber's address (Compulsory)
• td_city - The subscriber's city (Compulsory)
• td_country - The subscriber's country (Compulsory)
• td_company - The subscriber's company (Optional)
• td_suburb - The subscriber's suburb (Optional)
• td_phone - The subscriber's phone number (Optional)
• td_mobile - The subscriber's mobile number (Optional)

Example Request

Example createSubscriptionIdentifier API call:

Responses

If the API call was successful, it will return a response in JSON format.

API response example:

{"response_code":200,"message":"OK","data":{"identifier":"XXXX"}}

The 'identifier' is the ID of the subscription identifier now setup in the CyberCom Pay Checkout system. When this ID is passed to the Subscriptions page via the 'identifier_id' parameter, the subscription details will be displayed.

Example of Subscription URL with the identifier_id passed in:

The Subscription page will load the item by the identifier ID.

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(
    'api_key' => 'ida8463534kawhdi347d39h078dt3383',
    'merchant_id' => '123E59334B8338',
    'contract_id' => '123F8F0E11318B',
    'td_email' => 'example@optimizerhq.com',
    'td_first_name' => 'John',
    'td_last_name' => 'Doe',
    'td_address' => '16 Anzac',
    'td_city' => 'Auckland Central',
    'td_country' => 'New Zealand'
);

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