payment-gateway.app Docs
Getting Started

Server integration checklist

Ordered checklist for programmatic checkout and webhooks — hostnames, provider setup, Admin API, and IPN verification.

Server integration checklist

Use this page when wiring a custom backend or reviewing an integration. Official plugins (WooCommerce, aMember) follow the same boundaries; see E‑commerce integrations.

1. Know your hostnames

You need four public roles (often four DNS names). Do not send provider webhooks or checkout runtime traffic to the Admin API host.

RoleCaddy / docs variableBackend container (MPG_*)Hosted example
Admin Panel (browser UI)ADMIN_FRONTEND_DOMAINMPG_ADMIN_FRONTEND_DOMAINdashboard.payment-gateway.app
Admin API (your server → gateway)ADMIN_BACKEND_DOMAINMPG_ADMIN_BACKEND_DOMAINapi.payment-gateway.app
Checkout / customer portal (browser)MAIN_FRONTEND_DOMAINMPG_MAIN_FRONTEND_DOMAINsecure.payment-gateway.app
Main Backend (webhooks + runtime API)MAIN_BACKEND_DOMAINMPG_MAIN_BACKEND_DOMAINwebhook.payment-gateway.app

Self-hosted .env templates set both sides to the same hostname. Integration docs and API examples usually cite the unprefixed *_DOMAIN names; backend containers read the matching MPG_* values.

Full hostname map and self-hosted examples: Hostnames & DNS conventions. Routing details: Caddy reverse proxy.

2. Register provider webhooks on the Main Backend

Stripe, Mollie, GoCardless, PayPal, and similar send events to MAIN_BACKEND_DOMAIN, path /hooks/{type}/{providerId} (no /api/v1 prefix).

  1. Create the provider in the Admin Panel and note the provider id (MongoDB ObjectId in the URL).
  2. In the provider dashboard, set the webhook URL to
    https://<MAIN_BACKEND_DOMAIN>/hooks/stripe/<providerId> (or mollie, gocardless, paypal, etc.).
  3. Save the provider webhook signing secret or verification identifier into the provider record in the Admin Panel where the provider requires one.

Step-by-step: Provider setup. Reference: Webhooks & IPN.

3. Create an Organization API key

  1. Settings → API Keys → create a key with at least checkout:create (and any read scopes you need).
  2. Store the secret once; use Authorization: Bearer sk_... on Admin API requests only.

Never call the Admin API from untrusted browsers; keys are server-side only.

4. Create checkout sessions via the Admin API

  • Host: ADMIN_BACKEND_DOMAIN only.
  • Path: POST /api/v1/checkouts/{siteId}/create on the Admin API host. The default Caddy config also accepts /v1/* as a convenience rewrite, but /api/v1/* is the canonical backend route and generated API reference path.
  • {siteId} is the Site’s MongoDB ObjectId (Sites → Edit).

Site edit screen showing assigned Stripe and wire transfer providers for a storefront site

Response includes paymentUrl on MAIN_FRONTEND_DOMAIN — redirect the customer there.

Details and JSON body: Admin API — Checkouts.

5. Optional — outbound IPN to your server

If you need your own server notified on transaction status:

  1. Copy Webhook Signing Secret from Sites → Edit Site (whsec_...).
  2. Set ipnUrl when creating the checkout (HTTPS in production).
  3. Verify X-Signature-Timestamp and X-Signature-HMAC-SHA256 on each POST — Webhooks & IPN — Outbound IPN.

6. Verify end-to-end

  • Testing & sandbox — test keys, Stripe CLI forwarding to https://<MAIN_BACKEND_DOMAIN>/hooks/stripe/....
  • Quick Start — full UI walkthrough including dashboard checkout creation.

Quick Start — Your First Checkout

From a fresh deployment to a working hosted checkout flow.

Integration Recipes

Practical server-side recipes for checkouts, webhooks, IPN, invoices, and tax reconciliation.

On this page

Server integration checklist1. Know your hostnames2. Register provider webhooks on the Main Backend3. Create an Organization API key4. Create checkout sessions via the Admin API5. Optional — outbound IPN to your server6. Verify end-to-endRelated