README

Paczka integrująca PayU za pomocą OpenPayu SDK.

Instalacja

composer require x-one/payu-bundle

Symfony Flex powinien automatycznie dodać nowy wpis do pliku config/bundles.php.

Konfiguracja

Paczkę konfigurujemy za pomocą pliku config/packages/x_one_payu.yaml.

x_one_payu:
  api:
    environment: ...           # Środowisko - "sandbox" lub "secure"
    merchant_pos_id: ...       # Id punktu płatności (pos_id)
    signature_key: ...         # Drugi klucz (MD5)
    oauth_client_id: ...       # Protokół OAuth - client_id
    oauth_client_secret: ...   # Protokół OAuth - client_secret
    oauth_grant_type: ...      # Grant type - "client_credentials" (domyślnie) lub "trusted_merchant"
    oauth_email: ...           # Wymagane, jeżeli grant type ustawiony na "trusted_merchant"
    oauth_ext_customer_id: ... # Wymagane, jeżeli grant type ustawiony na "trusted_merchant"
    continue_route: ...        # Symfonowy route do przekierowania po płatności
    notify_route: ...          # Symfonowy route do odbioru powiadomienia o zmianie statusu

Powyższe wartości konfiguracyjne (poza routkami) pobieramy z konfiguracji punktu płatności sklepu w panelu PayU. Zakładka "Moje sklepy" > Wchodzimy w konkretny sklep > zakładka "Punkty płatności" > W szczegółach danego punktu mamy widoczną konfigurację.

Routing

Paczka udostępnia route przetwarzający powiadomienia z PayU. Aby je zaimportować, dodaj wpis do config/routes.yaml:

x_one_payu:
  resource: '@XOnePayuBundle/config/routes.php'
  prefix: /payments/payu

Zaimportowany route można wykorzystać w konfiguracji paczki:

x_one_payu:
  api:
    notify_route: x_one_payu_notify

Encje

Paczka wymaga dodania encji:

PayuOrder rozszerzającej XOne\Bundle\PayuBundle\Entity\Order

Przykład encji:

<?php

declare(strict_types=1);

namespace App\Entity\Payment;

use App\Repository\Payment\PayuOrderRepository;
use Doctrine\ORM\Mapping as ORM;
use XOne\Bundle\PayuBundle\Entity\Order;

#[ORM\Entity(repositoryClass: PayuOrderRepository::class)]
#[ORM\Table(name: 'payu_order')]
class PayuOrder extends Order
{
}

Po ich utworzeniu należy dodać je do konfiguracji:

# config/packages/x_one_payu.yaml
x_one_payu:
  entities:
    order: App\Entity\Payment\PayuOrder

Tworzenie zamówienia

Aby stworzyć zamówienie w PayU, należy utworzyć encję zamówienia i przekazać ją do klienta HTTP:

/**
 * @var XOne\Bundle\PayuBundle\Http\ClientInterface $payuClient
 * @var XOne\Bundle\PayuBundle\Factory\OrderFactoryInterface $payuOrderFactory
 * @var XOne\Bundle\PayuBundle\Model\OrderInterface $payuOrder
 */

$payuOrder = $payuOrderFactory->createOrder(
    description: 'Zamówienie w sklepie',
    currencyCode: 'PLN',
    totalAmount: 149_99, // 149.99zł
);

$payuClient->createOrder($payuOrder);

W przekazanym obiekcie zamówienia uzupełnione zostają:

identyfikator zamówienia PayU;
link do przekierowania klienta na stronę płatności;

Opis zamówienia

Zamówienie PayU składa się z 4 różnych opisów:

Pole	Opis
`description`	Opis zamówienia widoczny w panelu PayU (wymagany)
`additionalDescription`	Dodatkowy opis zamówienia widoczny w panelu PayU (opcjonalny)
`visibleDescription`	Opis zamówienia widoczny dla kupującego na stronie płatności PayU (opcjonalny)
`statementDescription`	Opis widoczny na wyciągu bankowym, w tytule operacji (opcjonalny)

Aktualizacja statusu zamówienia

PayU informuje system o aktualizacji zamówienia wysyłając zapytania POST na wcześniej skonfigurowany notify_route. Wbudowany kontroler XOne\Bundle\PayuBundle\Controller\NotifyController uruchamia proces obsługi powiadomienia:

use Symfony\Component\HttpFoundation\Response;
use XOne\Bundle\PayuBundle\Http\ClientInterface;

class NotifyController
{
    public function __construct(
        private ClientInterface $client,
    ) {
    }

    public function __invoke(): Response
    {
        $this->client->consumeNotification();

        return new Response();
    }
}

Bundle dispatchuje event XOne\Bundle\PayuBundle\Event\NotificationEvent, w którym mamy dostęp do:

obiektu zamówienia;
odpowiedzi od PayU;

Dzięki temu możemy podpiąć własną logikę do obsługi tych powiadomień. Bazowo bundle nasłuchuje tego eventu przez listener XOne\Bundle\PayuBundle\EventListener\UpdateOrderStatusFromNotification, który aktualizuje status zamówienia.

Rozwój bundle

Uwaga: wszystkie poniższe kroki wymagane przed wydaniem nowej wersji można uruchomić za pomocą pojedynczej komendy:

composer run-script pre-commit-checks

Testy

Upewnij się, że testy nie zwracają żadnego błędu:

vendor/bin/simple-phpunit

Quality control

Upewnij się, że kod jest sformatowany poprawnie (dzięki php-cs-fixer) oraz że PHPStan nie zwraca żadnych błędów:

vendor/bin/php-cs-fixer fix
vendor/bin/phpstan analyze

Wersjonowanie

Aby paczkę dało się zaktualizować przez composera, po zmergowaniu zmian do głównego brancha, należy utworzyć tag w formacie vX.Y.Z, np.

git tag -a v1.1.0 -m "Version v1.1.0"
git push --tags

x-one / payu-bundle

Maintainers

Details