Docs / Plugin guide / Magento

This plugin guide should tell you exactly what to verify before Magento routes a live order into Payvra settlement.

The Magento 2 integration is a Composer-installed payment method that redirects shoppers to the Payvra hosted checkout and reconciles order state through signed webhooks. Use this page to prove the installation path, payment-state reconciliation, and the exact switches you flip when the store moves from sandbox to live.

Create free sandbox Review API reference

Treat the extension like any other payment method: install it via Composer, confirm one full sandbox order lifecycle, and only then swap the API key and webhook secret to live values.

What this guide proves

Checkout redirect

Confirm the Payvra payment method appears at checkout, creates a payment via the API, and redirects the shopper into the hosted checkout without breaking the cart or order reference.

Signed callback

Verify the Magento REST callback endpoint receives the signed Payvra webhook and updates the order only after the HMAC signature is accepted.

Refund route

Confirm the credit memo action from the Magento admin maps back to the matching Payvra payment so operators are not forced into manual off-platform refund work.

Operator facts

Runtime model

Composer-installed Magento 2 module inside the store deployment.

Checkout route

Magento checkout -> Payvra hosted checkout -> signed callback to the store.

Store requirement

Magento 2.4+, PHP 8.1+, Composer, and HTTPS on the storefront.

Live promotion

Swap the Payvra API key and webhook secret after the sandbox order path is verified.

Overview

Treat this page as an operator checklist. Each section below maps one part of the plugin path you should verify before you promote checkout traffic to live funds.

Checkout redirect

Confirm the Payvra payment method appears at checkout, creates a payment via the API, and redirects the shopper into the hosted checkout without breaking the cart or order reference.

Signed callback

Verify the Magento REST callback endpoint receives the signed Payvra webhook and updates the order only after the HMAC signature is accepted.

Refund route

Confirm the credit memo action from the Magento admin maps back to the matching Payvra payment so operators are not forced into manual off-platform refund work.

Requirements

Make sure the store, hosting, and account prerequisites are in place before you install the plugin path.

•

Magento 2.4 or later (Open Source or Commerce edition).

•

PHP 8.1 or later.

•

Composer for dependency management.

•

A Payvra account with sandbox credentials.

•

HTTPS enabled on the storefront.

Store listing

The exact distribution surface operators reach for when they install the plugin. The card below mirrors the listing fields shoppers and merchants verify before adopting a payment path.

Magento Marketplace + PackagistMarketplace verified

Payvra. Distributed as a Composer package and Marketplace extension.

Payvra Gateway for Magento 2

Operators install via Composer, which keeps the dependency tracked alongside the rest of the Magento 2 deployment.
The module name registers the gateway under Stores -> Configuration -> Sales -> Payment Methods so it never bypasses the existing payment configuration boundary.
Setup compile and cache flush are run as part of the operator install, which keeps DI containers and front-end blocks coherent before the first checkout.

View on Packagist

Listing facts

Composer package: payvra/magento2-gateway
Magento: 2.4+ (OSS or Commerce)
Requires PHP: 8.1 or later
Module name: Payvra_Gateway
Cost: Free

Setup

Get the plugin or bridge installed first. Then verify that the store can hand checkout traffic to Payvra before you spend time on live credentials.

Install the extension via Composer

Use Composer to install the Payvra payment module so the dependency is tracked alongside the rest of the Magento deployment.

Terminal

1composer require payvra/magento2-gateway
2bin/magento module:enable Payvra_Gateway
3bin/magento setup:upgrade
4bin/magento cache:flush

Verify the module is registered

Run bin/magento module:status and confirm Payvra_Gateway appears in the enabled list. If it does not, check the Composer install output for dependency conflicts.

Confirm the payment method appears in admin

Navigate to Stores → Configuration → Sales → Payment Methods and verify the Payvra section is present. Do this before you wire credentials so the installation issue is separated from payment-mode issues.

Keep the first install in sandbox mode

Use the module to prove the redirect and callback flow before real funds are involved. The production cutover should only change the Payvra secret material, not the installation flow.

Configuration

Keep the runtime settings explicit so operators can tell which key, secret, and settlement target a store is using at a glance.

Enable payment method

Turn on the Payvra payment method only after the module is installed and the store is ready to test a checkout path.

Sandbox mode

Keep this enabled while you rehearse one complete order lifecycle. The goal is to validate store behavior, not just that the settings save correctly.

API key

Start with sk_test_.... Replace it with sk_live_... only after the signed webhook path is stable and the Magento order transitions are correct.

Webhook secret

Store the Payvra signing secret in the Magento admin configuration so operators can rotate it without changing the module code or other store settings.

Settlement currency

Choose the post-payment settlement target the merchant should receive after Payvra processes the payment and any conversion behavior.

Webhook setup

The plugin path is only production-safe once signed delivery is verified and the store can reconcile the final payment state automatically.

Copy the store callback URL

This is the REST endpoint the Payvra module exposes for signed webhook delivery.

Store webhook URL

1https://yourstore.com/rest/V1/payvra/webhook

Add the endpoint in the Payvra dashboard and subscribe to the order-facing events first: payment.confirmed, payment.completed, payment.failed, payment.expired, refund.completed, and refund.failed.

Verify the callback before order mutation logic runs

The module should reject stale or unsigned requests before it changes the Magento order. If the signature is valid, the callback can safely transition the order into the correct payment state.

Platform webhook quirks

Magento 2 ships several caching and ACL layers between the public REST endpoint and the order entity. Each one can swallow a signed webhook if it is not configured for the Payvra route.

Full page cache + Varnish

The Magento REST surface lives under /rest/V1/payvra/webhook. Add an explicit bypass rule to Varnish or any CDN in front of Magento so signed webhook deliveries are never served from cache.

DI compile after install

After composer require and module enable, run setup:di:compile on production-mode stores. Until DI is rebuilt the webhook controller is not autoloaded and Payvra delivery returns 404.

REST ACL

The webhook route is registered as anonymous in etc/webapi.xml. If a custom ACL plugin tightens the REST surface, allowlist the Payvra route or callbacks fail with 401 even when the signature is valid.

Async order grids

If async indexing is enabled, the order grid lags the underlying order entity by a few seconds. Read the order entity directly inside the webhook handler so the paid-state transition does not wait on the grid index.

Testing in sandbox

Run one full rehearsal with test credentials and confirm the checkout handoff, payment confirmation, and order update path end to end.

Payment method visibility

Place a sandbox order and confirm the Payvra payment method appears at checkout and redirects the shopper into hosted checkout.

Lifecycle rehearsal

Watch the sandbox payment progress from pending to confirmed while you compare the Magento order state against the Payvra webhook delivery log.

Order resolution

The Magento order should move to Processing only after the signed event is received and accepted, not before the customer returns to the store.

Promote to live

Only switch the credentials and webhook secret after the sandbox route is boring and repeatable.

Generate a live Payvra key and replace the sandbox sk_test_... value with sk_live_... in the Magento admin configuration.

Create a live webhook for the same callback URL and paste the live whsec_... value into the module settings.

Disable sandbox mode only after the redirect, callback, and order-state path are all stable in rehearsal.

Run one low-risk production order and compare the Magento order comments with the Payvra event log before wider rollout.

Refunds

Confirm the store-side refund action maps back to Payvra before you announce the plugin internally.

Trigger the refund from the Magento credit memo screen so the store and Payvra stay on the same source-of-truth path.

Use the Payvra refund action through the module, not a manual Magento-only refund, so the original payment reference and payout destination remain attached to the order.

Confirm the refund shows up in both Magento order comments and the Payvra dashboard before the issue is handed back to support.

Troubleshooting

Use these checks when the plugin path stalls. Each item points to the fastest place to confirm whether the problem is in storefront setup, Payvra delivery, or the operator config.

Payment method does not appear at checkout

Check that the module is enabled via bin/magento module:status, the payment method is turned on in admin configuration, and the store is running over HTTPS. Also verify setup:upgrade and cache:flush have been run after installation.

Orders stay pending after payment

This usually points to a webhook issue. Compare the Payvra webhook delivery log with the Magento system.log to see whether the callback URL, signing secret, or order mutation failed.

Credit memo cannot find the Payvra payment

Orders created before the module was installed, or payments that were not processed through Payvra, will not have the stored payment reference required for automated refunds.

Module installs but checkout still fails

Re-check the credential mode. A common cause is a live store still using sk_test_... or a stale sandbox webhook secret after the operator believes the store has been promoted.

Ready to validate the Magento gateway?

Prove one sandbox order from checkout redirect to signed callback, then promote the same module to live mode by switching only the Payvra credentials and webhook secret.

Get sandbox keys Back to docs

This plugin guide should tell you exactly what to verify before Magento routes a live order into Payvra settlement.

Treat the extension like any other payment method: install it via Composer, confirm one full sandbox order lifecycle, and only then swap the API key and webhook secret to live values.