Payments, invoices and coupons

With the shop licensed, customers can pay by card (Stripe) or PayPal. Customers pay on the gateway’s own page, NexoVirt never sees card data, and every confirmed payment is first booked to the customer’s balance. This page covers the gateways, the billing modes, the payments list, invoices with VAT and coupons.

Note

Gateways work for the customers of your own shop. Customers of a reseller pay their reseller outside the panel (balance top-ups over the reseller API).

Payment gateways

Open Shop settings > Payment gateways. There is one tab each for Stripe and PayPal, with an On or Off badge. Several gateways can be on at once; the customer picks one at checkout. A gateway that is switched on without all its keys (Stripe: Secret key and Webhook signing secret; PayPal: Client ID, Client secret and Webhook ID) shows Incomplete and a warning that names what is missing. Customers get no Top up or checkout for it until it is complete.

1. Switch the gateway on (Accept card payments with Stripe or Accept PayPal payments) and enter the keys.
2. Add the Webhook URL shown on the tab at the gateway, with the listed events. The panel only trusts events it can verify.
3. Click Test connection, then save with Save Stripe or Save PayPal.

Gateway	Fields	Webhook URL
Stripe	Secret key (sk_live_..., or sk_test_... for Stripe’s test mode), Publishable key, Webhook signing secret (whsec_...)	https://your-panel/webhooks/payments/stripe
PayPal	Mode (Sandbox (testing) or Live), Client ID, Client secret, Webhook ID	https://your-panel/webhooks/payments/paypal

Secrets are write-only: the form only says “Stored. Leave empty to keep it.” Saving needs the step-up confirmation.

• Stripe webhook events: checkout.session.completed, checkout.session.async_payment_succeeded, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted, charge.refunded, charge.dispute.closed. Add the endpoint in Stripe under Developers > Webhooks.
• PayPal webhook events: CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.SALE.COMPLETED, PAYMENT.SALE.REFUNDED, BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.SUSPENDED, BILLING.SUBSCRIPTION.EXPIRED, BILLING.SUBSCRIPTION.PAYMENT.FAILED. Add the webhook in your PayPal app (Developer Dashboard > Apps & Credentials) and copy its Webhook ID into the panel.
• Sync plans creates or updates the gateway product for every shop product at once. Without it, each product gets its own gateway product on its first checkout.
• Test with a Stripe test key or PayPal sandbox mode. Buy with a separate personal sandbox account, not the business account.

Unprocessed webhook events are retried by the command php spark payments:sweep --once (cron, every 5 minutes). It also re-reads checkouts that stayed open for more than 2 minutes and expires them after 24 hours. A checkout whose payment the gateway is still processing (for example a SEPA direct debit or a payment under review) stays open for up to 14 days, so the order is not lost. Re-run deploy/install-cron.sh after updating to get this cron entry, see CLI & daemons.

Billing modes

How customers pay is set as the default under Shop settings > General and can be overridden on each product (Price and periods):

Mode	What happens
From their balance (prepaid)	The customer tops up the balance (card, PayPal, your billing system or a manual booking) and orders and renewals are paid from it.
Automatic card / PayPal payment	The order starts a subscription at the gateway. The gateway charges every period and the paid date follows the gateway. No balance renewals.
Customer chooses	The order page offers both under Payment.

A product with a setup fee is always ordered prepaid (from the balance or a one-time card or PayPal payment); the customer can switch the server to automatic payment afterwards. The invoice lists the fee as its own line Setup fee.

Rules for subscriptions:

• Periods of 1, 3, 6 or 12 months only. Running subscriptions keep their price when you change the product.
• A subscription server is suspended 24 hours after its expiry if the payment did not arrive. Renew now is not offered.
• PayPal subscriptions do not allow plan changes or extras (the customer cancels and orders again, or pays by card).
• Every confirmed payment is booked as a top-up first, then the order, upgrade or extra is paid from the balance. An order is never created twice for one payment.

Payments list and refunds

Sales > Payments lists every card and PayPal payment with Date, Customer, Gateway, Type, Amount, Status, Refunded and Payment ID, with filters for gateway and status (succeeded, refunded, disputed) and Export CSV. A customer’s own payments are also in the Billing section of the customer page.

Refunds and lost disputes arrive by webhook. The refunded amount is taken back from the customer’s balance as a negative adjustment (never more than the payment) and you get a notice in the panel inbox (payment_issue). Refund money at the gateway; the panel follows.

Customers see Top up on their Balance page (amount, then Pay with card or Pay with PayPal). Without a complete gateway, the page says “To add credit, contact your provider.”

The amount must be within Minimum top-up and Maximum top-up (Settings > Shop); the form shows the minimum and starts with it filled in. These limits apply only to customer top-ups. A checkout for an order, a plan change or an extra pays exactly what it costs, even below the minimum. Credits and debits you book on the customer page, and bookings by your billing system over the API, are never limited.

Invoices and VAT

NexoVirt can create an invoice for every payment. Open Shop settings > Invoice settings.

Invoice settings

Setting	Meaning
Create an invoice for every payment	The master switch. Card and PayPal payments get an invoice, refunds and lost disputes a credit note, and top-ups you book by hand when you tick Create an invoice (for a credit only, e.g. a bank transfer).
Language	English or German invoices.
Number prefix and Next number	Numbers look like PREFIX2026-00001, without gaps. Next number can only go up, for example to continue old numbering.
Your company	Company name, Email, Address, Bank details, Country, VAT ID (must match the country’s format), Tax number and Footer.
VAT	Show VAT or No VAT on invoices, Your VAT rate, and the switches below.

The VAT switches:

• Small business (no VAT): for example § 19 UStG in Germany. Invoices show no VAT and a note.
• One-stop shop (OSS): consumers in other EU countries pay their country’s rate. Needed once your sales to EU consumers abroad pass 10,000 EUR a year. The EU rates are built in; check them once a year.
• EU businesses with reverse charge pay the net price: see Net price for EU businesses.

Which VAT an invoice shows

The amounts customers pay include VAT. The invoice shows the net amount and the VAT it contains.

Customer	VAT
In your country	Your rate (Domestic).
EU business abroad with a VAT ID the EU confirmed	Reverse charge, 0 %.
EU consumer abroad	Your rate, or their country’s rate with OSS on.
Outside the EU	0 % (Outside the EU).
You are a small business	No VAT.

The customer’s name, address, country and VAT ID come from their profile at the moment of the payment (customers enter them on Account settings > Billing details). A VAT ID is checked with the EU’s VIES service: the customer sees “Confirmed by the EU (VIES)” or that VAT is charged until it is confirmed. Reverse charge needs a confirmed VAT ID. Invoices are never changed afterwards.

Caution

NexoVirt helps with the paperwork but is not tax advice. Check the setup with your tax adviser.

The invoice list

Sales > Invoices shows one month at a time (arrows for the previous and next month) with the net, VAT and total sums. Each row has Number, Date, Customer, Description, VAT (rate and type), Net and Total, and a PDF button. Credit notes carry a Credit note badge. CSV exports the month and All PDFs (ZIP) downloads every PDF of it. Exports and settings are audited. Customers download their own invoices as PDF under Balance > Invoices.

Net price for EU businesses

Shop prices include VAT. With EU businesses with reverse charge pay the net price on, a customer in another EU country whose VAT ID the EU confirmed is credited with your VAT rate on top of every one-time card or PayPal payment, so your listed price costs them the net amount. The invoice shows what was paid at 0 %. Customers outside the EU are not changed, because their country is only self-declared. Automatic recurring payments keep the listed price.

Coupons

Catalog > Coupons lists the codes with Code, Discount, Products, Used, Valid until and Switch off / Switch on. A used coupon shows Used: cannot be deleted instead of Delete: it keeps its record for the orders, so switch it off to stop further use. New coupon has:

Field	Meaning
Code	3 to 32 letters, digits, _ or -, for example WELCOME20.
Discount	A number with % or your currency: percent or a fixed amount off.
How often it can be used	In total; empty is no limit. Every customer can use a code once.
Last day	The code works until the end of this day.
Products	Tick products to limit the code; none ticked means every product in every billing period.
Note	For you only.

A coupon takes the discount off the first payment of a new order (product and add-ons). Renewals cost the full price. Customers enter the code on the order page (Coupon code, Apply) and see the discounted total. Each customer can try at most 20 codes per hour. Coupons work for orders paid from the balance (also when topped up by card or PayPal at checkout), not for automatic recurring payments, and not in reseller shops.

Next steps

• Shop and customer balance for products, renewals and cancellation.
• Legal texts and order consent for terms and the withdrawal waiver.
• Storefront and WordPress plugin to sell from your own website.