Pre-Built Integrations

Magento 2 Integration — Installation & Setup Guide

Install and configure the Paypercut payment module (Paypercut_Payment) on a Magento 2 store. This module adds card, Buy Now Pay Later (BNPL), and saved-card (Vault) payment methods alongside your existing checkout. All methods use a redirect to a Paypercut-hosted payment page — no raw card data touches Magento.

This is a developer setup: you need SSH/CLI access to the Magento host and Magento admin access.

Requirements

  • Magento 2.4.x (Open Source / Commerce). Magento 2.3 and earlier are not supported.
  • PHP 8.4+ — composer.json requires >=8.4.0; the module will not install on earlier PHP.
  • A Paypercut merchant account and credentials from your Paypercut Merchant Dashboard:
    • Secret Key (card) — sandbox for testing, production for live.
    • Webhook Secret (card) — for verifying webhook authenticity. Set on the card method only; BNPL has no webhook secret.
    • BNPL Secret Key — only if you enable BNPL.
  • Ability to run bin/magento and flush caches on the store.
  • For BNPL: Magento cron must be running. The paypercut_bnpl_status_check job (every 5 minutes) reconciles BNPL orders — but only those created within the last 48 hours.

Step 1 — Install the module

There are two ways to install the module. Both finish with the same bin/magento enable/build sequence.

Option A — Adobe Commerce Marketplace (Composer)

  1. Open the listing — Paypercut Payments on the Adobe Commerce Marketplace — and add the extension to your Adobe Commerce account (use the listing's Install / Buy now flow).
  2. Ensure your Magento Access Keys (Marketplace → My Profile → Access Keys) are set in <magento-root>/auth.json for repo.magento.com.
  3. Require and build:
composer require paypercut/module-payment
bin/magento module:enable Paypercut_Payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Option B — GitHub Release ZIP (manual)

  1. Download the latest release from github.com/paypercut-oss/plugin-magento2/releases.
  2. Unzip it into app/code/Paypercut/Payment on your Magento host.
  3. Build:
bin/magento module:enable Paypercut_Payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Either way, confirm the module is enabled:

bin/magento module:status Paypercut_Payment

Production mode: if the store runs in production mode, also deploy the module's static assets with bin/magento setup:static-content:deploy -f (the payment renderers/templates will 404 without it), and consider wrapping the upgrade in bin/magento maintenance:enable / maintenance:disable.

Supported checkouts

The module ships payment renderers for standard Luma checkout and standard Hyvä checkout (Alpine.js) — card and BNPL work on these out of the box. If your store uses Hyvä ReactCheckout (Zento), the Paypercut methods are not rendered automatically: you must add paypercut_card, paypercut_bnpl, and paypercut_vault cases to that checkout's GraphQL resolver (Zento\Payment\Model\Resolver\PaymentForm::getPaymentObject()) and register them in its React renderer map, or the methods will not appear or redirect. See the plugin README's "Checkout Integrations" section.

Step 2 — Configure payment methods

In the Magento Admin, go to Stores → Configuration → Sales → Payment Methods. The module adds three fieldsets within Payment Methods (there is no custom top-level tab):

  • Paypercut Payment (card) — config path payment/paypercut_card/*
  • Paypercut BNPL (Pay in installments) — config path payment/paypercut_bnpl/*
  • Paypercut Subscriptions (Recurring Payments) — config path payment/paypercut_subscription/*

Each method has its own Enabled (Yes/No) toggle — there is no single master switch. Defaults out of the box: card and BNPL are enabled; saved cards (Vault) and subscriptions are disabled.

Paypercut Payment (card)

In the API Credentials group:

  • Environment — Sandbox or Production. Default Sandbox. This is the only test/live switch; there is no separate "Test mode" checkbox. Use your sandbox Secret Key with Sandbox and your production Secret Key with Production.
  • Secret Key — your Paypercut card Secret Key.
  • Webhook Secret — used to verify inbound webhook signatures (HMAC-SHA256). Stored encrypted. Strongly recommended (see Step 4).
  • Debug Mode — Yes/No.

Other groups for the card method:

  • General Settings — Title, Description, Sort Order.
  • Order Settings — New Order Status; Payment Action (Authorize and Capture (default) or Authorize Only); Refund Action (Refund on Credit Memo, Credit Memo on Refund, or None (default)). With the default None, a refund issued in the Paypercut dashboard is not mirrored as a Magento credit memo — choose Credit Memo on Refund if you want the IPN to auto-create one.
  • Saved Cards (Vault) — Enable Saved Cards (Yes/No, default No; writes payment/paypercut_vault/active). Enables tokenized saved cards for returning customers and automatically-charged subscriptions. The saved-card method is surfaced as a checkout renderer only on the React/Zento checkout, not on stock Luma.
  • Country Settings — Payment From Applicable Countries / Specific Countries.

There is no API Key, Store ID, Merchant Number, RSA Private Key, Public Certificate, or Key Index field — the card method authenticates with the Secret Key only.

Paypercut BNPL

  • General Settings — Enabled, Title, BNPL Secret Key (separate from the card Secret Key), Sort Order.
  • Order Limits — Minimum Order Total (default 100), Maximum Order Total (default 10000).
  • Installment Options — Available Installments (comma-separated, default 3,6,12), Show Installment Preview (default Yes).
  • Country Settings — applicable / specific countries.

BNPL default Payment Action is Authorize Only. BNPL is not available for admin-created orders.

Paypercut Subscriptions

Subscription support is disabled by default. Automatically-charged subscriptions use a stored card via the Vault (Saved Cards) method; subscriptions placed without a stored card fall back to invoice-based collection (Vault is not strictly required). Recurring billing is delegated to the Paypercut subscription API — Magento does not generate renewal orders — and subscription creation depends on the card IPN firing (a valid Webhook Secret). Key fields:

  • General — Enabled, Subscription Label, Description.
  • Billing — Default Billing Interval (Daily / Weekly / Monthly (default) / Yearly), Billing Interval Count, Billing Day of Month (1–28), Collection Method (Charge Automatically (default) or Send Invoice).
  • Trial — Enable Trial Period, Trial Period Days, Missing Payment Behavior (Cancel Subscription (default), Pause Subscription, or Create Invoice).
  • Cancellation — Cancel at Period End, Allow Customer Cancellation, Allow Customer Pause.
  • Notifications — Renewal Reminder Days, Failed Payment Notification.

Subscription products are configured per product via the EAV attributes added under the Paypercut Subscriptions attribute group (e.g. paypercut_subscription_enabled, interval, interval count, price override, and max billing cycles).

Click Save Config and flush the cache (bin/magento cache:flush) after changing settings.

Step 3 — Test in sandbox

Set Environment to Sandbox and enter your sandbox Secret Key, then run a full storefront test order:

  1. Add a product to the cart and select Paypercut at checkout.
  2. You are redirected to the Paypercut-hosted payment page. Complete payment with a Paypercut test card — see Testing → Test Cards, e.g. 4000 0200 0000 0000 for a successful authentication. Never use real card data in sandbox.
  3. Confirm the return: a successful payment lands on the order success page; cancelling returns you to the cart with the order cancelled and the quote restored.
  4. Confirm the order appears under Sales → Orders and that its status advanced. For card, the IPN moves the order to processing / invoiced. For BNPL, status advances when the shopper returns to the success page or on the next cron run (every 5 minutes) — BNPL does not use the card IPN, so make sure Magento cron is running before testing it. If a card order's status doesn't update, check webhooks (Step 4).

When ready to go live, switch Environment to Production, replace the Secret Key (and BNPL Secret Key) with your production keys, save, and flush the cache.

Step 4 — Configure webhooks

The module exposes a card IPN endpoint and a BNPL callback endpoint under the paypercut frontName:

Purpose URL
Card IPN / webhook https://your-store.com/paypercut/payment/ipn
BNPL status callback https://your-store.com/paypercut/payment/bnplcallback
  1. In your Paypercut Merchant Dashboard, configure the IPN endpoint https://your-store.com/paypercut/payment/ipn.
  2. Set the matching Webhook Secret in the Paypercut Payment section in Magento admin.

The IPN handler verifies the Paypercut-Signature header — format t=<timestamp>,v1=<hmac> — as HMAC-SHA256 over <timestamp>.<body>, with a 5-minute replay tolerance, using the card method's Webhook Secret (BNPL has no webhook secret). The endpoint must accept unauthenticated POSTs from Paypercut: remove any HTTP Basic Auth, IP allowlist, or WAF rule on /paypercut/payment/ipn, and keep the server clock in sync — a skew over 5 minutes fails verification.

Configure the Webhook Secret. If it is left empty, signature validation is skipped and the endpoint accepts unsigned requests. Always set it in production.

The card IPN drives capture/invoicing, order cancellation on failure, refunds, and subscription creation. BNPL does not use the card IPN: BNPL orders are reconciled by a cron job (paypercut_bnpl_status_check, every 5 minutes) that polls pending BNPL orders, with the bnplcallback endpoint as an optional push trigger. Ensure Magento cron is running (bin/magento cron:run / system crontab) for BNPL.

Payment methods

The module exposes exactly three methods at checkout, all redirect-based:

  • Card (paypercut_card) — standard card payment; supports authorize/capture, void, and full/partial refund.
  • BNPL / Pay in installments (paypercut_bnpl) — installment payments via the Paypercut BNPL API.
  • Saved Cards / Vault (paypercut_vault) — tokenized saved cards; disabled by default; used for automatically-charged subscriptions (which can otherwise fall back to invoice-based collection). Surfaced as a checkout renderer only on the React/Zento checkout.

There are no wallet methods (Apple Pay / Google Pay) in this module.

Troubleshooting

  • Method not visible at checkout — confirm the method's Enabled toggle is Yes, the correct Secret Key and Environment are set, and you ran setup:upgrade + cache:flush. Check Country Settings if you restricted countries.
  • Webhooks not processed — confirm the IPN URL is correct and reachable over HTTPS with no HTTP Basic Auth, IP allowlist, or WAF rule blocking it; that the server clock is within 5 minutes of real time; and that the Webhook Secret in Magento matches the one in the Paypercut dashboard.
  • BNPL orders stuck pending — confirm Magento cron is running; the BNPL status-check job runs every 5 minutes and only covers orders from the last 48 hours.
  • Payment method JS/templates 404 (production mode) — run bin/magento setup:static-content:deploy -f.
  • Changes not taking effect — run bin/magento setup:di:compile (after install) and bin/magento cache:flush.

FAQ

Q: What credentials do I need? A: A Secret Key (card) and a Webhook Secret for verifying webhooks. BNPL uses its own BNPL Secret Key. There are no Store IDs, Key Indexes, or RSA keys.

Q: Are the credentials created in Magento? A: No — copy your Secret Key and Webhook Secret from your Paypercut Merchant Dashboard.

Q: Will installing Paypercut affect my existing checkout? A: No — the module installs as additional payment options and does not replace your current checkout.

Further help

Previous
MerchantPro
Next
Getting started