Skip to main content
Home

Getting started

A walkthrough from sign-up to your first verified payment, with screenshots and video. Plan on 15–20 minutes.

Overview#

By the end of this guide you'll have a working tenant, a configured payment gateway, working webhooks, and a verified test transaction. Each step has a short video plus inline screenshots.

Video walkthrough coming

Full walkthrough — sign-up to first payment

Full walkthrough video. Drop the YouTube ID into the page once it's published.

Two ways to get started

Try Demo — fastest path. Click Try Demo on the home page, enter a name + email, and you're in. Demos last 24 hours; you can claim them as a permanent account at any time.

Full account — your platform admin creates the tenant for you and emails you a temporary password. You change the password on first login and you're done.

1. Create your account#

From the home page click Try Demo (or Login if your admin has already provisioned you). The demo form takes a name and an email — neither is verified, but the email is what shows on receipts.

Landing page with Try Demo and Login buttons
The home page. Try Demo and Login both lead into the dashboard.
Demo form with name and email fields
Demo form. Submitting drops you straight onto the dashboard.
A demo banner at the top of every authenticated page shows the remaining time. Click Claim this account at any point to set a real password and keep your data past the 24-hour window.
Orange demo banner with countdown and Claim button
Demo banner — countdown updates every 30 seconds, every 5 seconds in the last 5 minutes.

2. Dashboard tour#

The top nav links to the major surfaces: Home, Transactions, Plans, Subscriptions, Customers, plus your account dropdown for API keys and gateway credentials.

Dashboard view showing transactions table and side navigation
Main dashboard. Counts and a recent-activity feed front and center.

Video walkthrough coming

2-minute dashboard tour

2-minute dashboard tour.

3. Configure a gateway#

Go to My Account → Gateway Credentials. Pick a gateway tab (Paystack, Flutterwave, or Hubtel) and paste your secret keys.

Gateway credentials page in 'Not configured' state
Each gateway is independent. 'Not configured' means we'll fall back to the platform's shared keys (if your deployment has any).

Required fields per gateway:

  • Paystack — secret key (required); public key + custom API base URL (optional).
  • Flutterwave — secret key (required) + webhook secret hash (required for webhook verification).
  • Hubtel — API key + API secret.
Paystack credential form filled in
Saved fields display as masked dots; leave a field blank in a future edit to keep the existing value.

Demo accounts

Writing gateway credentials is blocked on demo tenants. Claim your account first (Claim this account in the orange banner).

4. Set up webhooks#

Below the credentials form you'll see your tenant-specific webhook URLs. Copy each and paste it into the corresponding gateway dashboard.

Webhook URLs panel with copy buttons
Webhook URLs panel. Each gateway has its own URL; the host matches whatever you configured in NEXT_PUBLIC_API_URL.

For each gateway, paste the URL into:

  • Paystack — Settings → API Keys & Webhooks → Test/Live Webhook URL
  • Flutterwave — Settings → Webhooks. Also paste the dashboard verif-hash back into the Webhook Secret Hash field on the gateway page.
  • Hubtel — Callback URL field on the merchant dashboard.

Video walkthrough coming

Webhook configuration walkthrough

Webhook configuration walkthrough across all three gateways.

5. Your first payment#

Open the Home (Payment) page. Fill in the customer email, amount, currency, and pick a gateway. Submit to generate a checkout link.

Payment initiation form filled with test values
Payment form. Currency dropdown is populated by the public /currencies endpoint.

On submit, the API creates a pending transaction and returns a redirect URL. The UI shows the link with a Copy button and an Open-in-new-tab shortcut.

Generated payment link with copy and email buttons
Payment link. Send it to the customer or open it directly to test.

Use test cards

When testing on Paystack, use the gateway's documented test cards (e.g. 4084 0840 8408 4081, CVV 408, exp 12/30, OTP 123456). Live cards on a test secret will be rejected by the gateway.

6. Verify a payment#

After the customer pays, the gateway redirects to the callback URL you supplied (the UI uses /payment/callback by default). The callback page reads the reference + provider from the query string and calls GET /api/v1/payments/verify/:reference. The transaction status is updated in the DB at the same time.

Payment callback page showing successful verification
Callback page after a successful payment.

Already-completed payments can also be re-verified from the transactions list using the inline Verify button — useful when a webhook is delayed.

Transactions table with a Verify button on a pending row
Manual verify on the transactions list.

7. Plans & subscriptions#

Plans are recurring payment amounts (e.g. "Pro Monthly — 5,000 NGN / month"). They live both in this API and on the gateway. Today only Paystack and Flutterwave support plan creation; only Paystack supports subscription creation.

Create plan form
Create plan. Provider radio is gated to gateways that actually support plan creation.
Plan detail page with linked gateway codes and edit button
Plan detail. Each linked gateway has its own provider plan code and a delete button.

Once a plan exists with a Paystack provider link, you can subscribe a customer:

Subscription create form with plan picker
Subscription form. Customer email is enough — a Customer row will be created automatically if one doesn't exist.

Video walkthrough coming

Plans & subscriptions end-to-end

Plans & subscriptions end-to-end.

8. Going live#

Before flipping a deployment to production:

  • Replace test secret keys with live keys in each gateway config.
  • Set APP_ENV=production on the API. This enables Gin release mode, hides Swagger by default, and tightens config validation (JWT secret length, CORS, SSL mode).
  • Set explicit origins on CORS_ALLOWED_ORIGINS. * is rejected in production.
  • Set FRONTEND_URL on the API so password-reset links go to your real domain.
  • Set NEXT_PUBLIC_API_URL on the UI to your production API host.
  • Disable SEED_DATABASE. The validator will refuse to start otherwise.
  • Confirm DB_SSLMODE is require or verify-full.
  • Verify the demo cleanup sweeper is running (look for "demo sweep:" log lines).
  • If you've enabled Cloudflare Turnstile (TURNSTILE_SECRET set), wire the widget into the demo form on the UI.
.env.production
APP_ENV=production
JWT_SECRET=long-random-string-32-or-more
SUPER_API_KEY=long-random-string-16-or-more
DB_SSLMODE=require
CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
FRONTEND_URL=https://app.example.com
SEED_DATABASE=false
SWAGGER_ENABLED=false
METRICS_ENABLED=true
ENCRYPTION_KEY=<32-byte hex/base64 — encrypts BYO secrets at rest>
TURNSTILE_SECRET=<from Cloudflare Turnstile dashboard>

Next steps#