Paystack integration: activating, webhooks, and reconciliation

How the Paystack integration works

School Vault connects to Paystack via its REST API and webhook system:

• API keys, School Vault uses your Paystack Secret Key to make authenticated calls (create DVAs, verify transactions).
• Webhooks, when a payment is received into your Paystack account, Paystack sends a real-time notification (webhook) to School Vault's servers. School Vault then matches the payment to the correct student and bill.

Connecting Paystack to School Vault

1. Log in to your Paystack Dashboard at dashboard.paystack.com.
2. Go to Settings → API Keys & Webhooks.
3. Copy your Live Secret Key (starts with sk_live_). Do not use the test key in production.
4. Return to School Vault and go to Fees from the sidebar → Settings tab.
5. Paste the Live Secret Key into the Paystack Secret Key field.
6. Click Verify & Connect. School Vault validates the key against the Paystack API. If valid, your business name and account status appear as confirmation.
7. Click Save Integration.

Configuring webhooks

1. In School Vault, go to Fees → Settings tab and locate the webhook URL field.
2. Copy your School Vault Webhook URL (it looks like: https://[your-domain]/api/webhooks/paystack/[unique-token]).
3. Return to your Paystack Dashboard → Settings → API Keys & Webhooks.
4. Paste the URL into the Webhook URL field.
5. Click Update in Paystack.
6. In School Vault, click Test Webhook. School Vault sends a test ping to Paystack and waits for the callback. A green "Webhook active" status confirms the connection is working.

How automatic reconciliation works

When a parent transfers money to their DVA:

1. The bank processes the transfer (near-instant for NIBSS IMPS, up to 2 hours for same-day bank transfers).
2. Paystack receives the funds and fires a dedicatedaccount.assign.success or transfer.success webhook to School Vault.
3. School Vault receives the webhook, verifies the Paystack signature, identifies the student by the DVA number, and credits the payment against the open bill.
4. The bill status updates to Partially Paid or Paid in Full.
5. A payment confirmation is sent to the parent (in-app + SMS).

This entire process takes 5–30 seconds after the bank transfer completes.

Manual reconciliation for missed webhooks

Occasionally a webhook may fail to reach School Vault (server downtime, network timeout). In this case:

1. Go to Fees → Fee Assignments tab and filter by Pending status to identify payments not yet matched.
2. School Vault polls Paystack daily for any transactions not yet matched to a bill. These appear here.
3. For each unreconciled payment, verify the amount and DVA number, select the student manually, and click Reconcile.
4. You can also trigger a full reconciliation sweep: click Sync All Transactions. This pulls the last 7 days of Paystack transactions and attempts to match any that are unreconciled.

Common mistakes

• Using the test (sandbox) secret key in the production School Vault settings, test transactions never involve real money and the integration will appear to work but no real payments will reconcile.
• Not testing the webhook after setup, always click Test Webhook to confirm the connection before the term begins.
• Having multiple Paystack webhook URLs configured, Paystack only sends events to one URL. Ensure the School Vault URL is the active one.