> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your app to Paystack

> Connect your app to Paystack, a payments provider for businesses in Africa, to take card, bank transfer, and mobile money payments from your Lovable app.

[Paystack](https://paystack.com/) is a payments provider for businesses in Nigeria, Ghana, Kenya, South Africa, and Côte d'Ivoire. The Paystack connector lets your Lovable app take payments through your own Paystack business, send customers to Paystack's checkout, and confirm each payment with Paystack. It's designed for apps whose owners already take payments with Paystack.

Paystack is available as an [app + chat connector](https://docs.lovable.dev/integrations/app-connectors.md): one shared connection that works in [Chats](https://docs.lovable.dev/features/chats.md), in the project chat while you build, and in your published apps.

With Paystack, your app can:

* Start a payment for the amount of an order and send the customer to Paystack's checkout page
* Open Paystack's checkout in a popup, so the customer stays on your page
* Mark an order as paid only after Paystack confirms the payment, its amount, and its currency
* Sell subscriptions with Paystack plans and stop a subscription from renewing
* Refund a payment in full or in part
* List recent transactions and their status

If you don't have a Paystack business, [Lovable payments](https://docs.lovable.dev/features/payments.md) can set up Paddle or Stripe for you instead. When you ask Lovable to add payments without naming a provider, it recommends those built-in payments.

## Common use cases and example apps

These examples show what you can build with Paystack, each with a prompt to start from.

| Example app | Example prompt | Description |
| :- | :- | :- |
| **Webshop checkout** | *Use Paystack and build a checkout for my shop so customers can pay for their cart in naira.* | **Take payment for a cart in one step.** The app starts a Paystack payment for the cart total, sends the customer to Paystack's checkout, and marks the order paid when Paystack confirms it. |
| **Popup payment** | *Use Paystack and build a product page where customers pay in a popup without leaving the page.* | **Keep customers on your page while they pay.** The app opens Paystack's checkout over the product page and confirms the payment with Paystack before it shows the receipt. |
| **Event ticket sales** | *Use Paystack and build a ticket page where visitors buy tickets for our event and receive a confirmation.* | **Sell tickets with local payment methods.** The app starts a payment for the selected tickets and confirms the order only after Paystack reports the payment as successful. |
| **Membership subscription** | *Use Paystack and build a members area with a monthly plan, where access ends when the subscription stops.* | **Charge members on a schedule.** The app subscribes each member to a Paystack plan and checks the subscription's status before it grants access. |
| **School fee payments** | *Use Paystack and build a page where parents pay school fees for a term and download a receipt.* | **Collect fixed fees and keep a record.** The app starts a payment for the fee, confirms it with Paystack, and stores the payment reference with the receipt. |
| **Payments overview** | *Use Paystack and build an admin page that lists the last 20 transactions with their amount and status.* | **See recent payments in one place.** The app reads transactions from your Paystack business and shows which succeeded, failed, or were abandoned. |

## How to connect Paystack

Who can create Paystack connections depends on your plan and workspace settings. App + chat connectors are available by default. On Business and Enterprise plans, [Who can create connections and clients](https://docs.lovable.dev/integrations/admin-controls.md#who-can-create-connections-and-clients) starts at **Admins**. Some Enterprise workspaces start at **No one**, which disables the connector. An admin or owner changes it in **Connectors → Admin settings → App + chat connectors**.

You can create multiple Paystack connections using different API keys, which is useful for separating test and live payments or connecting different Paystack businesses.

When the connection is created, you can [link it to the projects](https://docs.lovable.dev/integrations/app-connectors.md#link-a-connection-to-a-project) where you want to use it. Anyone building in a project can ask Lovable in the project chat to link their project to it. Linking follows the connection's access rules.

Link one Paystack connection to a project at a time. Your app uses only the first linked connection. When you're ready to take real payments, unlink the test connection and link the live one. Then ask Lovable to register the webhook again, as described in [How payments are confirmed](#how-payments-are-confirmed).

### Prerequisites

Before connecting Paystack, make sure you have:

* A Paystack account with a business
* The secret key of that business
* Permission to **create connections** in your Lovable workspace (see [Who can create connections and clients](https://docs.lovable.dev/integrations/admin-controls.md#who-can-create-connections-and-clients))

> [!NOTE]
>
> Payments made through this connector go to your Paystack business. Paystack charges its transaction fees directly, and billing is handled by Paystack, not Lovable.

### Step 1: Get your Paystack API keys

A Paystack secret key lets your Lovable app start and read payments for one Paystack business. Each business has a test secret key, which starts with `sk_test_`, and a live secret key, which starts with `sk_live_`. Payments made with a test key move no money.

Each mode also has a public key, which starts with `pk_test_` or `pk_live_`. The public key is optional in Lovable.

To get your Paystack API keys:

**1. Open your Paystack Dashboard**

Sign in to the [Paystack Dashboard](https://dashboard.paystack.com/).

**2. Open API keys**

Go to [Settings → API Keys & Webhooks](https://dashboard.paystack.com/#/settings/developers). The dashboard shows the keys for the mode you have selected, test or live.

**3. Copy the secret key**

Copy the secret key and store it securely. If you also want the public key, copy it from the same mode.

> [!WARNING]
>
> Your secret key functions like a password. Keep it secure and never share it publicly. You'll need it in the next step.

See Paystack documentation for more: [Authentication](https://paystack.com/docs/api/authentication/).

### Step 2: Connect Paystack to Lovable

Use your test keys for the first connection, so you can try payments without moving real money.

**1. Open Paystack in Connectors**

Open [Connectors](https://lovable.dev/dashboard?connectors) and select **Paystack**. For the other places to open the catalog from, see [Where to find connectors](https://docs.lovable.dev/integrations/introduction#where-to-find-connectors).

**2. Add a connection**

Click **Connect** on the connector page. The form has three sections, **Details**, **Configure connection**, and **Sharing**.

**3. Name the connection**

Under **Details**, Lovable fills in **Display name**, which you can change. The name is only used inside Lovable to identify the connection, for example `Paystack Test` or `Paystack Live`.

**4. Configure the connection**

Under **Configure connection**, enter:

1. **Secret key**: paste your Paystack secret key. It must start with `sk_test_` or `sk_live_`. **Open API Keys & Webhooks** opens that page in the Paystack Dashboard.
2. **Public key** (optional): paste the public key from the same mode as the secret key. It must start with `pk_test_` or `pk_live_`. Both checkouts on this page, the checkout page and the popup, work without it, so you can leave it empty. Paste it only if you ask Lovable for a checkout that uses Paystack's public key.

**5. Choose who can use this connection**

Under **Sharing**, the connection is private to you by default and shows a **Private** label. To share it, click **Share with others**. Then add workspace members by email, or click **Invite entire workspace** to make the connection available to everyone in your Lovable workspace.

See [Who can use connections and clients](https://docs.lovable.dev/integrations/admin-controls.md#who-can-use-connections-and-clients) for more information.

**6. Connect**

Click **Connect** at the bottom of the form. Lovable checks the secret key with Paystack when you connect.

When connected, anyone building in a project can ask Lovable in the project chat to link their project to Paystack. Linking follows the connection's access rules. Your Lovable apps can then start payments and confirm them with Paystack.

## How payments are confirmed

Lovable builds your app so it sets the amount of each payment from the order. Customers cannot change the amount.

After the customer pays, your app asks Paystack for the transaction. Your app marks the order as paid only when Paystack reports the transaction as successful and the amount and currency match the order. Your app does not treat the customer's return to your site as proof of payment.

Paystack also tells your app about a payment by calling a webhook, a public address in your app. The webhook covers customers who close the browser before they return to your site.

Paystack can't reach the editor's preview, so Lovable sets up the webhook on an address that Paystack can reach while you build. You can take test payments before you publish the app.

On new Lovable apps created from May 13, 2026, which use TanStack Start, ask Lovable to register the webhook again after you publish for the first time, so Paystack also calls the published app. Older React + Vite apps keep the same webhook address after publishing.

Lovable can add the webhook address to your Paystack business when you ask for it in the project chat. If Paystack does not accept the request, Lovable gives you the address, and you add it as the webhook URL under [Settings → API Keys & Webhooks](https://dashboard.paystack.com/#/settings/developers) in the Paystack Dashboard.

Paystack keeps separate webhook settings for test and live payments. After you link a live connection, ask Lovable to register the webhook again.

## Limitations

The Paystack connector cannot:

* Take a payment in a currency that is not enabled on your Paystack business. Paystack decides which currencies a business accepts.
* Send payouts. Lovable builds payments with this connector, not transfers from your Paystack balance to bank accounts or mobile wallets.
* Charge a saved card without a checkout. Every payment starts on Paystack's checkout, so one-click repeat payments and usage-based charges are not available. A customer who changes plans or returns after cancelling pays through the checkout again.
* Collect card numbers or mobile money details in your own form. Customers enter them on Paystack's checkout, which also offers bank transfer and mobile money.
* Split a payment between sellers. Marketplaces use split payments to send each seller's share to that seller's own account. They are not available.
* Send invoices or payment links. Your app starts each payment itself and sends the customer to Paystack's checkout.
* Create dedicated virtual accounts, which are bank account numbers that Paystack assigns to one customer for paying by transfer. Bank transfer stays available on Paystack's checkout.
* Handle disputes, which are payments that a customer has challenged with their bank. Respond to them in the Paystack Dashboard.
* Read your Paystack balance or look up the holder of a bank account.
* Support per-end-user Paystack login. Each connection represents a single Paystack business shared across all projects linked to it.

## Troubleshooting

Use these checks when connecting fails or a payment does not start.

> [accordion] Paystack did not validate your credentials.
>
> Paystack rejected the secret key, or the two keys are from different modes. Check that you copied the whole secret key and that it starts with `sk_test_` or `sk_live_`. If you entered a public key, check that both keys are test keys or both are live keys from the same Paystack business. Click **Show error** to see the reason.

> [accordion] A payment fails with a currency error
>
> Paystack refuses a payment in a currency that is not enabled on your business. Tell Lovable in the project chat which currency your Paystack business accepts, for example NGN, GHS, KES, or ZAR.

## Manage your Paystack connection

Connections are managed from [**Connectors**](https://lovable.dev/dashboard?connectors): select **Paystack**, then open the connection.

* **Unlink projects** to remove Paystack access from specific projects while keeping the connection available for others. See [Unlink projects from a connection](https://docs.lovable.dev/integrations/app-connectors.md#unlink-projects-from-a-connection) for the steps.
* **Delete the connection** to remove it from the workspace entirely. Deleting is permanent. It removes the credentials from all linked projects, and app features that use Paystack stop working until a new connection is added. See [Delete a connection](https://docs.lovable.dev/integrations/app-connectors.md#delete-a-connection) for the steps and who can delete.
