Paystack
Overview
Paystack is a modern payment gateway that makes it easy to accept payments from customers across Africa. This guide shows you how to integrate Paystack into your Emergent app so you can collect payments, manage subscriptions, and handle transactions.
When you connect Paystack, your app can process card payments, bank transfers, mobile money, and other local payment methods supported across African markets.
Before you begin
You'll need:
- A Paystack account (sign up is free)
- Your Paystack API keys (available in your Paystack dashboard under Settings → API Keys & Webhooks)
- An Emergent app that needs payment functionality
Info
Paystack provides both test keys (for development) and live keys (for production). Start with test keys while building and testing your integration.
Add Paystack to your app
Tell Emergent you want to use Paystack
In your app's chat, describe what you want to build:
"Add Paystack payment integration. I want to accept card payments and generate payment links for customers."
Be specific about your use case - for example, one-time payments, subscriptions, or donation flows.
Provide your API keys
Emergent will prompt you for your Paystack keys. You'll need:
- Public key - safe to expose in your frontend code
- Secret key - kept secure on the backend; never expose this in client-side code
Copy these from your Paystack dashboard (Settings → API Keys & Webhooks) and paste them when prompted.
Configure webhook endpoints
Paystack sends notifications (webhooks) when payment events occur - successful charges, failed transactions, subscription renewals, etc.
Emergent will generate a webhook URL for your app. Copy this URL and add it in your Paystack dashboard:
- Go to Settings → API Keys & Webhooks
- Scroll to Webhook URL
- Paste your Emergent webhook URL
- Save changes
This ensures your app receives real-time updates about payment status.
Test the integration
Use Paystack's test card numbers to verify everything works:
- Successful payment:
(any future expiry, any CVV)4084 0840 8408 4081 - Declined payment:
5060 6666 6666 6666 64
Process a test transaction in your app and confirm that payment status updates correctly.
Go live
When you're ready for production:
- After the first publish, replace the test keys with live keys in the Secrets panel(Preview → Manage → Secrets)
- Ensure your Paystack account is fully activated (business verification complete)
- Confirm your webhook URL is configured with your live keys
- Re-publish the app to apply the live keys
Common use cases
For selling products or services with a single charge:
- Initialize a transaction with an amount and customer email
- Redirect the customer to Paystack's secure checkout
- Handle the callback when payment succeeds or fails
- Confirm transaction status via webhook before fulfilling the order
For recurring revenue models:
- Create a Plan in your Paystack dashboard (defines amount and billing interval)
- Subscribe customers to the plan via your app
- Paystack automatically charges the customer on each billing cycle
- Handle
,subscription.create
, andcharge.success
webhookssubscription.disable
For no-code payment collection:
- Generate a Paystack payment link in your app
- Share the link via email, SMS, or messaging apps
- Customers pay without needing to visit your website
- Track payments in your Paystack dashboard or via webhooks
For marketplaces or platforms with multiple vendors:
- Set up Subaccounts for each vendor in Paystack
- Route a percentage of each transaction to the subaccount
- Paystack handles the splits automatically
- Each vendor can withdraw their balance independently
Supported payment methods
Paystack supports different payment methods by country. The available channels are:
- Card: all markets.
- Pay-with-Bank: Nigeria.
- Pay-with-Transfer: Nigeria and Ghana.
- USSD: Nigeria.
- Mobile Money: Ghana (MTN, AT Money & Airtel Money, Telecel), Kenya (M-Pesa, Airtel Money), and Côte d'Ivoire (MTN, Orange, Wave).
- Pay with Pesalink: Kenya. Instant bank transfers; requires enablement by Paystack support, and Diamond Trust Bank accounts can't pay via this channel.
- Instant EFT (Ozow): South Africa.
- Capitec Pay: South Africa.
- QR (SnapScan / Scan to Pay): South Africa.
Tip
Enable multiple payment methods to maximize conversion. Customers can choose their preferred option at checkout.
Webhook events
Your app receives these common events from Paystack:
Fired when a payment is successfully completed. Use this to fulfill orders, grant access, or trigger downstream workflows. Always verify the transaction amount and status before taking action.
Sent when a payment attempt fails (insufficient funds, incorrect PIN, etc.). You might want to notify the customer or offer alternative payment methods.
Triggered when you send money to a customer (refunds, payouts, etc.). Useful for confirming disbursements in marketplace or payout scenarios.
Fired when a customer is subscribed to a plan. Update your database to reflect active subscription status.
Sent when a subscription is canceled (by the customer or due to failed payments). Revoke access or notify the customer as appropriate.
Info
Paystack webhooks include a signature header (
x-paystack-signatureTesting and troubleshooting
Test mode vs. live mode
Always develop and test with test keys. Test mode has no financial impact - transactions are simulated and no real money moves. When you switch to live keys, every transaction is real.
Common issues
| Issue | Solution |
|---|---|
| Webhook not receiving events | Confirm the webhook URL in your Paystack dashboard matches the one Emergent provided - Check that your app is published and accessible (your cloud preview at |
| Transactions showing as pending | Bank transfers and some mobile money payments require manual confirmation - Check the Paystack dashboard for transaction status - Set up webhook listeners for |
| Payment page not loading | Ensure your public key is correctly configured in the frontend - Check browser console for JavaScript errors - Verify the transaction amount is valid (Paystack requires amounts in kobo/pesewas - smallest currency unit) |
Testing tools
Paystack provides a Test Mode Dashboard where you can:
- View all test transactions
- Manually trigger webhook events
- Simulate different payment outcomes (success, decline, timeout)
- Inspect API requests and responses
Use these tools to verify your integration handles all scenarios correctly before going live.
Security best practices
Protect your secret key
Never commit secret keys to version control or expose them in client-side code. Emergent stores them securely as environment variables.
Validate webhooks
Always verify the
x-paystack-signatureConfirm on the backend
After a customer completes checkout, verify the transaction status by querying Paystack's API from your backend - don't trust frontend callbacks alone.
Use HTTPS
Ensure your webhook endpoint uses HTTPS. Paystack will not send events to insecure HTTP URLs in live mode.
Pricing and fees
Paystack charges a percentage of each successful transaction. Fees vary by country and payment method:
- Nigeria: 1.5% capped at ₦2,000
- Ghana: 1.95% (no cap)
- South Africa: 2.9% (no cap)
Additional fees may apply for international cards or specific payment methods. Check Paystack's pricing page for current rates.
Note
There are no setup fees, monthly charges, or hidden costs. You only pay when you successfully collect a payment.
