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 clipboard
store.metadata.paystack_publishable_key - Copy to clipboard
GET /store/paystack/config - Copy to clipboard
GET /store/paystack/webview - Copy to clipboard
medusa-paystack-plugin/frontendhelper 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 clipboard
sdk.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
1npm install medusa-paystack-plugin
Register the plugin in your Medusa app:
12345678module.exports = defineConfig({plugins: [{resolve: "medusa-paystack-plugin",options: {},},],})
If you want verified Medusa payment completion, also register the provider:
1234567891011121314151617181920module.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:
1store.metadata.paystack_publishable_key
Store routes
Copy to clipboardGET /store/paystack/config
Returns:
12345{"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 clipboard
store_id - Copy to clipboard
email - Copy to clipboard
amount - Copy to clipboard
currency - Copy to clipboard
reference - Copy to clipboard
callback_url - Copy to clipboard
metadata - Copy to clipboard
channels - Copy to clipboard
first_name - Copy to clipboard
last_name - Copy to clipboard
phone
On success, cancel, or error the page:
- posts a message with source Copy to clipboard
medusa-paystack-webview - redirects to Copy to clipboard
callback_urlwhen provided
Frontend helper
Import the helper:
1234567import {buildPaystackReference,buildPaystackWebviewUrl,createPaystackSuccessHandler,fetchPaystackConfig,launchPaystackCheckout,} from "medusa-paystack-plugin/frontend"
Storefront checkout example
1234567891011121314151617181920const 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
1234567891011const 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
123npm run typechecknpm testnpm run build
Notes
- This package uses the Medusa v2 plugin scaffold and exports Copy to clipboard
./providers/paystackplus Copy to clipboard./frontend. - If Copy to clipboard
npm run buildfails because your local Medusa CLI install is incomplete, reinstall dependencies cleanly and rerun the build.
