Paystack

Paystack

Payment processing platform for African markets (Nigeria, Ghana, South Africa, Kenya, Cote d'Ivoire). Handles card payments, bank transfers, mobile money, and USSD. All amounts are in subunits (kobo for NGN, cents for USD/GHS/ZAR/KES) — multiply the base amount by 100.

Entity Hierarchy

Payment Flow

• Transactions — every payment attempt. States: success, abandoned, failed. Each has a unique reference (your ID) and Paystack id. Contains amount (subunits), currency, channel (card/bank/ussd/mobile_money), customer info, and authorization details for recurring charges.
• Customers — identified by email (unique). Each customer accumulates transactions, subscriptions, and authorizations. Has customer_code (Paystack ID) and optional metadata.

Recurring Billing

• Subscriptions — recurring charges linking a customer's authorization to a plan. States: active, non-renewing, attention, completed, cancelled. Has subscription_code, next_payment_date, and email_token for management links.

Financial Operations

• Invoices (Payment Requests) — billable items sent to customers. States: pending, paid. Can be sent via email or as a link. Each has a request_code and associated offline_reference for offline payments.
• Transfers — payouts from your Paystack balance to bank accounts. Require a transfer recipient. States: success, pending, failed, reversed. Uses transfer codes.
• Refunds — partial or full reversal of a successful transaction. Linked by transaction reference.
• Settlements — batched payouts from Paystack to your bank account. Shows the settlement schedule and deductions.
• Disputes — chargebacks and payment disputes raised by customers or banks. States: awaiting-merchant-feedback, awaiting-bank-feedback, pending, resolved.

Workflows

1. Revenue overview: Enumerate transactions filtered by date range → check settlements for payout timing → review disputes for chargebacks.
2. Customer audit: Enumerate customers → pick one → enumerate their transactions to see payment history.
3. Subscription monitoring: Enumerate subscriptions → filter by status to find attention or non-renewing subs that need action.
4. Payout tracking: Enumerate transfers → correlate with settlements to reconcile bank deposits.
5. Collections: Enumerate invoices (payment requests) → filter unpaid → follow up.
6. Onboard and bill customer: Create or update a customer → initialize a transaction with their email → share the authorization_url for payment.
7. Issue refund: Enumerate transactions → find the successful transaction → create a refund (full or partial).
8. Send payout: Create a transfer recipient with bank details → initiate a transfer from your balance to that recipient.

Pagination

Offset-based with integer page (1-indexed) and perPage (default 50, max 200). Response includes meta.total, meta.page, meta.pageCount. Use page=2, page=3 etc. to paginate — NOT cursor tokens.

Gotchas

• Amounts in subunits: NGN 100 = 10000. Always divide by 100 for display.
• Test vs live keys: sk_test_ prefix for sandbox, sk_live_ for production. Same API, different data.
• Transfer recipients: Must create a transfer recipient before initiating a transfer. Recipients are reusable.
• Currency codes: ISO 4217 (NGN, USD, GHS, ZAR, KES, XOF). Not all currencies available in all countries.