README

ZfrPaymill is a modern PHP library based on Guzzle for Paymill payment system.

Note : this library does not contain tests, mainly because I'm not sure about how to write tests for an API wrapper. Don't hesitate to help on this ;-).

Dependencies

Guzzle: >= 3.5

Installation

Installation of ZfrPaymill is only officially supported using Composer:

php composer.phar require zfr/zfr-paymill:1.*

Tutorial

First, you need to instantiate the Paymill client, passing your private API key (you can find it in your Paymill settings):

$client = new PaymillClient('my-api-key');

The currently supported version of the API is version 2.0.

How to use it?

Using the client is easy. For instance, here is how you'd create a new offer:

$details = $client->createOffer(array(
    'name'     => 'MyOffer',
    'amount'   => 500,
    'currency' => 'EUR',
    'interval' => '1 MONTH'
));

The parameters have a direct one-to-one mapping with the official documentation (for any reference, you can also check the ZfrPaymill\Client\ServiceDescription\Paymill-2.0.php file). To know what the responses look like, please refer to the official API reference.

For most get methods, you must pass an id parameter, as follows:

$details = $client->getClient(array('id' => 'my-client-id'));

Exceptions

ZfrPaymill tries its best to throw useful exceptions. Two kinds of exceptions can occur:

Guzzle exceptions: by default, Guzzle automatically validate parameters according to rules defined in the service description before sending the actual request. If you encounter those exceptions, you likely have broken code.
ZfrPaymill exceptions: those exceptions are thrown if an error occurred on Paymill side. Each exception implement ZfrPaymill\Exception\ExceptionInterface.

Here are all the exceptions:

ZfrPaymill\Exception\UnauthorizedException: your API key is likely to be wrong...
ZfrPaymill\Exception\TransactionErrorException: transaction couldn't be completed.
ZfrPaymill\Exception\NotFoundException: is thrown whenever client receives a 404 exception.
ZfrPaymill\Exception\ValidationErrorException: some errors on your sent data.
ZfrPaymill\Exception\ServerErrorException: any errors where Paymill is likely to be doing something wrong...

Usage:

try {
    $client->createTransaction(array(
        'amount'   => 4000,
        'currency' => 'EUR',
        'token'    => '1234'
    ));
} catch (\ZfrPaymill\Exception\TransactionErrorException $exception) {
    // Seems the transaction failed, let's see why:
    $why = $exception->getMessage();

    // Let's also get the response to have more info:
    $response = $exception->getResponse();
} catch (\Exception $exception) {
    // Catch any other exception...
}

For transaction/refund/preauthorization methods, Paymill may return status code 200 even if an error occured. Paymill stores this error in a response_code property in the reponse. However, ZfrPaymill will automatically checks if this is set, and throw a TransactionErrorException, so that you don't need to check for this yourself, but only catch the exception.

Advanced usage

Listeners

Because ZfrPaymill is based on Guzzle, you can take advantage of all its feature. For instance, you can add listeners to various events by calling the addSubscriber method on the client.

Complete reference

Here is a complete list of all methods, with a link to the official documentation for parameters names:

PAYMENT RELATED METHODS:

array createPayment(array $args = array()) doc
array deletePayment(array $args = array()) doc
array getPayment(array $args = array()) doc
array getPayments(array $args = array()) doc

PREAUTHORIZATION RELATED METHODS:

array createPreauthorization(array $args = array()) doc
array deletePreauthorization(array $args = array()) doc
array getPreauthorization(array $args = array()) doc
array getPreauthorizations(array $args = array()) doc

TRANSACTION RELATED METHODS:

array createTransaction(array $args = array()) doc
array getTransaction(array $args = array()) doc
array getTransactions(array $args = array()) doc
array updateTransaction(array $args = array()) doc

REFUND RELATED METHODS:

array getRefund(array $args = array()) doc
array getRefunds(array $args = array()) doc
array refundTransaction(array $args = array()) doc

CLIENT RELATED METHODS:

array createClient(array $args = array()) doc
array deleteClient(array $args = array()) doc
array getClient(array $args = array()) doc
array getClients(array $args = array()) doc
array updateClient(array $args = array()) doc

OFFER RELATED METHODS:

array createOffer(array $args = array()) doc
array deleteOffer(array $args = array()) doc
array getOffer(array $args = array()) doc
array getOffers(array $args = array()) doc
array updateOffer(array $args = array()) doc

SUBSCRIPTION RELATED METHODS:

array createSubscription(array $args = array()) doc
array deleteSubscription(array $args = array()) doc
array getSubscription(array $args = array()) doc
array getSubscriptions(array $args = array()) doc
array updateSubscription(array $args = array()) doc

WEBHOOK RELATED METHODS:

array createWebhook(array $args = array()) doc
array deleteWebhook(array $args = array()) doc
array getWebhook(array $args = array()) doc
array getWebhooks(array $args = array()) doc
array updateWebhook(array $args = array()) doc

zfr / zfr-paymill

Maintainers

Details