====== RADIUSdesk Top-Up Functionality ======
  * We re-introduced the Top-Up system to RADIUSdesk Git code during October 2021.
  * This page will discuss the following
        * Overview of the Top-Up system.
        * Profile requirements to implement the Top-Up functionality correct.
        * Top-Up manager applet.
        * API for third party systems to integrate with the Top-Up system.

===== Overview Of Top-Up System =====
{{ :2021:topup-overview.png?nolink |}}

  *  There are three types of Top-Up transactions
        * Time
        * Data
        * Days to use
  * A Top-Up transaction can only be one of the three available types.
  * Each Top-Up transaction has to be associated with an existing Permanent User.
  * Each Top-Up transaction is owned by an Access Provider.
  * Top-Up transactions can be done by:
        * The Top-Up Manager applet which can be found under the Users section of RADIUSdesk.
        * Any 3rd Party System using the API
  * Every **Create**, **Update** and **Delete** transaction on the top-ups table will have a ripple effect to adjust the corresponding FreeRADIUS attribute of the associated Permanent User. Let us take a practical example:
        * A 3rd Party system creates a Permanent User with a profile for data Top-Ups.
        * The Rd-Total-Data attribute will be missing since there is no Top-Up loaded for this user.
        * The 3rd Party system add the first free Top-Up of 20Mb.
        * Rd-Total-Data will now have a value of 20971520 (20*1024*1024).
        * The user then purchase 1Gb of data through the 3rd Party CC Payment Gateway.
        * Rd-Total-Data will now have a value of 1094713344 (1073741824+20971520).

===== Profile Requirements For The Top-Up System =====

  * The Top-Up system can only support one specific type of top up.
        * Data Top-Up for Permanent Users who have a data based counter.
        * Time Top-Up for Permanent Users who have a time based counter.
        * Days to use for Permanent Users who have a set expiry date some time in the future.
  * To implement a Data and Time Top-Up you have to assign the Permanent User to a profile with profile component containing a **never reset** counter.
  * This **never reset** counter will have the **Rd-Total-Time / Rd-Total-Data** attribute missing since it will be assigned to the specific Permanent User as a private attribute.
  * With the latest RADIUSdesk it is very simple to create such a profile.
  * See the following screenshot

{{ :2021:profile_top_up.png?nolink |}}

  * See the Profile Component which was automatically created for us when when we save the Profile

{{ :2021:profile_top_up2.png?nolink |}}


===== Top-Up Manager Applet =====
  * RADIUSdesk includes an applet that allows you to manually manage Top-Ups.
  * You can do the standard CRUD (Create Read Update and Delete) functions on the listed Top-Ups.
  * The applet has two tabs. The **Home** tab is used to do the standard CRUD.
  * There is also a **Transaction History** tab which can be used for audit purposes.
{{:2021:top_up1.png?nolink|}}
  * **Transaction History** tab
{{:2021:top_up2.png?nolink|}}

===== API For Third Party Systems =====
  * If you have a 3rd party system which will interact with RADIUSdesk to add Top-Ups then this section is for you.
  * 
<file php add_top_up.php>
<?php 

print("RADIUSdesk API to Add a TopUp for a Permanent user");
/*
 
    * = required
 
    == Adding a 1Gb Data top-up ==
 
    comment	            One Gb data (optional)
    *data_unit	            gb (options 'mb' or 'gb')
    *permanent_user_id	187 (alternatively you can use 'permanent_user = <permanent user's username>' to avoid lookup for ID)
    *token	            52190fff-a800-48eb-b1f2-478bc0a80167 (root user's token)
    *type	            data (other options are 'time' or 'days_to_use')
    *value	            1 (the amount of data/time or days_to_use)
    *user_id                0 (keep zero to make the owner the owner of the token)
 
    == Adding a 50 minutes Time top-up ==
 
    comment	            50 minutes Time (optional)
    *time_unit	            minutes (options 'minutes' or 'hours' or 'days')
    *permanent_user_id	    187 (alternatively you can use 'permanent_user = <permanent user's username>' to avoid lookup for ID)
    *sel_language	    4_4
    *token	            52190fff-a800-48eb-b1f2-478bc0a80167 (root user's token)
    *type	            time (other options are 'time' or 'days_to_use')
    *value	            1 (the amount of data/time or days_to_use)
    *user_id                0 (keep zero to make the owner the owner of the token)
 
*/
 
$comment	            = 'Two Gb data';
$data_unit	            = 'gb'; 
$permanent_user_id   = 187; 
$permanent_user        = 'dvdwalt';
$token	                    = '52190fff-a800-48eb-b1f2-478bc0a80167';
$user_id                      = 0; //The owner is the owner of the token
$type                           = 'data'; 
$value	                    = 2;
 
$url                        = 'http://127.0.0.1/cake3/rd_cake/top-ups/add.json';
 
// The data to send to the API
$postData = array(
    'comment'               => $comment,
    'data_unit'             => $data_unit,
    //'permanent_user_id'     => $permanent_user_id,
    'permanent_user'        => $permanent_user,
    'token'                 => $token,
    'user_id'               => $user_id,
    'type'                  => $type,
    'value'                 => $value
);
 
// Setup cURL
$ch = curl_init($url);
curl_setopt_array($ch, array(
 
    CURLOPT_POST            => TRUE,
    CURLOPT_RETURNTRANSFER  => TRUE,
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json'
    ),
    CURLOPT_POSTFIELDS => json_encode($postData)
));
 
// Send the request
$response = curl_exec($ch);
 
// Check for errors
if($response === FALSE){
    die(curl_error($ch));
}
 
// Decode the response
$responseData = json_decode($response, TRUE);
print_r($responseData);

?>
</file>