canonical: https://jentic.com/apis/paystack.com/paystack # Paystack API Paystack API enables businesses across Africa to accept payments via cards, bank transfers, mobile money, and USSD channels. It supports transaction initialization and verification, subscription management, refund processing, and multi-party split payments. The API also handles customer identity verification, dedicated virtual account assignment, and dispute resolution for merchants operating in Nigeria, Ghana, South Africa, and Kenya. ## For AI agents Accept payments, manage subscriptions, process refunds, and handle transfers for African merchants across cards, bank transfers, mobile money, and USSD channels. ## Scope Does not handle accounting, invoicing, or tax calculation - use for payment collection and fund transfers only. ## Capabilities - Initialize and verify card, bank transfer, and mobile money payments across African markets - Create subscription plans with automated recurring billing and dunning - Process refunds and manage dispute resolution with evidence uploads - Assign dedicated virtual accounts (DVAs) to customers for bank transfer collection - Split payments across multiple subaccounts for marketplace settlement - Transfer funds to bank accounts and mobile wallets via single or bulk payouts - Verify customer identity with BVN and document validation ## Use cases ### E-Commerce Payment Collection Accept one-time payments for online stores targeting African customers. Paystack handles card validation, bank transfer confirmation, and mobile money collection across Nigeria, Ghana, South Africa, and Kenya. Merchants initialize a transaction, redirect the customer to Paystack's hosted page or use the inline popup, and verify the transaction upon callback. The API supports 4 currencies (NGN, GHS, ZAR, KES) and settles funds to the merchant's bank account on a T+1 or next-business-day schedule. Example prompt: Initialize a transaction for 5000 NGN with the customer email customer@example.com, then verify the transaction reference after payment completion ### Subscription Billing for SaaS Set up recurring billing for subscription-based products serving African markets. Paystack manages plan creation, customer enrollment, automatic charge attempts, and failed-payment retries. Merchants can create plans with daily, weekly, monthly, quarterly, or annual intervals. The API sends webhook notifications for successful charges, failed attempts, and subscription cancellations, enabling automated dunning flows. Example prompt: Create a monthly plan for 2500 NGN named 'Pro Plan', then subscribe a customer with authorization code AUTH_xxx to that plan ### Marketplace Split Payments Distribute payments across multiple parties in a marketplace or platform model. Paystack's transaction splits let platforms define percentage or flat-fee splits between the main account and subaccounts. This handles vendor payouts, platform commissions, and tax withholding in a single transaction without manual settlement reconciliation. Example prompt: Create a transaction split that allocates 80% to subaccount ACCT_xxx and 20% to the main account, then initialize a 10000 NGN payment using that split ### Bulk Payouts to Bank Accounts Send money to multiple recipients via bank transfer in a single batch. Paystack's transfer API supports individual and bulk transfers to Nigerian bank accounts and mobile wallets. Each transfer requires a pre-registered recipient with verified account details. The API provides real-time transfer status and webhook notifications for successful or failed disbursements. Example prompt: Create a transfer recipient for account number 0123456789 at bank code 058, then initiate a bulk transfer of 50000 NGN split across 3 recipients ### AI Agent Payment Automation via Jentic AI agents use the Paystack API through Jentic to automate payment collection, verify transaction statuses, and trigger refunds without handling raw secret keys. Agents search for payment operations by intent, receive typed schemas for each endpoint, and execute calls with Jentic managing credential isolation and response validation. This reduces integration time from days to under an hour for agent-driven commerce workflows. Example prompt: Search Jentic for 'verify a Paystack transaction', load the transaction verification schema, and execute a verification call for reference REF_abc123 ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/transaction/initialize` | Initialize a new payment transaction | | GET | `/transaction/verify/{reference}` | Verify a transaction by reference | | POST | `/subscription` | Create a new subscription | | POST | `/refund` | Process a refund | | POST | `/transfer` | Initiate a single transfer | | POST | `/transfer/bulk` | Initiate bulk transfers | | POST | `/split` | Create a transaction split | | POST | `/dedicated_account` | Assign a dedicated virtual account | ## Key resources - **Transactions** — Initialize, verify, list, and export payment transactions - **Customers** — Create, update, and validate customer records and authorizations - **Plans** — Define billing plans with intervals and amounts for subscriptions - **Subscriptions** — Manage recurring billing enrollment, pausing, and cancellation - **Transfers** — Send funds to bank accounts and mobile wallets individually or in bulk - **Refunds** — Process full or partial refunds for completed transactions - **Disputes** — View, respond to, and resolve chargebacks with evidence - **Dedicated Virtual Accounts** — Assign unique bank account numbers to customers for transfer collection ## Why Jentic - **Setup:** Wiring the Paystack API by hand means managing its secret-key bearer auth and stitching together transaction, transfer, and subscription flows yourself. Through Jentic you install once, import Paystack from the API Directory, store the secret key once, and your agent calls it. - **Permission scoping:** Paystack passes its transaction and transfer details in the request body, so scope the agent by the operations it needs, such as initializing a transaction or verifying one by reference. You choose that set, so fund-moving operations like transfer, bulk transfer, or refund are not included unless you add them. - **Credential handling:** Your Paystack secret key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'accept a payment in Nigeria' or 'verify a transaction', and Jentic returns the matching Paystack operation with its typed request and response schemas so the agent calls the right endpoint without parsing the reference docs. ## Related APIs - **Flutterwave API** — Pan-African payment gateway with broader country coverage but similar core features - **Stripe API** — Global payment processor with deeper feature set but limited African payment method support - **Braintree API** — PayPal-owned gateway focused on US and European markets ## FAQ ### What authentication does the Paystack API use? The Paystack API uses Bearer token authentication with your secret key passed in the Authorization header. Through Jentic, your Paystack secret key is stored encrypted in the credential vault and agents receive scoped access tokens without the raw key entering the agent context. ### Can I process mobile money payments with the Paystack API? Yes. The Paystack API supports mobile money as a payment channel alongside cards, bank transfers, and USSD. You initialize a transaction via POST `/transaction/initialize` specifying the mobile_money channel, and the customer completes payment on their handset. ### What are the rate limits for the Paystack API? Paystack applies rate limits per secret key. The standard limit is 50 requests per second for transaction endpoints. Bulk operations like POST `/transfer/bulk` count as a single request regardless of the number of transfers included. ### How do I verify a payment through Jentic? Search Jentic for 'verify paystack transaction', load the returned schema for GET `/transaction/verify/{reference}`, and execute the call with the transaction reference. Jentic handles the Bearer token injection and returns the transaction status, amount, and currency in a structured response. ### Does the Paystack API support split payments for marketplaces? Yes. You create a split configuration via POST /split defining subaccounts with percentage or flat-amount shares. Then attach the split ID when initializing transactions. Paystack automatically distributes settlement funds across all parties. ### Which countries does the Paystack API support? Paystack supports merchants in Nigeria (NGN), Ghana (GHS), South Africa (ZAR), and Kenya (KES). Each country has specific payment methods available including cards, bank transfers, mobile money, and USSD depending on the market. ### Can I limit what my agent is allowed to do with the Paystack API? Yes. Because you run your own self-hosted Jentic One instance, your own rules decide which Paystack operations and credentials the agent may use. Since Paystack passes transaction and transfer details in the request body, you scope the agent to just the operations it needs, such as initializing a transaction with POST `/transaction/initialize` or verifying one with GET `/transaction/verify/{reference}.` Fund-moving operations like transfer, bulk transfer, or refund stay out of reach unless you explicitly add them to the allowed set.