Docs

Universal payment platform guide

This platform lets you run one Paystack backend for many websites. Each site keeps its own callback URL, success URL, cancel URL, plans, and allowed frontend origins.

This docs page is public and can be opened without signing in.

How to add a new site

1. Sign in to the dashboard and open `/dashboard/sites/new`.

2. Enter `site_name`, `site_key`, `success_url`, `cancel_url`, and `allowed_origins`.

3. Set `callback_url` to `https://payment.eclipse.name.ng/callback` if you want the central app to verify and then redirect.

4. Save the site and copy the generated `public_api_key` from the site detail page.

5. Create one or more plans in `/dashboard/plans`.

6. If you want another agent or teammate to help with integration, open the site detail page and generate a signed agent access link.

Agent access links

After a site is created, go to that site’s detail page and generate an agent link.

The generated URL is scoped to that one site only and can include the target site URL you want help integrating.

Share that link with another agent or teammate instead of giving them full dashboard access.

The helper can open the link without signing in, read the site’s config, use the snippets, run the integration test, and mark the site as verified.

The link does not expire automatically and does not grant access to other sites.

Frontend integration

Use the site-specific `public_api_key` in the browser when you call the initialize endpoint.

fetch("https://payment.eclipse.name.ng/api/payments/initialize", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-site-public-key": "pk_site_your_site_key"
  },
  body: JSON.stringify({
    email: "customer@example.com",
    amountKobo: 150000,
    planKey: "starter",
    metadata: {
      source: "pricing-page"
    }
  })
});

Paystack setup

Webhook URL: `https://payment.eclipse.name.ng/api/webhooks/paystack`

Do not rely on a single global callback URL in Paystack. The app sends the callback dynamically from each site config during payment initialization.

For the central redirect flow, use `https://payment.eclipse.name.ng/callback` as the site callback URL.

In Vercel, set `PAYSTACK_ENABLED_CURRENCIES` to the currencies that your merchant account is actually enabled for. This prevents customers from seeing Paystack's "merchant does not support currency" error.

Supported currencies

The platform now supports an `ALL` option at the site level for globally distributed users. Plans still use specific currencies, and direct initialization requests are restricted to the current Paystack-supported currencies configured in code and the merchant-level currencies you enable through `PAYSTACK_ENABLED_CURRENCIES`.

ALLNGNUSDGHSZARKESXOF

Verification model

The browser redirect is not final proof of payment.

Trusted payment confirmation comes from the shared Paystack webhook and the optional server-side verify endpoint.

The central `/callback` route verifies the reference and redirects to the site-specific success or cancel URL.

Each site page also includes a self-test button that initializes a real transaction through the deployed platform. Successful tests are recorded in integration history and automatically mark the site as verified.

Open dashboard