README

Інтеграція RozetkaPay Payment API з Payum: hosted checkout, одностадійна та двостадійна оплата, скасування hold і повернення коштів.

Підтримані операції:

Capture — створення hosted-платежу з confirm=true і редірект покупця на action.value.
Authorize — створення hold-платежу з confirm=false.
DoCapture із sol-parts/payum-contracts — списання hold через /confirm.
Cancel — повне розблокування hold через /cancel.
Refund — повне повернення captured-платежу через /refund.
Notify — перевірка X-ROZETKAPAY-SIGNATURE, звірка external_id і синхронізація через /info.
Sync — отримання авторитетного стану через GET /info.
GetStatus — мапінг станів RozetkaPay у статуси Payum.

Встановлення

composer require sol-parts/payum-rozetkapay

PayumBuilder

use Payum\Core\GatewayFactoryInterface;
use Payum\Core\PayumBuilder;
use SolParts\PayumRozetkaPay\RozetkaPayGatewayFactory;

$payum = (new PayumBuilder())
    ->addGatewayFactory('rozetkapay', static function (array $config, GatewayFactoryInterface $coreGatewayFactory) {
        return new RozetkaPayGatewayFactory($config, $coreGatewayFactory);
    })
    ->addGateway('rozetkapay', [
        'factory' => 'rozetkapay',
        'login' => 'merchant-login',
        'password' => 'merchant-password',
        'sandbox' => false,
    ])
    ->getPayum();

Symfony PayumBundle

Зареєструйте фабрику:

services:
    app.rozetkapay_gateway_factory:
        class: Payum\Core\Bridge\Symfony\Builder\GatewayFactoryBuilder
        arguments: [SolParts\PayumRozetkaPay\RozetkaPayGatewayFactory]
        tags:
            - { name: payum.gateway_factory_builder, factory: rozetkapay }

Налаштуйте gateway:

payum:
    gateways:
        rozetkapay:
            factory: rozetkapay
            login: '%env(ROZETKAPAY_LOGIN)%'
            password: '%env(ROZETKAPAY_PASSWORD)%'
            sandbox: false

Опції

Опція	Обов'язкова	Опис
`login`	так	Логін мерчанта для BasicAuth.
`password`	так	Пароль мерчанта для BasicAuth і перевірки callback-підпису.
`sandbox`	ні, типово `true`	`true` використовує `api-epdev.rozetkapay.com`, `false` — production API.
`api_url`	ні	Повний base URL Payment API без кінцевого `/`; має пріоритет над `sandbox`. Корисно для тестового merchant-проєкту, якщо RozetkaPay видав credentials для іншого середовища.
`on_behalf_of`	ні	Логін іншого мерчанта для заголовка `X-ON-BEHALF-OF`.
`checkout_ttl`	ні, типово `1440` (доба)	Скільки хвилин живе сторінка оплати. Дефолт шлюзу — одиниці хвилин: покупець, який відійшов по картку, повертається на «Order is not valid» (`ORDER_EXPIRED`), і замовлення лишається неоплаченим. Тому пакет підставляє власну добу; опція перекриває їх для всіх платежів магазину, а однойменний ключ у `details` — для окремого платежу.

Details платежу

ConvertPaymentAction формує:

amount з перерахунком із Payum minor units в основні одиниці валюти (12345 копійок → 123.45 UAH);
currency, description і external_id;
mode=hosted;
customer із переданих client_email, client_phone, client_first_name, client_last_name, client_patronymic.

RozetkaPay вимагає унікальний external_id для кожної окремої спроби оплати. Пакет зберігає явно передане значення; лише якщо його немає, використовує PaymentInterface::getNumber(). Повтор того самого HTTP-запиту після timeout має використовувати той самий external_id — API поверне попередній результат і не створить дубль.

Return URL веде на повторно доступний after-token Payum, callback URL — на notify-token. Callback перевіряється по сирому body до JSON-декодування за офіційним алгоритмом із base64url padding.

Статуси

RozetkaPay	Контекст	Payum
`init`, `pending`	будь-яка операція	pending
`success`	payment з `confirm=true` або confirm	captured
`success`	payment з `confirm=false`	authorized
`success`	cancel або refund	refunded; хост розрізняє cancel/refund за попереднім станом
`failure` + `session_expired`	payment	expired
`failure` + `transaction_is_canceled_by_payer`	payment	canceled
інший `failure`	будь-яка операція	failed

Sync нормалізує стан за найпізнішою операцією в /info (refund → cancel → confirm → payment), але невдала пізніша операція стан самого платежу не перекриває: відхилений /refund не перетворює captured на failed, а відхилений /confirm не ховає живий hold. Її статус береться, лише якщо іншого стану платежу у відповіді немає. Код відмови (status_code) завжди належить поточній операції — від попередньої він не успадковується.

Обмеження

Пакет реалізує hosted checkout. Direct card/token/wallet flow, рекурентні платежі, виплати, «Оплатити частинами» та фіскалізація не входять у цей gateway.
Refund робить повне повернення. API підтримує часткову суму, але стандартний flow пакета її не експонує.
Повернення може перейти в refund_pending, якщо на балансі мерчанта бракує коштів. До фінального callback воно лишається pending у Payum.

Ліцензія

MIT

sol-parts / payum-rozetkapay

Maintainers

Package info

Statistics

Security