Get started

Here we describe basic steps required by all supported gateways. We are going to setup models, storages, a security layer and so on. All that stuff will be used later.

Note: If you are working with Symfony framework look read the bundle's documentation instead.

Note: If you are working with Laravel framework look read the documentation instead.

Install

The preferred way to install the library is using composer. Run composer require to add dependencies to composer.json:

php composer.phar require payum/offline php-http/guzzle7-adapter

Note: Where payum/offline is a php payum extension, you can for example change it to payum/paypal-express-checkout-nvp or payum/stripe. Look at supported gateways to find out what you can use.

Note: Use payum/payum if you want to install all gateways at once.

Note: Use php-http/guzzle7-adapter is just an example. You can use any of these adapters.

Before we configure payum, let's look at the flow diagram. This flow is same for all gateways so once you familiar with it any other gateways could be added easily.

How payum works

As you can see we have to create some php files: config.php, prepare.php, capture.php and done.php. At the end you will have the complete solution and it would be much easier to add other gateways. Let's start from the config.php and continue with rest after:

config.php

Here we can put our gateways, storages. Also we can configure security components. The config.php has to be included to all left files.

<?php
//config.php

use Payum\Core\PayumBuilder;
use Payum\Core\Payum;
use Payum\Core\Model\Payment;

$paymentClass = Payment::class;

/** @var Payum $payum */
$payum = (new PayumBuilder())
    ->addGateway('aGateway', [
        'factory' => 'offline',
    ])

    ->getPayum()
;

Note: There are other storages available. Such as Doctrine ORM\MongoODM.

Note: Consider using something other than FilesystemStorage in production.

prepare.php

At this stage we have to create an order. Add some information into it. Create a capture token and delegate the job to capture.php script. Here's an offline gateway example:

<?php
// prepare.php

include __DIR__.'/config.php';

$gatewayName = 'aGateway';

/** @var \Payum\Core\Payum $payum */
$storage = $payum->getStorage($paymentClass);

$payment = $storage->create();
$payment->setNumber(uniqid());
$payment->setCurrencyCode('EUR');
$payment->setTotalAmount(123); // 1.23 EUR
$payment->setDescription('A description');
$payment->setClientId('anId');
$payment->setClientEmail('[e-mail]');

$payment->setDetails(array(
  // put here any fields in a gateway format.
  // for example if you use Paypal ExpressCheckout you can define a description of the first item:
  // 'L_PAYMENTREQUEST_0_DESC0' => 'A desc',
));


$storage->update($payment);

$captureToken = $payum->getTokenFactory()->createCaptureToken($gatewayName, $payment, 'done.php');

header("Location: ".$captureToken->getTargetUrl());

Note: There are examples for all supported gateways.

capture.php

When the preparation is done a user is redirect to capture.php. Here's an example of this file. You can just copy\past the code. It has to work for all gateways without any modification from your side.

<?php
//capture.php

use Payum\Core\Request\Capture;
use Payum\Core\Reply\HttpRedirect;
use Payum\Core\Reply\HttpPostRedirect;

include __DIR__.'/config.php';

/** @var \Payum\Core\Payum $payum */
$token = $payum->getHttpRequestVerifier()->verify($_REQUEST);
$gateway = $payum->getGateway($token->getGatewayName());

/** @var \Payum\Core\GatewayInterface $gateway */
if ($reply = $gateway->execute(new Capture($token), true)) {
    if ($reply instanceof HttpRedirect) {
        header("Location: ".$reply->getUrl());
        die();
    } elseif ($reply instanceof HttpPostRedirect) {
        echo $reply->getContent();
        die();
    }

    throw new \LogicException('Unsupported reply', null, $reply);
}

/** @var \Payum\Core\Payum $payum */
$payum->getHttpRequestVerifier()->invalidate($token);

header("Location: ".$token->getAfterUrl());

Note: Find out more about capture script in the dedicated chapter.

done.php

After the capture did its job you will be redirected to done.php. The capture.php script always redirects you to done.php no matter the payment was a success or not. In done.php we may check the payment status, update the model, dispatch events and so on.

<?php
// done.php

use Payum\Core\Request\GetHumanStatus;

include __DIR__.'/config.php';

/** @var \Payum\Core\Payum $payum */
$token = $payum->getHttpRequestVerifier()->verify($_REQUEST);
$gateway = $payum->getGateway($token->getGatewayName());

// you can invalidate the token. The url could not be requested any more.
// $payum->getHttpRequestVerifier()->invalidate($token);

// Once you have token you can get the model from the storage directly. 
//$identity = $token->getDetails();
//$payment = $payum->getStorage($identity->getClass())->find($identity);

// or Payum can fetch the model for you while executing a request (Preferred).
$gateway->execute($status = new GetHumanStatus($token));
$payment = $status->getFirstModel();

header('Content-Type: application/json');
echo json_encode([
    'status' => $status->getValue(),
    'order' => [
        'total_amount' => $payment->getTotalAmount(),
        'currency_code' => $payment->getCurrencyCode(),
        'details' => $payment->getDetails(),
    ],
]);

Note: Find out more about done script in the dedicated chapter.

---

Supporting Payum

Payum is an MIT-licensed open source project with its ongoing development made possible entirely by the support of community and our customers. If you'd like to join them, please consider:

• Become a sponsor