Paid listings

Paid listings takes payment for what a site sells its partners: a membership tier for a period, and promotions in its priced slots. A partner pays in the portal through the provider’s hosted checkout (Stripe Checkout is the one provider), or staff raise an invoice and record its payment. Either way the result is an order, and a paid order is fulfilled: a tier order makes the organisation’s membership active at that tier until the end of the period it bought, and a promotion order approves the promotion. A refund takes it back, and a tier order’s membership lapses when its period ends.

Without config/paidlistings.yaml, or with provider: none, nothing is sold in the portal; staff can still raise invoices for priced promotions.

ConfigurationCopy Anchor Link

provider: stripe
stripe:
  secret_key: ${STRIPE_SECRET_KEY}
  webhook_secret: ${STRIPE_WEBHOOK_SECRET}
sites:
  main:
    promotions: checkout
    tiers:
      standard: { amount: "120.00", currency: GBP, months: 12 }
      gold: { amount: "300.00", months: 12 }

A tier on sale must be declared in config/memberships.yaml and sold on the site (memberships.tiers in site.yaml). A promotion’s price comes from its slot in promotions.yaml (see Promotions), never from this file.

engine-dmo check validates the file without needing the secrets; the server reads the two variables at start and refuses to start when either is unset. A key beginning sk_live_ or rk_live_ is live mode; any other is test mode.

Setting up StripeCopy Anchor Link

The engine creates one Checkout Session in payment mode per order, for one line at the order’s amount, naming the order as the client reference and in the payment’s metadata. It never sees card details.

The webhookCopy Anchor Link

POST /paidlistings/webhook/stripe checks the Stripe-Signature header and its age (at most 5 minutes) before reading the body, refuses an event it has already applied (event ids are kept 90 days), holds a payment’s amount to the order’s, and then fulfils the order. A delivery that fails its signature counts against its address’s allowance and is answered 429 past it; one that verifies is never limited.

The billing screenCopy Anchor Link

The portal’s billing screen, {portal path}/billing/{org}, is for people whose partner role grants billing.pay (the built-in billing and owner roles). It shows:

• the organisation’s membership on the site;
• with a provider, each tier on sale with its price and period;
• on a site with promotions: checkout, its promotion requests waiting for payment, priced from their slot;
• its orders and their statuses.

Each offer is a plain form that posts to {portal path}/billing/{org}/checkout, which records the order at the price in configuration (the form only names the offer) and answers 303 to the provider’s checkout page. It works without JavaScript. The screen renders the portal template billing.html, which engine-dmo portal scaffold --site <site> copies for restyling.

A promotion request on a checkout site is requested until the partner starts checkout, then awaiting_payment while its order is open; payment approves it, with the slot’s capacity checked again. If the order is cancelled or abandoned, the promotion goes back to requested.

OrdersCopy Anchor Link

stateDiagram-v2
  [*] --> open : checkout started or invoice raised
  open --> paid : payment received
  open --> cancelled : abandoned or cancelled
  cancelled --> paid : a late payment
  paid --> fulfilled : tier or promotion granted
  paid --> failed : fulfilment could not go ahead
  paid --> refunded
  failed --> fulfilled : staff retry
  failed --> refunded
  fulfilled --> lapsed : a tier order's period ends
  fulfilled --> refunded
  lapsed --> refunded
  refunded --> [*]

What fulfilment doesCopy Anchor Link

Paid orders whose fulfilment was interrupted are retried every minute; ended periods are lapsed every hour, by the site’s timezone.

StaffCopy Anchor Link

Staff with paidlistings.manage on the site (the built-in administrator and partnership-manager roles) use the Orders screen under Members to:

• raise an invoice for a tier on sale or for a promotion waiting for payment;
• record an invoice’s payment, which fulfils it;
• cancel an open order;
• retry a failed fulfilment;
• record a refund made in Stripe or in the finance system.

TroubleshootingCopy Anchor Link