Developers

Create Transaction 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 transactions, where you pass in the relevant payment details generated on your system. Alternatively you can also use the CyberCom Pay Storefront system to store information about products and pricing within CyberCom Pay.

A transaction identifier is a temporary record held in the CyberCom Pay Checkout system that identifies transactions sent to the Payments page for a particular item being sold. Identifiers are setup for sale items using the createTransactionIdentifier API. You simply pass the item's details and the API will return the item's identifier. Then when a user clicks to buy an item, the corresponding identifier is sent to the Payments page, where the items details (price etc) are displayed. The advantage of the using this API is that a identifier can be setup for any item on your website, even if it is unknown to CyberCom Pay Checkout.

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)
• td_item - Name of the particular item. This is used on the payments page and helps identify the purchasing item. (Compulsory)
• td_description - Description of item or items. This data is displayed under the price on the payments page when the parameter "checkout" is set to true. HTML tags can be passed with this parameter to format the displayed data. (Optional)
• td_amount - Item price (Compulsory)
• td_default_quantity - Quantity of items. This can be manually over-ridden by passing the 'item_quantity' parameter directly to the payments page. (Optional, default is 1)
• td_user_data - Any user data you would like to pass. (Optional)
• td_currency - The currency the transaction will be charged in. If the currency is not valid, this will default to NZD. For a full list of these, please see Available Currencies. (Optional, if not passed the system defaults to your default currency.)
• td_token- This is the token relating back to the customer's card data that is securely stored on our system. Passing this into the API will put the payment page into 'token' mode. This will fetch the users card data, so they don't have to enter it again. If the token passed is incorrect, the page will load as per usual. (Optional)
• td_callback_url- This field can be used to dynamically set your call back URL for individual transactions. This functionality replaces the deprecated 'setCallback' API (Optional)
• td_lpn_url- This field can be used to dynamically set your LPN URL for individual transactions. This functionality replaces the deprecated 'setLpn' API (Optional)
• td_email- The customer's email address. This will automatically set the 'email' field on the payment page. (Optional)
• td_reference- This field can be used to pass through a reference code for reconciliation purposes. The data can be viewed on the transaction details page. (Optional)

Example Request

Example createTransactionIdentifier 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 transaction identifier now setup in the CyberCom Pay Checkout system. When this ID is passed to the Payments page via the 'identifier_id' parameter, the item details will be displayed.

Example of Payments URL with the identifier_id passed in:

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

/**
 * 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',
    'td_item' => 'your_product',
    'td_amount' => '9.95'
);

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