zfr / zfr-paymill
PHP library for interacting with the Paymill REST API
Requires
- php: >=5.3.3
- guzzle/guzzle: >=3.5,<=3.8
Requires (Dev)
- phpunit/phpunit: ~3.7
This package is auto-updated.
Last update: 2024-10-29 03:33:02 UTC
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 aTransactionErrorException
, 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: