README

Paysafecard driver for the Omnipay PHP payment processing library

This is non-official Omnipay-driver for the payment gateway provider Paysafecard. In order to use it the Omnipay-Framework is required.

Omnipay is a framework agnostic, multi-gateway payment processing library for PHP 5.3+. This package implements Paysafecard REST API support for Omnipay.

Installation

This package is installed via Composer. To install, simply add it to your composer.json file:

$ composer require sauladam/omnipay-paysafecard-rest

And run composer to update your dependencies:

$ composer update

Basic Usage

The following gateway is provided by this package:

Paysafecard_Rest

For general usage instructions, please see the main Omnipay repository.

Setting up the gateway

This is quite simple because the API only needs an API key.

require 'vendor/autoload.php';

use Omnipay\Omnipay;

$gateway = Omnipay::create('Paysafecard_Rest');

$gateway->setApiKey('yourApiKey');

// Testmode is on by default, so you want to switch it off for production.
$gateway->setTestMode(false); // default: true

Initializing / authorizing a payment

$response = $gateway->authorize([
    'amount' => 0.01,
    'currency' => 'EUR',
    'success_url' => 'http://success.com/{payment_id}',
    'failure_url' => 'http://fail.com/{payment_id}',
    'notification_url' => 'http://notify.com/{payment_id}',
    'customer_id' => 1234,
])->send();

if ($response->isSuccessful()) {
    $paymentId = $response->getPaymentId(); 
    
    // this is the url you should redirect the customer 
    // to or display within an iframe
    $authUrl = $response->authUrl();
} else {
    echo 'Something went wrong: ' . $response->getMessage();
}

The auth URL points to a (secure) page where the customer can enter their Paysafecard PIN number. You can redirect the customer to that URL or embed it as an iframe and display it to them - either is fine.

After the customer has filled out and submitted the form, Paysafecard will redirect them to what you've specified as your success_url in the authorize request. Ideally that URL should contain some kind of payment identifier or some reference to your previously stored $paymentId (Paysafecard will replace the placeholder {payment_id} in the URL with the actual payment id), because you now need it to check the status of this transaction:

Check the status

$response = $gateway->details([
    'payment_id' => $paymentId,
])->send();

The status now should be AUTHORIZED, so check for that:

if($response->getStatus() == 'AUTHORIZED')
{
    // The customer has authorized the payment, we're now ready to capture it.
}

Capture the transaction

$response = $gateway->capture([
    'payment_id' => $paymentId,
])->send();

if($response->getStatus() == 'SUCCESS') {
    // You have successfully captured the payment, the order is ready to ship.
}

Refunds

In order to use the Refund API, you have to ask paysafecard explicitly to enable this endpoint for your merchant account, otherwise you will get a "401 Unauthorized" response.

If you want to execute the refund immediately, just use the refund()-funtion directly with all the required data:

$response = $gateway->refund([
    'payment_id' => $paymentId,
    'amount' => 12.34,
    'currency' => 'EUR',
    'customer_email' => 'customer@email.com',
    'customer_id' => 1234,
])->send();

if($response->getStatus() == 'SUCCESS') {
    // The amount was successfully refunded.
}

However, it is recommended to validate the refund first in order to "precheck the likeliness of the upcoming refund to be successful" because "there are certain conditions why a refund might be refused".

So instead of refund() you should rather use validateRefund() first with the same data and only request the refund if the validation passed:

$validationResponse = $gateway->validateRefund([
    // same data as above
])->send();

if(! $validationResponse->isSuccessful() || $validationResponse->getStatus() != 'VALIDATION_SUCCESSFUL') {
    // something went wrong...
}

$refundResponse = $gateway->refund([
  'payment_id' => $paymentId,
  'refund_id' => $response->getRefundId(),
])->send();

if($refundResponse->isSuccessful()) {
    echo "The refund was successful and the refund id is " . $refundResponse->getRefundId(); 
}

Support

For more usage examples please have a look at the tests of this package. Also have a look at the Paysafecard API Documentation for further details.

If you are having general issues with Omnipay, we suggest posting on Stack Overflow. Be sure to add the omnipay tag so it can be easily found.

If you want to keep up to date with release anouncements, discuss ideas for the project, or ask more detailed questions, there is also a mailing list which you can subscribe to.

If you believe you have found a bug, please report it using the GitHub issue tracker, or better yet, fork the library and submit a pull request.

sauladam / omnipay-paysafecard-rest

Maintainers

Details