General Technical Information on One-Time Payment

Summary
  1. Form for capturing access codes
  2. Form optional fields
    1. Four fields for collecting the data:
      1. data
      2. recall
      3. recall_ca
      4. nde
    2. Four fields for affiliation:
      1. ap_ca
      2. ap_ca_idc[n]
      3. ap_ca_mnt[n]
      4. ap_ca_map[n]
  3. Checking code validity
  1. Form for capturing access code

    The script contains:

    • A PNG image which source is hosted on our server and that displays the number to dial based on the pricepoint you selected.
    • A HTML form containing various fields.

    This HTML field must contains 3 fields:

    • The code[] field (of the TEXT type in the script) in which the web-user types his code . If several codes are required, there'll be fields code[0], code[1], etc...
    • The ids field containing the Allopass ID assigned to your site.
    • The idd field containing the Allopass ID assigned to your protected product (document).

    Form destination URL:

    When the form is submitted, this data is sent to the URL http://payment.allopass.com/acte/access.apu. The Allopass system then checks the code validity. If it's valid, immediate redirection to your product URL (return URL) occurs.

  2. Form optional fields

    You can add several optional fields to this form, which don't appear in the script provided by default:

    1. Four fields for collecting the data

      1. The data field:

        >This hidden field (thus of the HIDDEN type) can contain any value of your choice.
        When your customer is redirected to your site, in case of a valid code, your product URL (return URL) will be called with an additional parameter named DATAS containing what you put there in the form.

        For instance, if you set up the product URL (return URL) as: http://www.mysite.com/return.php
        the Allopass system will call this URL as follows: http://www.mysite.com/return.php?DATAS=xxxx
        with "xxxx" corresponding to what you put in the data field of the form.

      2. The recall field:

        This hidden field, if present in the form and with the value "1", will allow you to collect the code typed in by the customer, if valid. A parameter named RECALL will be sent via the return URL, containing the code(s) typed in.

        For example : http://www.mysite.com/return.php?RECALL=12345678
        In the case of a (example 3 codes) : http://www.mysite.com return.php?RECALL=12345678,78945612,45897845

      3. The recall_ca field:

        This hidden field, if present in the form and with the value "1", will allow you to collect the affiliate code used for this access. A parameter named RECALL_CA will be sent via the return URL containing the affiliate code. If no affiliate code was used, this parameter remains empty.

      4. The nde field:

        This hidden field, if present in the form and with the value "1", prevents the parameters DATAS and RECALL, RECALL_CA... from coming back to your script if the code typed in is erroneous (thus calling the error page script).

    2. Four fields for affiliation:

      1. The ap_ca field:

        This hidden field, if present, must contain an "affiliate code", which you can generate in the section "affiliate links". If this field is present in your form, then, whoever your visitor is, the sharing percentage you set when you created this affiliate code will be credited to your affiliate's account. This amount will be deducted from your own payout.

        This field is useful if you sell a content in partnership with another merchant, for instance. This merchant will receive a percentage of the generated revenue and will be able to request outpayment from Allopass, just like you.

      2. The ap_ca_idc[n] field (n ranging from 0 to 4) :

        This field contains the ID of an affiliate to whom you want to pay a percentage of your profits without having priorily created an affiliate link.

        Your affiliate will find his ID in the section "Personal details" of his Allopass account.

        If you use this field ap_ca_idc[n], you must also use either of the following fields. The fields below are used to define how much you allocate to your affiliate's account.

      3. The ap_ca_mnt[n] field (n ranging from 0 to 4) :

        It is the amount to be paid out (as a percentage) to your affiliate which you set up with the parameter ap_ca_idc. This value ranges from 0 to 100.

        Rather than stating the sharing percentage, you can also use an alias system.

        To find out more, Set Alias !

      4. The ap_ca_map[n] field (n ranging from 0 to 4):

        This field must contain the "Affiliation Payout Program" ID.

        For each subscription, an "Affiliation Program Payout" sets the fixed amount which will be reallocated to your affiliate (thus not a percentage).

        Important! You can't use the fields ap_ca_mnt[n] and ap_ca_map[n] together in the same access script!

        Furthermore, the use of "Affiliate payout program" is not compatible with affiliate links: when a web-user clicks one of your affiliate banners, the associated affiliate program is not taken into account if an ap_ca_map[n] field is embedded in your access script.

        Start your own "Affiliation Payout Program" !

      Using the fields ap_ca_idc[n] and ap_ca_mnt[n] (or ap_ca_map[n]), you can reallocate part of your profits to up to 5 different affiliates!

      Of course, the sum of all ap_ca_mnt[n] codes can't be superior to 100, and the affiliate payout sums as defined by the ap_ca_map[n] can't be superior to your total payout!

    Important! For Iframe format scripts, variables must be passed in GET in the URL containing the access code capturing script (right.php4). You'll also need to replace the symbol # of the alias by %23 or use the urlencode() PHP function.

  3. Checking code validity

    Your PHP or ASP scripts can ask the Allopass system to know the validity of a subscriber pass, which is returned to you with the form parameter RECALL.

    Once your return page has received this information, you dispose of 1 minute to check if this code was validated for a given product.

    Your script will send a HTTP request to our server containing as parameters both the code(s) you want to check and the ID of your protected product.

    Our server tells you whether if this or these code(s) is/are valid or not for this product.

    Implementation:

    • You first need to collect the ID of your protected product. This ID is to be found in the table "My Products List" in the column "#auth". It looks like "54/75/4567".
    • Then your product page must send a request to our server with a parameter named code containing the code to be checked and a parameter named auth containing your product ID (document).
    • Our server can answer:
      OK
      This code was accepted in the previous two minutes for access to this product.
      NOK
      This code is erroneous
      ERR
      The request was not understood (maybe an error affecting your product ID).

    For instance, if the pass is valid, you can place a cookie on your customer's system, as a proof of payment. You'll be able to automatically grant access to your other protected pages just by testing the presence of this cookie.
    If it's not present, you'll just have to redirect your customer to an error page.

    Here is an example (in PHP, see bottom page for PERL):

    The HTML code-capturing form is like::

      <form action ="http://payment.allopass.com/acte/access.apu" method="post">
        <input type="hidden" name="ids" value="99" />
        <input type="hidden" name="idd" value="74" />
        <input type="hidden" name="recall" value="1" />
        <input type="text" name="code[]" size="8" />
        <input type="submit" value=" Enter " />
    
      </form>
    

    Of course, the values of the parameters ids and idd must be those provided in the original script.

    If your product page is script named retour.php4, then this script will be called when a valid code is inserted.
    You'll find there the variable $RECALL containing the code typed in.

    You then check the Allopass platform. Here is the PHP example:

    <?php
      $RECALL = $_GET["RECALL"];
      if( trim($RECALL) == 
    
    "" )
      {
        // The RECALL variable is empty, the web-user is redirected
        // to an error page
        header( "Location: error.html" );
        exit(1);
      }
      // $RECALL contains the access code
    
      $RECALL = urlencode( $RECALL );
    
      // $AUTH must contain the ID of YOUR product
      $AUTH = urlencode( "54/75/456" );
    
    
      /**
       * sending of the request to the Allopass server
       * in the variable $r[0] will be found the server answer
       * in the variable $r[1] will be found the customer's country code
       * (FR,BE,UK,DE,CH,CA,LU,IT,ES,AT,...)
       * In case of a multicode, we'll also find $r[2],$r[3] etc...
       * each containing the result and the country code.
       */
      $r = @file( "http://payment.allopass.com/api/checkcode.apu?code=$RECALL&auth=$AUTH" );
    
      // checking of the server answer
    
      if( substr( $r[0],0,2 ) != "OK" ) 
      {
        // The server answered ERR or NOK : access is denied
    
        header( "Location: error.html" );
        exit(1);
      }
     
      /**
       * The pass is valid!
       * A cookie named CODE_OK is placed, with the value 1
       * This cookie remains valid until the web-user closes his browser
       * In the following pages, you'll just need to test this cookie
       * If it's present, the web-user is granted access,
       * sotherwise he'll be redirected to an error page
       */
      setCookie( "CODE_OK", "1", 
    
    0, "/", ".mydomain.com", false );
    
      /**
       * In the above line replace".mydomain.com" by the domain name
       * of your site!
       * For example, if your site is accessible at the address
       * http://perso.hoster.com/mypage
       * then you'll have to write ".hoster.com"
       * (mind to put "." before your domain name!!)
       */
    
    ?>
    

    In the following pages of your site's paid-access area, you'll be able to check the presence of the cookie as follows:

    <?php
      if( $HTTP_COOKIE_VARS['CODE_OK'] != '1')
      {
        header( "Location: error.html" );
        exit(1);
      }
    
    
    ?>
    

    However, optimal security will be reached by setting up a session system that associates a session to every visitor who used Allopass to access your site.

    PERL programmers will find here a module specifically designed for Allopass by one of our members (M. B. Nauwelaerts) whom we thank wholeheartedly : http://www.it-development.be/software/PERL/Business-PhoneBill-Allopass/