← All Integration Guides
STORE PLUGIN · ON-SITE + HPPAccept Crypto Payments with Sylius 2.0
Native Payum checkout and the Sylius payment state machine.
New adapters are initial integration builds. Complete installation and real-payment acceptance in your own staging store before enabling live traffic.
Choose the correct package and PHP environment
| Shopping platform | PHP environment for this package |
|---|
| Sylius >=2.0.0 <2.1.0 with PayumBundle 2.6+ / Payum 1.7-compatible core | PHP 8.2.x / 8.3.x / 8.4.x (also satisfy the store dependency lock) |
|---|
Use the PHP version permitted by both this package and your exact core release. A plugin does not make an older store core compatible with newer PHP.
New packages use optional request_id deduplication and require MochiPay Web65 or later. Existing customers can keep their current plugins and API integrations.
01 · Prepare your MochiPay account
- Create an account · activate a subscription.
- Wallets · Enable a receiving wallet for every asset/network you will offer. Back up recovery material before checkout.
- API Credentials · Keep the merchant API key and secret on the server. Never put credentials into checkout HTML or browser scripts.
02 · Install and enable the native gateway
- Extract MochiPaySylius into plugins/MochiPaySylius. Add a local Composer path repository and run composer require mochipay/sylius-plugin:1.0.0.
- Register MochiPay\Sylius\MochiPayBundle in config/bundles.php, and import its routes as described in README.md inside the ZIP.
- Run bin/console cache:clear and bin/console mochipay:install. Existing payment attempts are retained.
- Create a native payment method with the MochiPay gateway factory. Enter credentials, enable MochiPay and the native method, and assign channels.
- Use the Sylius 2.0 Payum checkout. MySQL/MariaDB and PostgreSQL are supported; Sylius 1.x and 2.1+ require different adapters.
The English README inside each ZIP includes the exact paths, native configuration, dependencies and upgrade notes. Follow it for your platform.
04 · ON_SITE and HPP use the same payment
ON_SITEPayment dialog in your store
The default ON_SITE dialog shows the exact amount, address, network, QR and payment status on your store domain.
HPPMochiPay hosted payment page
HPP opens the MochiPay payment_url and returns to your store after checkout. Select HPP in the same gateway settings.
Reopening checkout or switching presentation reuses the saved payment order. No payment_mode parameter is added to the MochiPay API.
Try the public ON_SITE/HPP simulation →
05 · Verify a staging order before going live
- Place a small staging order. Confirm the fiat total, selected asset, network and exact crypto amount before sending payment.
- Verify that the server queries MochiPay and records the native paid state only after a matched PAID result. A return URL or callback body alone is not payment proof.
- Test HPP, ON_SITE, reopening checkout and repeated notifications. Confirm that the same order is reused and payment completion is applied once.
These downloads have source/interface checks and simulated checkout validation. Full native-store installation and real paid checkout still require staging acceptance.
Understand server-side payment verification →
Troubleshooting and downloads
If the gateway is missing, check the exact store branch, PHP, cache, native method activation and channel restrictions. If an order remains pending, check credentials, active subscription, wallets and public callback reachability. Keep existing payment attempts when updating.