Developer / API

Plugin API

Yui\TatraPay\Plugin implements yStore's yui\craft\base\collector\PaymentMethodRegistryInterface and registers itself with the store's PaymentMethodRegistry once all plugins have loaded (Plugins::EVENT_AFTER_LOAD_PLUGINS). These methods are yStore's checkout contract; they are not normally called directly from custom code, but are useful when debugging a checkout integration.

use Yui\TatraPay\Plugin;

$details = Plugin::$plugin->getDetails();

Method	Purpose
getDetails(): array	Returns the payment method descriptor(s) yStore uses to list Tatra methods at checkout. Always includes the base card method (tatra-pay) and the PayLater method (tatra-pay-loan, gated by enablePayLaterType). When Payment Type is tatraPayPlusAPI, also includes Bank Transfer (tatra-pay-bank, gated by enableBankTransfer) and QR Pay (tatra-pay-qr, gated by enableQrPay). Each descriptor carries name, code/handle, type (online), instructions, price, enabled, url, logo, description.
placeOrder(array $data, array $items, ?string $code = null): array	Builds and sends the payment request for an order, dispatched by $code (see below). Returns ['redirectUrl' => ..., 'extra' => $api->getParams()] on success, or [] on invalid data/items or a gateway error.
postValidate(array $params): array	Called on the checkout return/callback. Behaviour depends on the configured Payment Type and on $params; returns `['success' => bool, 'paid' => float
getPaymentRetryUrl(array $order, array $items): ?string	Delegates to the gateway; not implemented as a distinct retry URL in this plugin version.

TatraPayGateway::placeOrder() dispatches on the $code argument passed by yStore, matching the codes returned from getDetails():

$code	Flow
tatrapay (Payment Type tatraCardPay)	Classic HMAC-signed CardPay redirect form. Requires merchantMid (must match ^[a-z0-9]{3,4}$) and secretKey.
tatrapay (Payment Type tatraPayPlusAPI)	POST /v1/payments with Preferred-Method: CARD_PAY. Requires apiKey and clientSecret.
tatrapay-bank	POST /v1/payments with Preferred-Method: BANK_TRANSFER and a bankTransfer.remittanceInformationUnstructured note. TatraPay Plus API only.
tatrapay-qr	POST /v1/payments with Preferred-Method: QR_PAY. TatraPay Plus API only.
tatrapay-loan	POST /v1/applications against the PayLater endpoint, with order line items, applicant details, and an externalApplicantId. Uses the PAY_LATER OAuth scope.

postValidate() behaviour

• tatraCardPay: reads the bank's RES/AMT return params. RES === 'OK' marks the payment successful.
• tatraPayPlusAPI: reads paymentId from the return params, calls ApiService::getPaymentStatus(), and maps authorizationStatus:
  • OK → success. If selectedPaymentMethod is BANK_TRANSFER or QR_PAY, status is set to payment_review instead of an immediate paid state, since those methods settle asynchronously.
  • CANCEL / EXPIRED / DECLINED → status = 'canceled'.
  • In sandbox mode, authorizationStatus is forced to OK.
• Loan / PayLater (order_number present in params): looks up the order's payment transaction, reads the stored applicationId from transaction.extra, and calls ApiService::getApplicationStatus(). LOAN_DISBURSED → payment_review; CANCEL/EXPIRED → canceled.

ApiService

Yui\TatraPay\services\ApiService (via Plugin::$plugin->getApi()) wraps the TatraPay Plus API v1.5.2. All methods use Guzzle and throw/log through yui\craft\Plugin::error() on failure; most return an empty/null result rather than propagating the exception.

Method	Purpose
getAccessToken(string $scope = 'TATRAPAYPLUS'): ?string	OAuth2 client_credentials token request to /auth/oauth/v2/token. Scopes: TATRAPAYPLUS (card/bank/QR) and PAY_LATER (loan).
getPaymentStatus(string $paymentId): ?array	GET /v1/payments/{id}/status. Returns a normalized array: authorizationStatus, selectedPaymentMethod, amount, maskedCardNumber, status, plus the raw cardPayStatus/bankTransferStatus/payLaterStatus/comfortPayStatus sub-objects.
getApplicationStatus(string $applicationId): ?array	GET /v1/applications/{id}/status for PayLater loan applications. Returns ['status' => ...].
getPaymentMethods(): array	GET /v1/payments/methods. Lists payment methods available to the merchant account.
cancelPayment(string $paymentId): bool	Cancels a TatraPay Plus payment intent.
getLoanPrecalculation(float $amount, string $currency = 'EUR', ?int $preferredDuration = null, ?float $downPayment = null): array	PUT /v1/payments/loans/precalculation. Used to preview instalment terms before initiating a loan application.

Order edit hook

When Payment Type is tatraPayPlusAPI, the plugin injects a Check Payment Status button into the order edit page via the order-edit-extra-actions Twig hook, shown only while the order status is pending_payment. It links to the shared yui/payment-transactions/check-payment-status/{orderId} CP route.

Control panel routes

Route	Handler	Notes
tatrapay/dashboard	DashboardController	Default CP nav landing page. Requires accessPlugin-tatrapay.
tatrapay/settings/*	SettingsController	General, Credentials, Pricing, Restrictions, Test cards sections; save-settings action shared across all sections.
tatrapay/settings/test	SettingsController::actionTest()	Requests an access token to validate the configured API credentials, then redirects back with a flash message.

Events

Yui\TatraPay\plugin\Events registers TatraPayGateway with yStore's PaymentService::EVENT_REGISTER_PAYMENT_GATEWAYS on plugin init. Saving any settings section (SettingsController::afterSettingsSaved()) clears the payment_methods_ dynamic storage cache key so checkout picks up the new configuration immediately.