General Technical Information on Credit Card Payment

Sommaire A - Creating a button for access purchase
B - Creating a button for capturing the subscriber pass
C - Optional fields of the subscription form
D - Optional fields of the Subscriber pass capturing form
E - Checking the pass validity
F - Compatibility with "One-time" payment products
G - Acknowledgment URL

A - Creating a button for access purchase

The provided script contains:
  • An HTML form that contains various hidden fields.
  • An image which source is hosted on our server and prompting web-users to click it to subscribe. This image is the validation button of the form.

This HTML form must contain 3 fields at least:
  • The langfield which value may be "L_FR" (French) or "L_UK" (English).
  • The ids field that contains the Allopass ID of your site.
  • The idd field that contains the Allopass ID of your product (document).

When this form is submitted, all this data is sent to the subscription management interface.
When a purchase occurs, the subscriber pass is automatically linked to the Allopass ID's of your site and product.



B - Creating a button for capturing the subscriber pass

The provided script contains:
  • A PNG image which source is hosted on our server, and that gives end-users a few guidelines.
  • A HTML form that contains various fields.

This HTML form must contain 3 fields:
  • The code field (of the TEXT type in the script) where the web-user inserts his subscriber pass.
  • The ids field that contains the Allopass ID of your site.
    The idd field that contains the Allopass ID of your product (document).

When this form is submitted, all this data is sent to the URL http://payment.allopass.com/subscription/access.apu
Our system verifies if the pass is valid. If it's valid, immediate redirection to your return URL occcurs.



C - Optional fields of the subscription form

You can add several optional fields to this form, which are not present in the script provided by default:

a - 1 field for collecting information
  • 1 - The data field:
    This hidden field (of the HIDDEN type) may contain any value of your choice.
    If such a field exists and if you set up an "Acknowledgment URL" for your "Credit Card" product, this URL will be called with an additional DATAS parameter that contains the value in this field.



b - 3 fields for managing your affiliates:
  • 1 - The ap_ca field:
    This hidden field, if present, must contain an "affiliate code", which you can generate in the rubric "Affiliate links".
    If this field is present in your form, then, whoever your visitor is, the sharing percentage your set when creating this affiliate code will be credited to your affilate's Allopass account.
    This amount is deducted from our your own payout.
    This field is useful when you sell a content in partneship with another merchant for example.
    This other merchant will receive a percentage of the generated revenue and will be able to request outpayments 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 whom you'd like to give a sharing percentage without having to create an affiliate link.
    Your affiliate will find his ID in the rubric "My profile" of his Allopass account.

  • 3 - The ap_ca_mnt[n] field (n rangin from 0 to 4) :
    This is the amount (as a percentage) to be allocated to the affiliate you defined with the parameter ap_ca_idc.
    This value can range from 0 to 100.

    With these fields ap_ca_idc[n] and ap_ca_mnt[n], you can share some of your revenue with up to 5 different affiliates!
    Of course, the sum of all the ap_ca_mnt[n] can't be superior to 100.

    Lastly, if rebilling occurs, the affiliate information is conserved (your affiliate(s) will receive the same percentage than for initial subscription).

  • The 4 - ap_ca_map[n] field (n ranging from 0 to 4)
    This field must contain the ID of an "Affiliate payout program".
    An "Affiliate payout program" states for every subscription, a flat rate (this is not a percentage) that you'll re-allocate to your affiliate.

    Mind! you can't use the fields ap_ca_mnt[n] and ap_ca_map[n] together in the same script!

    Moreover, you can't use the "Affiliate payout program" with the affiliate links: if your visitor clicked one of your affiliate banners, the corresponding affiliate program will not be taken into account if an ap_ca_map[n] field is present in your access script.

    Start your own "Affiliate payout program"!



D - Optional fields of the subscriber pass capturing form

You can add various optional forms fo this form which are not present in the script provided by default.
  • The data field: this hidden field (of the HIDDEN type) may contain any value of your choice.
    When your customer is redirected to your site in case of a valid pass, your return URL will be called with an additional parameter DATAS that contains what you put there in the form.

  • The recall field: If present in the form, this hidden field with the value "1" will allow you to collect the pass inserted by the web-user, in case it's valid.
    A parameter named RECALL will be sent to you in the return URL containing the subscriber pass.




E - Checking the pass validity

Your PHP, ASP scripts or others can ask the Allopass platform to check the validity of a subscriber pass that is sent to you in the parameter recall in the pass capturing form.

Your script will send a HTTP request to our server, with the subscriber pass that you wish to check and the ID of your product as parameters.

Our server answers whether or not the code(s) is/are valid for this product.

Implementation:

- First you must collect the ID of your product. This ID is listed in the column "#AUTH" of the table that lists your product.
This ID is of the type "54/75/4567".

- Then, your return page must send a request to our server with a parameter named CODE that contains the code to be checked and a parameter named AUTH that contains the ID of your product.

- Our server can answer:
  • OK : This pass is valid for this product.
  • NOK : This pass is not valid.
  • ERR : The request was not understood (maybe an error affecting your product ID).
For instance, if the pass is valid, you can send a cookie to your customer as a proof of payment.
On the other pages of your paid-access area, you'll just need to check this cookie. If it's not present, the web-user will be redirected to an error page.

Here is a concrete example (in PHP, PERL: see bottom page):

Your HTML capturing form is like:

<form action ="http://payment.allopass.com/subscription/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 in the parameters ids and idd must be those provided in the standard script.

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

Then you can ask the Allopass platform. Here is the example in PHP :

<?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;
 }

 // $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 $r[0] variable will be found the server response
 // the $r[1] variable will read "ABOCB"

 $r=@file("http://payment.allopass.com/api/checkcode.apu?code=$RECALL&auth=$AUTH");

 // testing of the server response
 if (ereg("ERR",$r[0]) || ereg("NOK",$r[0])) 
 {
  // The server answered ERR or NOK : access is denied
  header("Location: error.html");
  exit;
 }

 // The pass is valid!
 // A cookie named CODE_OK with the value is placed
 // This cookie is valid until the web-user closes his browser
 // In the following pages, you'll just need to test the presence of the cookie
 // If it's present, the web-user is authorized,
 // otherwise he'll be redirected to an error page

 setCookie("CODE_OK","1",0,"/",".mydomain.com",false);

 //In the above line, replace ".mydomain.com" with the domain name of your site!
 //For instance if your site is available at:
 //  http://perso.hoster.com/mypage
 //then you'll have to write ".hoster.com"
 //(don't forget the "." before the domain name!!)

         
?>


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

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

Keep in mind that optimal security will be obtained by creating a session system that associates each customer to their pass.



F - Compatibilty with "One-Time" payment products

If, when creating your credit card products you chose to make subscriber pass compatible with one or several of your "One-time" product(s), the web-user will be able to access it/them by inserting his subscriber pass in the code capturing field.

In the case of a multicode product, the web-user must insert his pass in the first of the fields.

Protecting your product:
  • If you use a Javascript protection: there is nothing to change
  • If you use a PHP protection (including the sending of a HTTP request to our server),you'll have to test the second line of our server response which, in the case of a subscriber pass, returns the value "ABOCB".


G - Acknowledgment URL

If, when creating your Credit card product you set up an "acknowledgment URL" linking to one of your scripts, then this script will be called when the purchase of the subscriber pass is accepted (or when accepted rebilling occurs).

Various parameters are associated to this URL :
  • AUTH: ID of your product
  • DAYS: subscription duration
  • EXPIRE: expiring date of the subscription ( DD/MM/YYYY_HH:MM:SS)
  • CODE: Subscriber pass delivered to the web-user
  • TRANS: reference of the transaction
  • AMOUNT: amount paid by the web-user
  • RENEW: with the value "1" in the case of a rebill
  • COUNTRY: customer's country code
  • DATAS: information collected in "DATAS" if present in the form for purchasing the subscriber pass.

In addition, you can collect all the acknowledgment URL's called over the last 48 hours.

TO do so, you must call the URL:
http://www.allopass.com/webm_get_abocb_ack_xml.php4?IDC=XXX&PWD=YYY

With:
  • XXX: Your Allopass account ID
  • YYY: Your Allopass password

You can also call this URL in SSL via:

https://secure.allopass.com/webm_get_abocb_ack_xml.php4?IDC=XXX&PWD=YYY

In case of a success, what is returned to you is of the form:

<?xml version="1.0"?>
<ack>
 <Etat>OK</Etat>
 <Calls>

  <Call>

   <URL>url_appelée</URL>
   <Dinsert>1102354370</Dinsert> (date of insertion)
   <Dcall>1102354371</Dcall> (date of the URL calling)
   <DinsertTXT>06/12/2004 18:32:50</DinsertTXT> (the same, in plain)
   <DcallTXT>06/12/2004 18:32:51</DcallTXT> (the same, in plain)
  </Call>

  ....

 </Calls>
</ack>

In case of error:

<?xml version="1.0"?>

<ack>
 <Etat>NOK</Etat>
 <ErreurDescription>explications</ErreurDescription>
</ack>

Technical Information