Core concepts

Topiic models subscription billing with a handful of long-lived entities. Most integration questions reduce to “which of these am I creating/reading/updating right now?”

Merchant

The top-level account. Every other entity belongs to exactly one merchant. Your API key is scoped to one merchant — you cannot read or write data outside it.

If you operate a SaaS that sits in front of multiple Topiic merchants (e.g. a gym class-management tool used by many gyms), each gym mints its own API key from its own Topiic merchant and gives it to you.

Member

A person who subscribes. Holds the contact details (name, email, address, phone) and a link to the matching customer record at the payment gateway.

Members are unique per merchant by email. Creating a member with an email that already exists for that merchant returns the existing row.

Plan

A pricing template. Defines:

• Price charged per billing cycle (decimal).
• Frequency — Daily, Weekly, Fortnightly, Monthly, Quarterly, Yearly, or OneOff.
• Trial days before billing starts.
• Setup fee and cancellation fee (optional).
• Minimum contract months (optional).
• Is active / is public flags.

Plans belong to a Product, which is just a grouping for staff — products carry the brand-facing name/description; plans carry the price + cadence.

Plans are pre-configured in the Topiic portal by the merchant. Integrations reference them by id — they never create plans on the fly.

Subscription

A member’s enrolment in a plan. Created when checkout completes. Carries:

• The current Status (Trial, Active, PastDue, Paused, Cancelled).
• StartDate, TrialEndsAt, NextBillingDate.
• The PaymentMethodId to debit each cycle.
• The matching gateway subscription id.

A member can hold multiple subscriptions (e.g. a gym membership + an unlimited-classes add-on).

Payment method

A tokenised card or bank account. Topiic stores only the gateway token plus display-safe metadata (brand, last 4, expiry) — never the PAN.

For hosted-checkout flows, the payment method is created by the hosted form during checkout. For direct API flows, your server calls the add-payment-method endpoint which forwards to the gateway. Direct flows put you in PCI scope — prefer hosted checkout.

API key

The credential your integration uses to talk to Topiic. Two pieces:

• The API key (tpk_…) goes in the Authorization: Bearer … header on REST calls.
• The signing secret (tss_…) is the HMAC key used to sign hosted-checkout deep links and verify incoming webhook signatures.

Both are shown exactly once at creation. Topiic stores a hash of the API key and the plaintext signing secret. Revoking an API key invalidates both immediately.

Each key has its own webhook configuration (endpoint URL + subscribed event types + enabled flag), so you can route different integrations to different receivers.

Checkout session

A short-lived (≤30 min) row created when a signed deep link resolves. Tracks the user through contact-confirmation, card capture, and provisioning. On success it pins the created member, payment method, and subscription ids.

You don’t usually interact with checkout sessions directly — Topiic owns the UI for the full session and emits a webhook on completion.

Webhook event + delivery

Events are immutable records of “something interesting happened” (e.g. checkout.completed). Each event has one or more delivery attempts that POST the payload to the configured URL and capture the receiver’s response. Failed deliveries chain a fresh attempt on backoff — see Retries & replay.

How they fit together

flowchart TD
    M[Merchant]
    K[ApiKey<br/><i>your integration</i>]
    WE[WebhookEvent]
    WD[WebhookDelivery]
    URL[Your URL]
    Mem[Member]
    PM[PaymentMethod<br/><i>tokenised card</i>]
    Sub[Subscription]
    P[Plan]
    Pr[Product]
    CS[CheckoutSession<br/><i>transient</i>]

    M --> K
    K --> WE
    WE --> WD
    WD --> URL
    M --> Mem
    Mem --> PM
    Mem --> Sub
    Sub --> P
    P --> Pr
    M --> CS
    CS -. on success .-> Mem
    CS -. on success .-> PM
    CS -. on success .-> Sub

Tip

Whenever you’re touching a member, payment method, or subscription, you should already know the merchant id — it lives on every entity and your API key won’t grant access across merchants.