React Native Paystack WebView (v5)

Modern, hook-based, Paystack-powered payments in React Native apps using WebViews — now streamlined with Provider architecture & fully customizable.

Endorsed by Paystack, so you know you’re in good hands. Payment processing has never been this easy!

🚀 Installation

npm install react-native-paystack-webview
# or
yarn add react-native-paystack-webview

📦 Peer Dependency

yarn add react-native-webview

# iOS
cd ios && pod install

# Expo
npx expo install react-native-webview

⚡ Quick Start

Wrap your app with the Provider

import { PaystackProvider } from 'react-native-paystack-webview';

<PaystackProvider publicKey="pk_test_XXXXXX">
  <App />
</PaystackProvider>

Use in a component

import React from 'react';
import { Button } from 'react-native';
import { usePaystack } from 'react-native-paystack-webview';

const Checkout = () => {
  const { popup } = usePaystack();

  const payNow = () => {
    popup.checkout({
      email: 'jane.doe@example.com',
      amount: 5000,
      reference: 'TXN_123456',
      plan: 'PLN_example123',
      invoice_limit: 3,
      subaccount: 'SUB_abc123',
      split_code: 'SPL_def456',
      split: {
        type: 'percentage',
        bearer_type: 'account',
        subaccounts: [
          { subaccount: 'ACCT_abc', share: 60 },
          { subaccount: 'ACCT_xyz', share: 40 }
        ]
      },
      metadata: {
        custom_fields: [
          {
            display_name: 'Order ID',
            variable_name: 'order_id',
            value: 'OID1234'
          }
        ]
      },
      onSuccess: (res) => console.log('Success:', res),
      onCancel: () => console.log('User cancelled'),
      onLoad: (res) => console.log('WebView Loaded:', res),
      onError: (err) => console.log('WebView Error:', err)
    });
  };

  return <Button title="Pay Now" onPress={payNow} />;
};

🧠 Features

✅ Simple checkout() or newTransaction() calls
✅ Global callbacks with onGlobalSuccess or onGlobalCancel
✅ Debug logging with debug prop
✅ Fully typed params for transactions
✅ Works seamlessly with Expo & bare React Native
✅ Full test coverage

📘 API Reference

`PaystackProvider`

Prop	Type	Default	Description
`publicKey`	`string`	—	Your Paystack public key
`currency`	`string`	`NGN`	NGN / GHS / USD
`defaultChannels`	`string[]`	`['card']`	Payment channels
`debug`	`boolean`	`false`	Show debug logs
`onGlobalSuccess`	`func`	—	Called on all successful transactions
`onGlobalCancel`	`func`	—	Called on all cancelled transactions

`popup.checkout()` / `popup.newTransaction()`

Param	Type	Required	Description
`email`	`string`	✅	Customer email
`amount`	`number`	✅	Amount in Naira (not kobo)
`reference`	`string`	—	Custom reference (optional)
`metadata`	`object`	—	Custom fields / additional info
`plan`	`string`	—	Paystack plan code (for subscriptions)
`invoice_limit`	`number`	—	Max charges during subscription
`subaccount`	`string`	—	Subaccount code for split payment
`split_code`	`string`	—	Multi-split identifier
`split`	`object`	—	Dynamic split object
`onSuccess`	`(res) => void`	✅	Called on successful payment
`onCancel`	`() => void`	✅	Called on cancellation
`onLoad`	`(res) => void`	—	Triggered when transaction view loads
`onError`	`(err) => void`	—	Triggered on WebView or script error

Meta Props

Name	Description	Required?	Default Value
`cart_id`	A unique identifier for the cart. Can be either a string or a number.	`NO`	`undefined`
`custom_fields`	An array of custom fields for adding additional metadata to the transaction. If not passed, a default custom field is created using the `firstName`, `lastName`, and `billingName`.	`NO`	`[{ display_name: '${firstName + ' ' + lastName}', variable_name: '${billingName}', value: '' }]`
`cancel_action`	A string specifying the action to take if a transaction is canceled.	`NO`	`undefined`
`custom_filters`	Custom filters to restrict or specify transaction options, such as:	`NO`	`undefined`
	- `recurring`: A boolean to indicate if the transaction is recurring.
	- `banks`: An array of bank codes for supported banks.
	- `card_brands`: Supported card brands, e.g., `'verve'`, `'visa'`, `'mastercard'`.
	- `supported_mobile_money_providers`: Supported mobile money providers, e.g., `'mtn'`, `'atl'`, `'vod'`.

Dynamic Multi-Split Payment Object structure

Name	use/description	required?
`type`	Dynamic Multi-Split type. Value can be `flat` or `percentage`	`YES`
`bearer_type`	Defines who bears the charges. Value can be `all`, `all-proportional`, `account` or `subaccount`	`YES`
`subaccounts`	An array of subaccount object as defined below. e.g. {“subaccount”: ‘ACCT_xxxxxx’, “share”: 60}	`YES`
`bearer_subaccount`	Subaccount code of the bearerof the transaction. It should be specified if bearer_type is `subaccount`	`NO`
`reference`	Unique reference of the split. Can be defined by the user	`NO`

Dynamic Multi-Split Payment Sub-Account Object structure

Name	use/description	required?
`subaccount`	Specify subaccount code generated from the Paystack Dashboard or API to enable Split Payment on the transaction. Here’s an example of usage: `subaccount: "SUB_ACCOUNTCODE"`	`YES`
`share`	Defines the amount in `percentage (integer)` or `value (decimal allowed)` depending on the type of multi-split defined	`YES`

🧪 Debugging

Enable debug={true} on the PaystackProvider to get logs like:

Transaction modal status
Incoming postMessage data
Success, cancel, error logs

Contributions

Want to help improve this package? Read how to contribute and feel free to submit your PR!

Licensing

This project is licensed under the MIT License.

Video Tutorial

Accepting Payment With Paystack In React Native by just1and0

Sponsorship

Thanks to Our Superheroes ✨

A huge shoutout to our amazing contributors! Your efforts make this project better every day. Check out the (emoji key) for what each contribution means:

_{Oluwatobi Shokunbi} 💻 📖	_{Akinyemi Mosolasi} 📖 💻	_{okechukwu0127} 💻 🐛	_Johney 💻	_sammy 💻	_{Jimoh Jamiu} 🐛 📖 💻	_{Cahak George} 💻
_{John Ayeni} 📖	_majirieyowel 💻	_{David Erinayo Obidu} 🐛	_surafelbm 🐛	_{Rex Omiv} 🐛	_{Osagie Osaigbovo Charles} 🐛	_Ujjalcha1 🐛
_{Oyefeso Oluwatunmise} 🐛	_{Fuad Olatunji} 📖	_{Wilhelm Erasmus} 💻	_{Matiluko Opeyemi Emmanuel} 💻 📖	_{Oluwamurewa Alao} 💻	_{Emmanuel Ngene} 💻	_Mauko 📖
_{Quartus Kok} 💻