Call&Pay API V3.0

Introduction

Call&Pay is an online payment system which provides an ability for your website to become online shop.

You can start selling any kind of goods by offering your visitors ability to pay online by means of their standard phones – no credit card, no bank transfer, no registration is needed. Call&Pay uses different premium rate numbers allowing your customers to instantly pay for your products in multiple countries.

Call&Pay allows simple integration for any kind of website by including simple HTML/Javascript snippet which opens payment popup window. A visitor is asked to call a number specified in the popup. The system announces a code, which the visitor types into the popup window and clicks OK button. This is all that is needed for a payment to be done. The customer's website is informed about payment details and can proceed with purchase steps needed to deliver particular good to the customer (download, shipping, etc.).

Definitions

ExpressionDescription
Customer Party that buys services, products or content (merchant)
Buyer Party that buys services, products or content
Payment Gateway Provider Provider of website for payment over the IVR payment system Call&Pay
customer.web.site in examples below, URL of customer's website
Transaction ID Transaction ID displayed to the buyer; to be used in contacts with support
Reference ID ID that is used in forming URL’s to the Call&Pay server
Service Kind Kind of service (online payment, ON/OFF by phone, credit tanking)
Announced code Code announced to the buyer by Call&Pay service during the phone call
CAPTCHA code Code consisting of randomly selected group of letters and numbers which are displayed as a distorted image.

Premium rate number types

Call&Pay uses various premium rate numbers in order to bill your customer for a product you sell. Still, there are different kinds of these numbers:

  • drop charge ≫ independent of a call duration, the call will be billed at fixed rate
  • per minute ≫ the call will be billed based on a call duration

Based on the price for the processing order, Call&Pay automatically chooses the best number to be used.

Service types

The following section describes the three types of service (in following text «service kinds») currently available with Call&Pay:

  1. Pay per call
  2. ON/OFF by phone call (referenced in rest of this document as on/off service)
  3. Credit tanking (referenced in rest of the text as credit service)

Pay per call

This section describes the pay per call process.

Goal

This service may be used for customers who want to sell online any kind of products, services or e.g. downloadable content, such as video clips, audio files, etc. Customer's website provides the purchase price for the product and the Call&Pay service selects automatically a drop charge or a per minute based phone number that a buyer has to call in order to pay for the product.

Process Flow

  1. The buyer selects a product to buy online and clicks to checkout.
    1. The customer's website opens the popup window using the provided javascript function
    2. Payment form is generated and returned by Call&Pay
  2. The popup displays a country selection and a phone number to call
  3. The buyer makes a phone call to the Call&Pay phone system
  4. The Call&Pay announces a code
  5. The buyer enters the code in the popup, along with a CAPTCHA code.
    1. Call&Pay validates the code and CAPTCHA.
      1. In the case of per minute (payment calculated on call duration basis) phone number, the popup window displays a progress bar and asks the buyer not to hang up the call before price total is reached; when call time is up the success landing page is displayed.
      2. Payment transaction is completed in the Call&Pay.
  6. If the code is valid, success landing page is displayed and the buyer is prompted to click OK.
  7. The buyer clicks OK in the success landing page.
    1. The command is sent to the Call&Pay
    2. The Call&Pay closes the popup and redirects the buyer to the customer's website landing page where sold good or content is available.
    3. The customer's website on the redirected page verifies provided redirection parameters with Call&Pay
    4. The Call&Pay provides verification results
  8. If the request is verified the website allows the buyer access to the sold goods.

call and pay diagram


call and pay sequence

Integration steps

IMPORTANT! It's highly necessary to validate POST parameters with Call&Pay. Note that a post request to your page can be forged by malicious parties. By validating the request with Call&Pay you can discard these calls. Also, check provided parameters with the one you expect. For example, somebody malicious could send valid data, but not related to your sale, so you need to check and compare parameters like total_price, cust_id, insert_dt, custom_value, etc. Also, you should save each payment transaction parameters (ex. in database) so you can afterwards check if provided int_id already exists in your database and decline duplicate request.

  1. Download integration package.
  2. copy xs_receiver.html file from the package to your website (ex. your website's root folder)
  3. In the web page which should have BUY link include javascript:
    <script type="text/javascript" src="https://callandpay.ch/action/v3/callandpay.js"></script>
    in the html section
  4. Paste and edit javascript section for a buy button (for actual parameters like cust_id and api_key contact call&pay), example:
    
    <a href="#" onclick="callAndPay.payment(
        {   'cust_id'       : '1111',
            'price'         : 'ch:1000:chf;de:1000:eur;at:1000:EUR',
            'content_link'  : 'http://customer.web.site/v3/content/index.php',
            'custom_value'  : '1234',
            'website'       : 'http://customer.web.site',
            'api_key'       : '111111111111111111111111111',
            'service_class' : 'test',
            'success_email' : 'info@customer.web.site',
            'support_email' : 'suppport@customer.web.site',
            'language'      : 'de',
            'logo_url'      : 'http://customer.web.site/logo.jpg',
            'logo_text'     : 'Demo Shop',
            'xs_url'        : 'http://customer.web.site/xs_receiver.html'
        },500,100);"><strong>Buy now (10 CHF)!</strong></a>
                                
  5. Generate a download page which can be developed in any of web programming languages like php, asp, asp.net (vb.net or c#), perl, python, etc. Basically, Call&Pay redirects the buyer to this page and provides parameters via POST: transaction id, paid amount, etc. The first thing you have to do on this page is to validate posted parameters with Call&Pay service by sending exactly the same parameters you received and check if Call&Pay replies with VERIFIED. This step is crucial. Then it's up to you what should be done next: send confirmation email, allow download, send thank you, etc.

Here is sample php script for the confirmation:

/**
 * The purpose of this script is to accept notifications from Call&Pay, verify them and if Verified to proceeed with checkout (provide paied content to a buyer)
 */

// read the post from Call&Pay system and prepare request for verifications
$req = '';
foreach ($_POST as $key => $value) {
    $value = urlencode(stripslashes($value));
    if($req != ''){
        $req.= '&';
    }
    $req .= "$key=$value";
}

// post back to Call&Pay system to validate
$header .= "POST /action/v3/check HTTP/1.0\r\n";
$header .= "HOST: callandpay.ch\r\n";
$header .= "Content-Type: application/x-www-form-urlencoded\r\n";
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n";
$fp = fsockopen ('ssl://callandpay.ch', 443, $errno, $errstr, 30);

if (!$fp) {
// HTTP ERROR - read $errstr and $errno
}
else {
    fputs ($fp, $header . $req);
    while (!feof($fp)) {
        $res = fgets ($fp, 1024);
        if (strcmp ($res, "VERIFIED") == 0) {
            //IMPORTANT: first check that cust_id, custom_value, website, payment_amount/payment_currency are correct!!!
            //if((double)$_POST['total_price'] == 10 && $_POST['currency'] == 'CHF')

            //TODO IMPLEMENT YOUR BUSINESS LOGIC HERE!
            //process $_POST['custom_value'],$_POST['pub_id'],$_POST['int_id'],$_POST['customer_id'],$_POST['total_price'],$_POST['currency']
            echo "<h1>Request is successfully verified</h1>";
            echo '<p>Sent parameters:</p>';
            echo '<pre>';
            print_r($_POST);
            echo '</pre>';
        }
        else if (strcmp ($res, "INVALID") == 0) {
            // log for manual investigation
        }
    }
    fclose ($fp)
                    

Technical Details

Javascript checkout function parameters

params javascript hash array (described in the next table)
left left coordinate of the popup window to be displayed
top top coordinate of the popup window to be displayed
cust_id customer ID
price product price for all the countries, example: ch:1000:chf;de:1000:eur;at:1000:eur Value is integer value it's actual value multiplied by 100. Example: 10.5 euros should be provided as 1050
content_link link for downloading product after successful payment
custom_value custom value passed back to content_link (optional)
website website (optional)
api_key API key
service_class One of: test, normal or adult
success_email mail address where to send report about successful payment (optional)
support_email mail address where to send support requests (optional)
language language (optional, default: 'de')
logo_url URL where to find logo (optional) Parameters: Logo size: 165x78 pixel // Supported formats: jpg, gif, png
logo_text text below logo (optional) Parameters: max. Text lines: 5 // max. letters per line: 15
Note: specify text line breaks with html tag
xs_url URL to xs_receiver.html file on your server

Services classes

  • test This service class should be used while implementing Call&Pay services. Call&Pay will always show Swiss fixnet number instead of a VAS number. These calls are visible in statistics with price 0 and kickback 0 when used as drop charge numbers or with connection price 0.2 and kickback 0 when used as per minute numbers, as well for onoff and credit services. This allows you to test the service implementation without having high testing costs.
  • normal This should be used in production, for normal services.
  • adult This should be used in production, for erotic services.

POST parameters provided by Call and Pay

As described, when the buyer makes a purchase, the Call&Pay makes a HTTP POST request to your content page (url is provided by you in initial javascript checkout call). This is the place where you need to implement business logics: first to validate this request with the Call&Pay (to find out if it's from the Call&Pay at all), and if verified, to compare provided values with the values you expect for the total price paid, currency, custom value, etc. Please take a look at example script provided in the package for more details. Here's a list of POST parameters provided by Call&Pay on your content page:

cust_id customer ID
total_price total price paid
country ISO 2 country code
currency currency code
content_link content link you provided
custom_value custom value you provided
website website
service_class service class
pub_id public transaction id - given to the buyer as well
int_id internal transaction id
insert_dt date/time of transaction creation