Running the platform
Payments
Sellers can pay to publish in paid categories and to promote their listings. Buyers never pay through the site; the mobile apps do not sell anything (they only show the result), so App Store and Google Play rules on in-app purchases do not apply.
What can be sold
| Product | What it does |
|---|---|
| Posting in a paid category | Linked to categories (Categories, edit, Posting fee; subcategories inherit it). A new listing there waits for payment, then goes live or to review. Renewing it is paid the same way. |
| Featured | Shown in a labelled "Promoted listings" row above matching search results (up to 3, rotated) and in the home page slots, for the chosen days. |
| Bump | Moves the listing back to the top of the newest listings. |
| Highlight | A coloured card for the chosen days. |
| Urgent | An "Urgent" badge for the chosen days. |
| Dealer plan | For business accounts: a number of active listings, bumps included in each period and a Dealer badge, for the chosen days (see Dealer plans below). |
Create them in Admin, Payments, Products, with a price in every currency sellers may use and the VAT rate included in the price. Staff can also grant a promotion for free from a listing's page in the admin (Promote); it is recorded in the Audit log.
Payment providers
Turn providers on in Admin, Payments, Payment providers. Their keys stay on the server, in the environment (.env.local or the server's settings), never in the database. Test mode uses the providers' sandboxes.
| Provider | Environment variables | Notification address to register |
|---|---|---|
| Stripe (cards, Apple Pay, Google Pay) | STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET | https://your-site/payments/webhook/stripe, events checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, checkout.session.expired, refund.created, refund.updated, and for renewing dealer plans invoice.paid, customer.subscription.updated, customer.subscription.deleted |
| NETOPIA Payments (cards) | NETOPIA_API_KEY, NETOPIA_POS_SIGNATURE, NETOPIA_PUBLIC_KEY (the PEM from the NETOPIA admin, or that PEM in base64) | Sent with each payment; nothing to register. |
| PayPal | PAYPAL_CLIENT_ID, PAYPAL_SECRET, PAYPAL_WEBHOOK_ID | https://your-site/payments/webhook/paypal, events PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.REFUNDED |
Every notification is verified (Stripe's signature, PayPal's verification call, NETOPIA's signed token), checked against the order's amount and currency, and applied once, however many times it arrives. A payment that does not match is refused and written to the Audit log. The worker (see Backend installation) completes paid orders: it publishes the listing or starts the promotion and emails the receipt with a PDF attached. The PDF shows your company details from Settings, Platform (legal name, registration number, VAT ID, registered address), the buyer, the product, the VAT included and the total; the buyer can download it again from the order page.
Orders and refunds
Admin, Payments, Orders lists every order with its status, provider and amounts, and each payment attempt with what the provider sent. From an order you can refund all or part of it (Stripe and PayPal refund through their API; NETOPIA refunds are made in the NETOPIA admin, and their notification updates the order), send the receipt again, download its PDF, or export all orders to Excel. The admin dashboard shows revenue by product and currency for the chosen period.
Dealer plans
Create plans in Admin, Payments, Products with the type Dealer plan: the period in days (30 for a monthly plan), Active listings (listings published, in review or waiting for payment at the same time), Included bumps per period and the price. A business account picks a plan under Dealer plan in its account.
- Stripe: the plan renews by itself every period until the dealer stops it (from the same page) or it is cancelled in Stripe. Every renewal becomes a paid order with its receipt; refunds work as for other orders. Add
invoice.paid,customer.subscription.updatedandcustomer.subscription.deletedto the Stripe webhook events. - NETOPIA and PayPal: the dealer pays one period at a time; paying again for the same plan adds a period after the current one, and an email reminds them 3 days before the end.
- Choosing a different plan replaces the current one straight away (a renewing Stripe plan is cancelled at Stripe), with its own limits from that day.
- With the active listings in use, a new listing, a renewal or a feed import is refused with a message pointing to a bigger plan. Listings already on the site stay when a plan ends or shrinks; they come off as they expire.
- Dealers on a plan get a Dealer badge on their listings and profile, and a Bump button on their listings while included bumps are left.
- Settings, Listings, Business accounts need a dealer plan: off (the default), business accounts without a plan are not limited, as before; on, they get the same free listing limits per category as private sellers.
Admin, Payments, Dealer plans lists every business's plan, its end date and whether it renews. The daily job app:dealer-plans:check sends the reminders and the "plan ended" emails.
Not included yet
Fiscal invoices and e-Factura and a prepaid wallet are separate steps. The receipt states the VAT included in the price and says it is not a fiscal invoice; invoicing for your country stays with your invoicing provider.
Found a mistake? Tell us.