yproximite / payum-system-pay

System Pay gateway for Payum

Payum System Pay

A Payum gateway to use SystemPay (a French payment system)

Requirements

• PHP 7.2+
• Payum
• Optionally PayumBundle and Symfony 3 or 4+

Installation

$ composer require yproximite/payum-system-pay

Configuration

With PayumBundle (Symfony)

First register the gateway factory in your services definition:

# config/services.yaml or app/config/services.yml
services:
    yproximite.system_pay_gateway_factory:
        class: Payum\Core\Bridge\Symfony\Builder\GatewayFactoryBuilder
        arguments: [Yproximite\Payum\SystemPay\SystemPayGatewayFactory]
        tags:
            - { name: payum.gateway_factory_builder, factory: system_pay }

Then configure the gateway:

# config/packages/payum.yaml or app/config/config.yml

payum:
  gateways:
    system_pay:
      factory: system_pay
      vads_site_id: 'change it' # required 
      certif_prod: 'change it' # required 
      certif_test: 'change it' # required 
      sandbox: true
      hash_algorithm: 'algo-sha1' # or 'algo-hmac-sha256'

With Payum

<?php
//config.php

use Payum\Core\PayumBuilder;
use Payum\Core\Payum;

/** @var Payum $payum */
$payum = (new PayumBuilder())
    ->addDefaultStorages()

    ->addGateway('gatewayName', [
        'factory'        => 'system_pay',
        'vads_site_id'   => 'change it', // required
        'certif_prod'    => 'change it', // required
        'certif_test'    => 'change it', // required
        'sandbox'        => true,
        'hash_algorithm' => 'algo-sha1' // or 'algo-hmac-sha256'
    ])

    ->getPayum()
;

Why hash_algorithm is prefixed by algo-?

We wanted to use sha1 or hmac-256, but there is currently a Payum limitation which try to call sha1 because it's a valid callable.

As a workaround, the only easy solution we thought was to prefix them with algo-. Since algo-sha1 is not a valid callable, there is no Payum issues and everything works well.

Usage

Make sure your Payment entity overrides getNumber() method like this:

<?php

namespace App\Entity\Payment;

use Doctrine\ORM\Mapping as ORM;
use Payum\Core\Model\Payment as BasePayment;

/**
 * @ORM\Table
 * @ORM\Entity
 */
class Payment extends BasePayment
{
    /**
     * @ORM\Column(name="id", type="integer")
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="IDENTITY")
     *
     * @var int
     */
    protected $id;

    /**
     * {@inheritdoc}
     */
    public function getNumber()
    {
        return (string) $this->id;
    }
}

By doing this, the library will be able to pick the payment's id and use it for the payment with System Pay (we should send a transaction id between 000000 and 999999).

Payment in several instalments

If you planned to support payments in several instalments, somewhere in your code you will need to call Payment#setPartialAmount to keep a trace of the amount per payment:

<?php
class Payment extends BasePayment
{
    // ...

    /**
     * @ORM\Column(type="integer", nullable=true)
     */
    protected $partialAmount;

    public function getPartialAmount(): ?int
    {
        return $this->partialAmount;
    }

    public function setPartialAmount(?int $partialAmount): void
    {
        $this->partialAmount = $partialAmount;
    }
}

Usage

<?php

use App\Entity\Payment;
use Yproximite\Payum\SystemPay\Api;
use Yproximite\Payum\SystemPay\PaymentConfigGenerator;

// Define the periods
$periods = [
    ['amount' => 1000, 'date' => new \DateTime()],
    ['amount' => 2000, 'date' => (new \DateTime())->add(new \DateInterval('P1M'))],
    ['amount' => 3000, 'date' => (new \DateTime())->add(new \DateInterval('P2M'))],
];

// Compute total amount
$totalAmount = array_sum(array_column($periods, 'amount'));

// Compute `paymentConfig` fields that will be sent to the API
// It will generates something like this: MULTI_EXT:20190102=1000;20190202=2000;20190302=3000
$paymentConfig = (new PaymentConfigGenerator())->generate($periods);

// Then create payments
$storage = $payum->getStorage(Payment::class);
$payments = [];

foreach ($periods as $period) {
    $payment = $storage->create();
    $payment->setTotalAmount($totalAmount);
    $payment->setPartialAmount($period['amount']);

    $details = $payment->getDetails();
    $details[Api::FIELD_VADS_PAYMENT_CONFIG] = $generatedPaymentConfig;
    $payment->setDetails($details);

    $storage->update($payment);
    $payments[] = $payment;
}

payum-system-pay's Issues

Improvement: allow customization of the Notify action URL

Hi!

I've been successfully receiving payment notifications from System Pay through the Payum notification url but it would be easier to work with the system if the notification URL was customizeable.

Indeed, when testing the payment integration on a local host, it's not easy to change the notification URL. I'm used to using ngrok to allow webhooks to be sent to my local dev machine, but I had to edit the code to manually specify a URL with this gateway.

Maybe the FIELD_VADS_URL_CHECK field could be taken into account during the URL building in the Capture action so that if it's set as a gateway config parameter, it overrides the host/URL used by the gateway when setting the notification token?

Can't retry payment after abort/failure

When a payment is made and results in a failure or is aborted, it can't be retried from the order payment page as the generated token for the payment does not change.

The bank gateway rejects the transaction saying that the payment has already been processed.

The token would need to be unique for each payment to allow retrying failed payments.

How to capture a payment?

Hi!

I am currently working on a Sylius shop for a customer that has a System Pay contract for receiving payments. Thanks a lot for your plugin, that simplified a lot of the dev process for us!

I one issue though: all the payments I make using the system-pay gateway are only authorized and not captured. The capture delay in the bank's back-office is set to 0 days. Is there something I should configure so that the payments are captures right away?

Thanks!

Getting no data from systempay return

Hi, thanks for your plugin !

Whenever i get back from systempay to my sylius app, none of the data is accessible in the CaptureAction.

This means this condition is never true so i keep getting back to systempay instead of validating my payment

if (null !== $details[Api::FIELD_VADS_RESULT]) {
            return;
        }

Do you have any idea why ? I tried setting vads_return_mode to GET or POST to get some data but this is not it. My $details variable only contains the data i passed it when creating the payment, never the return data from systempay.