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

``bash
npm install react-native-paystack-webview


or


yarn add react-native-paystack-webview
`

$3

`bash
yarn add react-native-webview

iOS

cd ios && pod install

Expo

npx expo install react-native-webview
`

---

⚡ Quick Start

$3

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




`

$3

`tsx
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 ;
};
`

---

🧠 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

$3

| Prop | Type | Default | Description |
|-------------------|-----------|---------|------------------------------------------|
| publicKey | string | — | Your Paystack public key |
| currency | string | — | Currency code (optional) |
| 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 |

$3

| 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

---

[](https://github.com/just1and0/object-to-array-convert#contributions)Contributions

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

---

[](https://github.com/just1and0/React-Native-Paystack-WebView#licensing)Licensing

This project is licensed under the MIT License.

---

Related Projects

- React-Native-quidpay-WebView
- React-Native-rave-WebView

---

$3

- Accepting Payment With Paystack In React Native by just1and0

---

Sponsorship

- Star the project on Github
- Buy me a coffee
- Like, Share and subscribe on Youtube

---

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 💻	Tolu Kalejaiye 💻 🐛	Harith Onigemo 💻

This project follows the all-contributors specification. Contributions of any kind welcome!