Skip to main content
Version: 2.0.0

SimplePay

yui/craft-simplepay adds SimplePay (OTP Mobil Kft.) as an online payment method to checkout on a store running yui/craft-plugin. SimplePay is a Hungarian card payment gateway; the plugin drives SimplePay's hosted card payment page through OTP Mobil's official PHP SDK (bundled in the plugin under src/simplepay/).

Use it when you want to accept bank card payments routed through SimplePay, typically for a store selling into the Hungarian market.

What it does​

  • Registers itself with the yStore payment method registry (PaymentMethodRegistryInterface) once all plugins have loaded, so SimplePay appears as a selectable payment option at checkout alongside any other configured payment method — but only while the plugin is enabled.
  • Builds a SimplePay "start" transaction from the current order (total, currency, order reference, customer email, billing address, line items, language) and redirects the customer to SimplePay's hosted payment page.
  • Optionally sends invoice data (name, company, country, city, postcode, street) with the transaction, but only once every required address field is present — see Developer → Invoice data.
  • Validates the signed notification SimplePay sends back on the checkout return URL and reports success/failure to yStore's checkout flow.
  • Adds a License page under the plugin's CP navigation, consistent with other YUI plugins.
  • Ships Czech, German, Hungarian, and Slovak translation files (currently empty — see Developer → Translations); unlisted or untranslated strings fall back to English.

Where admins work with this plugin​

In Craft CP, open the plugin's own CP navigation section (SimplePay):

  • Dashboard (yui-simplepay/dashboard) — new in v1.3.0. KPI cards (total orders, revenue, successful/failed counts), a 30-day transaction trend chart, a status breakdown, and a recent-transactions table, all scoped to orders paid through SimplePay. See Developer → Dashboard.
  • Settings (yui-simplepay/settings) — merchant credentials, checkout display, currency/language, and visibility restrictions, now split across five tabs (General, Credentials, Pricing, Restrictions, Test cards). See Settings.
  • License (yui-simplepay/license) — activate, redeem, or revoke the plugin license, and copy the entitlement token. Same license flow used across YUI plugins.

Before v1.3.0 the plugin never set $hasCpSection = true on Plugin.php, so Craft did not list SimplePay in the CP sidebar at all — Settings and License were unreachable through CP navigation, not just the dashboard. v1.3.0 sets hasCpSection = true and adds a dashboard entry to Plugin::getNavItems(), restoring the whole nav section and adding the new Dashboard page.

Beyond the dashboard's own KPIs, there is still no full payments/transactions list in this plugin version — SimplePay is the merchant of record, so the authoritative transaction record is the SimplePay admin (or the sandbox admin while testing), not Craft CP.

How the checkout payment flow works​

  1. The customer selects SimplePay (or the configured Select button name) as their payment method at checkout.
  2. yStore calls the plugin's placeOrder(), which builds a SimplePay "start" transaction from the order (currency, order reference, customer email, total, language, billing address, line items) and starts it via the SDK.
  3. If SimplePay accepts the request, the customer is redirected to the paymentUrl SimplePay returns — SimplePay's hosted card payment page.
  4. SimplePay redirects the customer back to the store's checkout callback URL with signed r/s query parameters. The plugin's postValidate() verifies the signature, reads the notification, and reports the order as paid only when the notification status (e) is SUCCESS.
  5. Any failure — missing/invalid signature, non-SUCCESS status, or an SDK error — is logged through the shared yStore error log (yui-simplepay-plugin:postValidate) instead of surfacing raw SimplePay error payloads to the customer.

Order totals and item prices are stored by yStore in minor units (cents) and are divided by 100 and formatted to two decimal places before being sent to SimplePay.

Requirements​

  • Craft CMS 5 project.
  • yui/craft-core version 1, yui/craft-plugin (yStore) version 2+.
  • A SimplePay merchant account (Merchant ID / MID and Secret Key), available in both the sandbox and live SimplePay admin.
  • Composer access to https://packages.yui.sk/.

Installation​

composer config repositories.yui composer https://packages.yui.sk/
composer require yui/craft-simplepay
php craft plugin/install yui-simplepay

Then open Settings → Plugins → SimplePay → Credentials and enter the SimplePay Merchant ID and API Secret Key (see Settings).

Security notes​

  • The secret key is stored as plain settings data — do not commit it to version control; set it through the CP settings form on each environment instead.
  • Enable SandboxMode talks to SimplePay's sandbox environment and never moves real money; keep it on until a full test payment has been verified.
  • sandboxMode, secretKey, merchantId, selectedLanguage, and defaultCurrency are site-overridable settings — a multi-site install can use different SimplePay credentials, currency, or language per site.
  • The plugin builds per-currency config keys (for example HUF_MERCHANT / HUF_SECRET_KEY) from the single Merchant ID/API Secret Key fields at request time — see Developer → Currency configuration.

Developer / API reference​

See Developer for the Plugin and ApiService methods, the checkout return signature validation, and CP routes.

Frequently asked questions​

Which currencies does this plugin support? The settings form offers CZK, EUR, HUF, and USD as Default currency. Amounts are formatted to two decimal places for all of them; the actual currency SimplePay processes a payment in comes from the order's own currency at checkout time, falling back to Default currency if the order has none set.

Can I restrict SimplePay to specific countries or a date/time window? Yes — the Restrictions tab lets you pick which store countries can see SimplePay at checkout, and set a Visible From / Visible To window.

How do I test a payment before going live? Turn on Enable SandboxMode and use SimplePay's own sandbox test card numbers from the SimplePay developer documentation — this plugin's settings page shows a placeholder generic Visa test card as a starting point; always confirm current test card numbers against SimplePay's own docs before relying on them (see Settings → Test cards).

Where do I see completed SimplePay transactions? In the SimplePay admin (or sandbox admin), not in Craft CP — this plugin version does not keep its own payment/transaction list.