Overview
Icon for Paystack

Paystack

Processes payments across Africa via Paystack

Medusa Paystack Browser Plugin

Medusa v2 plugin for Paystack with:

  • a per-store admin widget for the Paystack publishable key
  • a public config route for storefronts and mobile apps
  • a hosted webview checkout route that loads Paystack InlineJS v2
  • a frontend helper export for browser checkout
  • an optional verified Medusa payment provider for installs that also configure a Paystack secret key

Modes

Helper mode

Helper mode only needs the Paystack publishable key.

It gives you:

  • Copy to clipboardstore.metadata.paystack_publishable_key
  • Copy to clipboardGET /store/paystack/config
  • Copy to clipboardGET /store/paystack/webview
  • Copy to clipboardmedusa-paystack-plugin/frontend helper functions

In helper mode, the browser Copy to clipboardonSuccess(transaction) callback is only a UX signal. The plugin does not mark a Medusa order as paid from the client callback alone.

Verified mode

Verified mode uses the same browser checkout flow, but also registers the optional payment provider with a Paystack Copy to clipboardsecret_key.

In verified mode:

  • the browser success callback triggers Copy to clipboardsdk.store.cart.complete(cart.id)
  • the provider verifies the Paystack transaction reference server-side
  • Medusa only completes the cart when verification succeeds
  • refunds use the stored Paystack transaction id

Installation

npm install medusa-paystack-plugin

Register the plugin in your Medusa app:

module.exports = defineConfig({
plugins: [
{
resolve: "medusa-paystack-plugin",
options: {},
},
],
})

If you want verified Medusa payment completion, also register the provider:

module.exports = defineConfig({
plugins: [
{
resolve: "medusa-paystack-plugin",
options: {
secret_key: process.env.PAYSTACK_SECRET_KEY,
},
},
],
modules: [
{
resolve: "@medusajs/medusa/payment",
options: {
providers: [
{
resolve: "medusa-paystack-plugin/providers/paystack",
id: "paystack",
options: {
secret_key: process.env.PAYSTACK_SECRET_KEY,
},

Admin setup

After the plugin is installed, open the store details page in Medusa Admin. A Copy to clipboardPaystack widget is injected into Copy to clipboardstore.details.after.

Save the store-specific publishable key there. The widget stores it in:

store.metadata.paystack_publishable_key

Store routes

Copy to clipboardGET /store/paystack/config

Returns:

{
"store_id": "store_123",
"publishable_key": "pk_test_xxx",
"verified_mode_enabled": true
}

If your Medusa installation has more than one store, pass Copy to clipboardstore_id.

Copy to clipboardGET /store/paystack/webview

Returns a minimal HTML page that loads Paystack InlineJS and starts checkout inside a mobile webview or popup-style browser window.

Supported query params:

  • Copy to clipboardstore_id
  • Copy to clipboardemail
  • Copy to clipboardamount
  • Copy to clipboardcurrency
  • Copy to clipboardreference
  • Copy to clipboardcallback_url
  • Copy to clipboardmetadata
  • Copy to clipboardchannels
  • Copy to clipboardfirst_name
  • Copy to clipboardlast_name
  • Copy to clipboardphone

On success, cancel, or error the page:

  • posts a message with source Copy to clipboardmedusa-paystack-webview
  • redirects to Copy to clipboardcallback_url when provided

Frontend helper

Import the helper:

import {
buildPaystackReference,
buildPaystackWebviewUrl,
createPaystackSuccessHandler,
fetchPaystackConfig,
launchPaystackCheckout,
} from "medusa-paystack-plugin/frontend"

Storefront checkout example

const config = await fetchPaystackConfig({
baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL,
storeId: "store_123",
})
const onSuccess = createPaystackSuccessHandler({
mode: config.verified_mode_enabled ? "verified" : "helper",
cartId: cart.id,
sdk,
redirectUrl: `${window.location.origin}/checkout/complete`,
})
await launchPaystackCheckout({
key: config.publishable_key,
email: cart.email!,
amount: paymentSession.amount,
currency: paymentSession.currency_code,
reference:
(paymentSession.data as { paystack_reference?: string })?.paystack_reference ??
buildPaystackReference(),

Mobile webview example

const webviewUrl = buildPaystackWebviewUrl({
baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL,
callbackUrl: "myapp://checkout/complete",
currency: cart.currency_code,
email: cart.email!,
amount: cart.total,
metadata: {
cart_id: cart.id,
},
storeId: "store_123",
})

Load that URL in your mobile webview and listen for the Copy to clipboardmedusa-paystack-webview message payload or the redirect to your callback URL.

Development

npm run typecheck
npm test
npm run build

Notes

  • This package uses the Medusa v2 plugin scaffold and exports Copy to clipboard./providers/paystack plus Copy to clipboard./frontend.
  • If Copy to clipboardnpm run build fails because your local Medusa CLI install is incomplete, reinstall dependencies cleanly and rerun the build.

You may also like

Browse all integrations

Build your own

Develop your own custom integration

Build your own integration with our API to speed up your processes. Make your integration available via npm for it to be shared in our Library with the broader Medusa community.

gift card interface

Ready to build your custom commerce setup?