Developer notes

Technical reference for developers who customize Przelewy24 Payments.

Add-on identity

Item	Value
Add-on id	kv_przelewy24
Function prefix	fn_kv_przelewy24_
Language variables	kv_przelewy24.*
CSS scope	.kv-przelewy24
PHP namespace	Tygh\Addons\KvPrzelewy24
Preset	payment (generated by kv new --kind integration)

Structure

Class	Role
Client\BaseClient	HTTP (cURL, TLS verification, timeouts), JSON, error mapping, masked logging
Client\Api	Przelewy24 REST API v1: Basic auth (POS ID + API key), sign (SHA-384 JSON with the CRC key), register, verify, by session id, refund, test access, methods
Client	Client per company, the connection test
PaymentService	Register, notification confirm (amount and currency check, PUT transaction/verify), read-back by session id, refunds and refund results
Transition	Pure status logic: session status (0 / 1 / 2 / 3) to local status to order status, never backwards
Accounts, Secret	Credentials (test and live) sealed with AES-256-GCM; one account per store owner or per vendor
Config, Access	Settings, owner mode, who may see and manage what
Queue, Jobs, JobException	Job queue: back-off 5 min / 15 min / 1 h / 3 h / 12 h, per-job isolation, overlap lock; handlers in Jobs::handle(), recurring work in Jobs::schedule()
Log	Event log with masking, filters, CSV, retention
Webhook	Signature check of the notification body (transaction result and refund result), idempotent event ids; the controller kv_przelewy24.webhook?c=<account> stores the event as a job, answers 200 and runs it at once

Database tables

Table	Purpose
?:kv_przelewy24_accounts	Credentials (POS ID, API key, CRC key sealed), last connection check
?:kv_przelewy24_log	Log
?:kv_przelewy24_jobs	Queue
?:kv_przelewy24_transactions, ?:kv_przelewy24_refunds	Payments and refunds

Hooks used

PHP: change_order_status_post (automatic refund when an order reaches the chosen status), prepare_checkout_payment_methods (hides the method while it cannot start payments). Template hooks: orders:tabs_extra (payment tab), addons:manage / addons:tabs_content (licence), index:styles.

Money rules

• Amounts are integers in grosz (minor units); merchantId, posId, orderId and amount are sent as integers because the checksum is calculated from the typed JSON.
• orderId of Przelewy24 does not fit a signed 32-bit integer: it is stored in a text column and never cast to a 32-bit value.
• A payment is paid only after PUT /api/v1/transaction/verify returned success.
• The notification body is never trusted for the state: amount and currency must equal the registered ones.

Test the HTTP layer without the provider

The base URL can be overridden for tests in config.local.php (development only):

$config['kv_przelewy24_base_url'] = 'http://127.0.0.1:11957';

node tests/mock-server/server.js 11957 starts a local stand-in of the provider API; node tests/e2e/e2e.mjs runs the HTTP end-to-end test against it; php tests/unit.php runs the unit tests.

Template overrides

Admin templates live in design/backend/templates/addons/kv_przelewy24/. Do not edit them in a store; they are replaced on update.