Help center

Online dues collection with Paystack

Let residents pay their monthly dues online. Money settles directly to your HOA's own bank account — HOAPortal never touches the funds.

How it works

You sign up for a free Paystack account in your HOA's name, paste the account's secret key into /admin/settings → Online dues payments (Paystack), and residents immediately see a “Pay online” button on their /pay page.

When a resident clicks it:

  1. They're redirected to Paystack's secure checkout.
  2. They pay with a card, Mobile Money (MTN, Vodafone, AirtelTigo), or instant bank transfer.
  3. They're redirected back to HOAPortal. Their payment is auto-approved and auto-allocated to their oldest unpaid month(s) — same allocation logic as any other payment.
  4. Money settles to your HOA's bank account. Paystack's standard timing is T+1 business day for Ghana card + MoMo transactions.

You never manually approve online payments — Paystack's verification already confirmed the money moved. Manual verification (upload evidence) is still there for offline payments (cash, direct bank transfer, older MoMo receipts).

Setup — step by step

1. Create a Paystack Ghana account

Go to paystack.com/gh. Sign up using an email you control — usually the treasurer's or the HOA's official email. You'll need:

  • The HOA's registered name (or the executive's name if unregistered).
  • A phone number.
  • The HOA's bank account details (or the account you want funds settled to).

No monthly fee. Paystack charges 1.95% per successful transaction — capped at GHS 100 per transaction. Failed transactions are free.

2. Complete KYC

Upload identification documents so Paystack can move you to live mode. What they need depends on how the HOA is set up:

  • Registered HOA (Ltd by guarantee, sole proprietorship, etc.)— Certificate of Incorporation, TIN, plus the director's Ghana Card.
  • Unregistered HOA— the treasurer's Ghana Card and a personal bank account in their name. This is fine for smaller communities but the account holder is on the hook if there's ever a chargeback.

KYC usually clears within 24 hours. Until it clears you're in test mode — real cards will be declined.

3. Grab your secret key

Log in to your Paystack dashboard. Toggle the switch in the top-right from Test to Live(you'll want the live key so real payments work).

Go to Settings → API Keys & Webhooks. You'll see two keys:

  • Public key (pk_live_…) — safe to expose; optional.
  • Secret key (sk_live_…) — sensitive, NEVER share it. This is the one HOAPortal needs.

Copy the secret key.

4. Paste into HOAPortal

Go to /admin/settings, scroll to Online dues payments (Paystack). Check “Accept online dues payments via Paystack”. Paste the secret key. Save.

Click Test connection. You should see:

✓ Connected in live mode. Available balance: GHS 0.00.

If you see an error, the key is wrong or Paystack's API is unreachable — the error message will tell you which.

5. Tell your residents

Send an announcement (from /admin/notices) letting them know they can now pay online at their /pay page. Include a note that receipts land in their email inbox automatically.

Test vs live mode

Paystack keys are mode-scoped: sk_test_… works only with test cards, sk_live_… works with real money.

Before going live, you can validate everything with a sk_test_… key + Paystack's test cards. Success card is 4084 0840 8408 4081, any future expiry, any 3-digit CVV.

HOAPortal figures out the mode from the key's prefix — no separate toggle to keep in sync.

What if a payment fails?

Paystack transactions have three states: success, failed, abandoned. Only successful ones are recorded in HOAPortal.

  • If a resident's card is declined at Paystack's checkout, nothing is charged, no record is created. They can retry immediately.
  • If they abandon the checkout (close the tab), same thing — no charge, no record.
  • If the payment actually went through but the redirect back to HOAPortal was interrupted (network drop), the money is with Paystack but not yet in the resident's statement. Wait an hour — the redirect usually completes, or Paystack's webhook fires. If not, the resident can still upload the receipt to their /pay page and you approve it manually. Paystack also shows the transaction in your dashboard.

Refunds and disputes

Refunds are handled inside the Paystack dashboard, not HOAPortal — there's no button in HOAPortal for “refund a Paystack-paid dues payment” yet. Process:

  1. Refund on the Paystack dashboard (Transactions → find it → Refund).
  2. Delete the corresponding payment in /admin/payments— this rolls back the allocation so the resident's statement matches reality.

Chargebacks (customer disputes with their card issuer) are rare for HOA dues but you'll be notified by Paystack email. Same cleanup: refund is automatic once you accept the dispute; delete the payment on your side.

Security notes

  • Your secret key is encrypted at rest inside HOAPortal — the DB alone can't recover it without the platform master key.
  • HOAPortal never sees the resident's card details. Paystack handles PCI compliance end-to-end.
  • The “Pay online” button uses a per-transaction reference tied to both the tenant and the resident — one HOA can't verify another HOA's payments.
  • Rotate the secret key any time by generating a new one on Paystack and re-saving on the settings page. No redeploy needed.

Common problems

“Invalid key” on Test connection

You've pasted the public key instead of the secret key. Secret key starts with sk_, public starts with pk_. Both are in the same Paystack dashboard section.

Real cards are declined but test cards work

Your KYC hasn't cleared yet, so Paystack is holding you in test mode. Check Paystack dashboard → Compliance for outstanding items.

Resident says they paid but nothing appears in HOAPortal

Two possibilities:

  • The redirect back was interrupted. Ask them to visit their /paypage — the return handler runs on any visit within the same session. If that doesn't work, verify on the Paystack dashboard and record manually.
  • They paid on a different HOA's subdomain by mistake (rare, but it happens on shared-family accounts). The reference belongs to that tenant, not yours.

Money isn't hitting my bank account

Paystack settles T+1 business day by default. Check Paystack dashboard → Settlements. If it's stuck (usually a bank-account-verification issue on Paystack's side), their support at [email protected] resolves within a business day.

Need a hand? Email us — or check the FAQ for quick answers.