Understanding Paystack API
The Paystack REST API is accessed at https://api.paystack.co. Authentication uses Authorization: Bearer SECRET_KEY. SDKs are available for PHP, Python, JavaScript, Ruby, Go, .NET, and Java. The API is organised around transactions, customers, subscriptions, and subaccounts. Rate limit is 200 requests per second.
How to Charge a Card
Use the standard checkout via the hosted modal for PCI compliance. POST to /transaction/initialize with email and amount in kobo, get the authorization_url, and redirect the customer. The direct charge API at /charge is for in-app payments but requires PCI SAQ A compliance.
Transaction Verification
Transaction verification is the single most important security step. Never trust the redirect callback alone. Always call GET /transaction/verify/:reference server-side after receiving a callback. The response returns the status field which must be "success" before you grant value. Check that the amount matches to prevent tampering.
The response also includes an authorization object with an authorization_code. Store this code for recurring payments and one-click purchases.
Webhook Implementation
Webhooks arrive server-to-server regardless of what the customer does after payment. Paystack sends events to your configured URL for charge.success, transfer.success, transfer.failed, subscription.create, and invoice.paid. Verify the x-paystack-signature header using HMAC-SHA256 with your secret key.
Respond with HTTP 200 quickly and process asynchronously. Paystack retries for up to 72 hours if it does not receive a 200 response.
Recurring Payments and Subscriptions
Paystack subscriptions enable recurring billing without storing card details. Create a plan using /plan with the name, amount, and interval. Create a subscription via /subscription with the customer’s email, plan code, and authorization code. Paystack automatically charges the card on each billing date.
Handle lifecycle events through webhooks. subscription.disable fires on cancellation or after exhausting retry attempts. invoice.paid fires for each successful billing cycle.
Split Payment Configuration
Split payments distribute funds among multiple parties. Create subaccounts using /subaccount with business name, settlement bank, and default split percentage. Pass a split_code during transaction initialisation. The bearer type determines who pays the fee: account, subaccount, or all.
Error Handling and Edge Cases
Common errors include insufficient funds, expired cards, invalid PIN, and network timeouts. HTTP 400 indicates validation errors, 401 means authentication failure, 404 means resource not found, and 429 means rate limit exceeded. Implement exponential backoff for 5xx errors. Run reconciliation jobs hourly to catch orphaned transactions where verification timed out.
Frequently Asked Questions
How do I integrate Paystack into a Nigerian app?
Register a Paystack business account, obtain your secret and public keys, install the Paystack SDK for your preferred language, implement the charge card or standard checkout flow, and handle the webhook callback to verify transactions.
What is the difference between Paystack test mode and live mode?
Test mode uses test API keys and fake card numbers to simulate transactions without real money movement. Live mode processes real payments. Switch to live mode only after completing end-to-end testing.
How does Paystack split payment work?
Paystack Split Payment allows you to automatically distribute transaction amounts among multiple subaccounts. You define the split configuration with percentage or flat amounts per subaccount, and Paystack handles the settlement automatically.
How do I verify a Paystack transaction?
Use the GET /transaction/verify/:reference endpoint with the transaction reference returned from the charge call. The response includes the full transaction status, amount, and customer details.