PHP Paysafecard API class

This package contains the following structure:

/
|-- example
|   `-- psc_example.php`
|-- files
|   `-- psc.api.php`
|   `-- psc.exceptions.php`
|-- CHANGELOG

Place the files inside the files folder where you can include them from your project.

Configuring the paysafecard class

If you want to use the paysafecard class just copy the psc.api.php and psc.exceptions.php into your project and include them. Because the API has only one class instance you can get a singleton instance and set or get the values you need to set up your cashin form.

require_once("psc.api.php");
require_once("psc.exceptions.php");

$instance = \OutstandDesign\PSC\Paysafecard::getSingleton();
$instance->Session = $_POST;
$instance->Cookie = $_POST;

You can change from live mode (productivity - default) to debug mode (testing) by setting the Debug variable to true.

$instance->Debug = true;

While working in debug mode the only working pin is:

1234-1234-1234-1234

Further you have to use these login credentials:

Username: Test

Password: 1337

See the example file for a more detailed example.

1. Set up your input form

After configuring the paysafecard class you have to init the current session. You can also force a refresh of the session and cookie data (for example after every form submit).

public function Init ( bool $renew = false )

Now you can get the values needed for your input form. The required values are:

$instance->Session
$instance->Cookie
$instance->Captcha

These three values contain the session and cookie ID and further the captcha image as data:image/jpg;base64, encoded string.

<img src="data:image/jpg;base64,<?php echo $instance->Captcha; ?>">

Note The values change automaticly with the first (when you don't set them before) and every forced Init

That the script works you have to send (or save) the session id and cookie together with the captcha input which the form submits. When getting a request of the submitted form you have to set the old (submitted) session and cookie ID before you use the Init method to load the old session. This can be easily done with the following code:

$instance->Session = $_POST['session_id']; # if send by a hidden field value
$instance->Cookie = $_POST['cookie_id']; # if send by a hidden field value

Now you have the old session loaded and can use the the Check method.

Example

// configuration at this point already done
if(isset($_POST['cookie']) && isset($_POST['session']))
{
    // Set Sessioninformation to retrieve old instance
    $instance->SessionID = $_POST['session'];
    $instance->Cookie = $_POST['cookie'];

    // Convert pincodes to xxxx-xxxx-xxxx-xxxx format $_POST['code'] is an array with 4 elements
    $_POST['code'] = implode('-', $_POST['code']);

    // Ready for doing some stuff with the submitted pin
    // like checking and adding

    // Force a renew of the session
    $instance->Init(true);
}

// Load Session if not already done
$instance->Init();

2. Check a pin on validation

Use the Check method to validate that the submitted pin is valid and can be cashed in by using MyPinAccount_AddPincode.

public function Check ( string $Pin, string $CaptchaInput )

Parameters

$Pin string The Pincode in the format: NNNN-NNNN-NNNN-NNNN where as every N is a number from 0-9
$CaptchaInput string The Captcha needs to have the following format: NNNNN (5 numbers from 0-9)

Exceptions

Code 2301 \OutstandDesign\Exception\WrongPinCodeException Your $Pin does not match the format restriction
Code 2302 \OutstandDesign\Exception\InvalidCaptchaException Your $CaptchaInput does not match the format restriction
Code 2307 \OutstandDesign\Exception\InvalidSessionInformationException Your Session and Cookie informations are not correct
Code 2311 \OutstandDesign\Exception\SessionTimedOutException The Paysafecard page is currently unavailable
Code 1338 \OutstandDesign\Exception\ServiceTemporarilyUnavailableException Normally when Paysafecard has temp. banned your server because of to many requests at a time
Code 2306 \OutstandDesign\Exception\PinPasswordProtectedException $Pin is password protected. Please get in contact with Paysafecard
Code 2303 \OutstandDesign\Exception\WrongCaptchaInputException $CaptchaInput is not valid
Code 2304 \OutstandDesign\Exception\WrongPinCodeInputException $Pin is not valid
Code 2309 \OutstandDesign\Exception\PinAlreadyUsedException $Pin is already cashed into your/another MyPins Account
Code 2342 \OutstandDesign\Exception\UnknownErrorException Please contact the developer to fix this problem

Returns

bool True if the pin could be succesfully checked else an exception

Example

try {
    // Try to check if pin is correct and captcha is valid
    if($psc_instance->Check($_POST['code'], $_POST['captcha'])) {
         // inside this block everything is okay with the pin and the captcha
    }
} catch (OutstandDesign\Exception\PaysafecardException $e) {
    // if an error occurs switch the error code and handle exception
    switch($e->getCode())
    {
        // for example 1338: Service temporarily unavailable
        case 1338:
            echo  '<b>Our service is unfortunatly currently unavailable.</b>';
            break;  

        // for example 2303: Captcha validation failed
        case 2303:
            echo '<b>Your submitted captcha doesn\'t match the picture.</b>'; 
            break;

        // for example 2304: Pincode validation failed
        case 2304:
            echo '<b>Your submitted pin isn\'t valid.</b>'; 
            break;

        // if error wasn't handled throw it to the user screen
        default:
            throw $e;   
    }
}

3. Adding a pin to your account

After checking the submitted pin you have to add it to your myPins account. This can be done by using the AddPincode method.

public function AddPincode ( string $Username, string $Password, string $Pin)

This will return an array like in the next line if everything worked well else an exception with the error will be thrown.

array [2] {
    "fund" =>
    float(10.0),
    "serial" =>
    string("7.....")
}

Parameters

$Username string Your MyPins Username
$Password string Your MyPins Password
$Pin string The Pincode in the format: NNNN-NNNN-NNNN-NNNN where as every N is a number from 0-9

Exceptions

Code 1337 \OutstandDesign\Exception\NotLoggedInException When your login credentials were wrong
Code 2301 \OutstandDesign\Exception\WrongPinCodeException Your $Pin does not match the format restriction
Code 1339 \OutstandDesign\Exception\MyPinSecurityBanException Your account has been banned due to security reasons
Code 2307 \OutstandDesign\Exception\InvalidSessionInformationException An internal error occured. Please reply to the developer
Code 2310 \OutstandDesign\Exception\OutOfLimitsException Your maximum limit has been reached. Next cashin possible at the start of the next month
Code 1338 \OutstandDesign\Exception\ServiceTemporarilyUnavailableException Normally when Paysafecard has temp. banned your server because of to many requests at a time
Code 2306 \OutstandDesign\Exception\PinPasswordProtectedException $Pin is password protected. Please get in contact with Paysafecard
Code 2304 \OutstandDesign\Exception\WrongPinCodeInputException $Pin is not valid
Code 2308 \OutstandDesign\Exception\PinTemporarilyUnavailableException The $Pin is currently not available
Code 2312 \OutstandDesign\Exception\WrongPinCurrencyException $Pin is not in the same currency as your MyPins Account
Code 2309 \OutstandDesign\Exception\PinAlreadyUsedException $Pin is already cashed into your/another MyPins Account
Code 2342 \OutstandDesign\Exception\UnknownErrorException Please contact the developer to fix this problem

Returns

array Array with the key fund (the balance cashed in) and serial (the serial number of the cashed in pin)

Example

$username = "EnterYourUsername";
$password = "EnterYourPassword";

 // if pin is valid try to add pin to your account
 $account_information = $instance->AddPincode($username, $password, $_POST['code']);

<?php
// include the public API
require_once "../files/psc.exceptions.php";
require_once "../files/psc.api.php";

$msg = "";
$instance = OutstandDesign\PSC\Paysafecard::getSingleton();
// active debugmode
//See docs/changelog for detailed informations
$instance->Debug = true;

// If our form has been submitted
if(isset($_POST['cookie']) && isset($_POST['session']))
{
    // Set Sessioninformation to retrieve old instance
    $instance->SessionID = $_POST['session'];
    $instance->Cookie = $_POST['cookie'];

    // Convert pincodes to xxxx-xxxx-xxxx-xxxx format
    $_POST['code'] = implode('-', $_POST['code']);
    try {
        // Try to check if pin is correct and captcha is valid
        if($instance->Check($_POST['code'], $_POST['captcha'])) {
            $username = "EnterYourUsername";
            $password = "EnterYourPassword";

            // if pin is valid try to add pin to your acccount
            $account_information = $instance->AddPincode($username, $password, $_POST['code']);
        }
    } catch (OutstandDesign\Exception\PaysafecardException $e) {
        // if an error occurs switch the error code and handle exception

        // all error codes can be found in the documentation
        // @ http://docs.outstand-design.de/cashin_script/
        switch($e->getCode())
        {
            // for example 1338: Service temporarily unavailable
            case 1338:
                $msg = '<b>Our service is unfortunatly currently unavailable.</b>';
                break;  

            // for example 2303: Captcha validation failed
            case 2303:
                $msg = '<b>Your submitted captcha doesn\'t match the picture.</b>'; 
                break;

            // for example 2304: Pincode validation failed
            case 2304:
                $msg = '<b>Your submitted pin isn\'t valid.</b>'; 
                break;

            // if error wasn't handled throw it to the user screen
            default:
                throw $e;   
        }
    }
    $instance->Init(true); // Force session_id and cookie to be renewed
}

// Load new session informations. Doesn't change session_id or cookie if already set
$instance->Init();

?>
<!DOCTYPE html>
<html>
    <head></head>
    <body>
        <?php echo $msg; ?>

        <form action="" method="post">
            <label for="code">Pin:</label>
                <input type="input" maxlength="4" size="1" pattern="[0-9]{4}" autocomplete="off" name="code[pin1]" value="">
                <input type="input" maxlength="4" size="1" pattern="[0-9]{4}" autocomplete="off" name="code[pin2]" value="">
                <input type="input" maxlength="4" size="1" pattern="[0-9]{4}" autocomplete="off" name="code[pin3]" value="">
                <input type="input" maxlength="4" size="1" pattern="[0-9]{4}" autocomplete="off" name="code[pin4]" value=""><br>
            <img src="data:image/jpg;base64,<?php echo $instance->Captcha; ?>">
            <input type="input" maxlength="5" size="1" pattern="\d{5}" name="captcha"><br>
            <input type="hidden" name="cookie" value="<?php echo $instance->Cookie; ?>"><input type="hidden" name="session" value="<?php echo $instance->SessionID; ?>">
    <input type="submit" value="Senden"></form>

</body>
</html>