mpw-checkout-react
v0.0.3
Published
Simplify your payment processing with this intuitive React library! Seamlessly integrate MoiPayWay flexible checkout options into your applications—whether you want full control with a modal or an inline experience. Customize your payment buttons, handle
Downloads
40
Maintainers
Readme
MPWCheckout
is a versatile React component library that integrates the MoiPayWay payment gateway into your React apps. It supports both inline and popup payment modes, and now offers two distinct ways to handle payments: initiating payments with MPWCheckout
or continuing existing payments with MPWCheckoutRef
using an orderReferenceCode
.
Installation
You can install MPWCheckout
React via npm
npm install mpw-checkout-react
Prerequisites
- React: This library requires React 18.0 or higher.
- Node: Node version >=14.x is recommended.
Usage
Basic Setup
Wrap your app in MPWCheckoutProvider
to provide the necessary context. The publicKey
is only required if you're using MPWCheckout
to initiate payments. If you're continuing a payment with MPWCheckoutRef
, the publicKey
is optional.
import React from 'react';
import { MPWCheckoutProvider } from 'mpw-checkout-react';
const App = () => (
<MPWCheckoutProvider publicKey="your-public-key">
{/* Your application code */}
</MPWCheckoutProvider>
);
export default App;
Using Inline Checkout
The inline checkout opens a payment modal inside your application. Use the MPWCheckout
component, passing the requestBody
. With optional callbacks like onSuccess
, onFailure
, onClose
. By default the displayMode
is "inline"
, so you don't need to pass it as a prop.
import React from 'react';
import { MPWCheckout, IRequestBody } from 'mpw-checkout-react';
const requestBody: IRequestBody = {
// Your payment details here
};
const handleSuccess = (data) => {
console.log('Payment Successful', data);
};
const handleFailure = (error) => {
console.error('Payment Failed', error);
};
const MyCheckoutButton = () => (
<MPWCheckout
requestBody={requestBody}
onSuccess={handleSuccess}
onFailure={handleFailure}
/>
);
export default MyCheckoutButton;
Using Popup Checkout
For popup checkout, simply set the displayMode
to "popup"
. The payment will open in a new window.
import React from 'react';
import { MPWCheckout, IRequestBody } from 'mpw-checkout-react';
const requestBody:IRequestBody = {
// Your payment details here
};
const MyPopupCheckoutButton = () => (
<MPWCheckout
requestBody={requestBody}
displayMode="popup"
onSuccess={(data) => console.log('Payment Successful', data)}
onFailure={(error) => console.error('Payment Failed', error)}
/>
);
export default MyPopupCheckoutButton;
Customizing Checkout Button
You can fully customize the checkout button by passing your own child components inside the MPWCheckout
component.
<MPWCheckout
requestBody={requestBody}
>
<button>Custom Checkout Button</button>
</MPWCheckout>
Continue Payment with Order Reference
If the payment has already been initiated and you have an orderReferenceCode
, use MPWCheckoutRef
to continue the payment without needing a publicKey
.
import { MPWCheckoutRef } from 'mpw-checkout-react';
const ContinuePaymentButton = () => (
<MPWCheckoutRef
orderReferenceCode="your-order-reference-code"
onSuccess={(data) => console.log('Payment Successful', data)}
onFailure={(error) => console.error('Payment Failed', error)}
/>
);
Full Checkout Control
For full control, use the useMPWCheckout
hook. You can either initiate a new payment or continue a payment using the payReference
and orderReferenceCode
. The MPWCheckoutModal
is necessary for displaying the payment iframe.
Initiate a Payment
import React from 'react';
import { useMPWCheckout, MPWCheckoutModal } from 'mpw-checkout-react';
const CustomPayButton = () => {
const { initiatePayment, isLoading, isOpen, orderReferenceCode } = useMPWCheckout();
const handlePayment = () => {
initiatePayment({
requestBody: {/*request body*/},
onSuccess: (data) => console.log('Payment successful', data),
onFailure: (data) => console.log('Payment failed', data),
onClose: (data) => console.log("Closed data:", data)
});
};
return (
<>
<div className='mb-3'>
<button onClick={handlePayment} disabled={isLoading}>Pay</button>
</div>
<MPWCheckoutModal isOpen={isOpen} orderReferenceCode={orderReferenceCode} />
</>
);
};
export default CustomPayButton;
Continue a Payment
If you want full control of the payment process using an existing orderReferenceCode
, you can use payReference
from useMPWCheckout
:
import React from 'react';
import { useMPWCheckout, MPWCheckoutModal } from 'mpw-checkout-react';
const CustomPayButton = () => {
const { payReference, isLoading, isOpen, orderReferenceCode } = useMPWCheckout();
const handlePayment = () => {
payReference({
orderReferenceCode: "input order reference code",
onSuccess: (data) => console.log('Payment successful', data),
onFailure: (data) => console.log('Payment failed', data),
onClose: (data) => console.log("Closed data:", data)
});
};
return (
<>
<div className='mb-3'>
<button onClick={handlePayment} disabled={isLoading}>Pay</button>
</div>
<MPWCheckoutModal isOpen={isOpen} orderReferenceCode={orderReferenceCode} />
</>
);
};
export default CustomPayButton;
API
MPWCheckoutProvider
Wraps your app and provides the checkout context. The publicKey
is optional but required if using MPWCheckout
to initiate payments.
Props
publicKey
(string, optional): Public key for the MoiPayWay gateway, required for MPWCheckout.
Example
<MPWCheckoutProvider publicKey="your-public-key">
{children}
</MPWCheckoutProvider>
useMPWCheckout
A hook that gives access to the payment state and functions such as initiatePayment
, payReference
, isOpen
, isLoading
, and more.
initiatePayment
: Starts a new payment flow with the providedrequestBody
.payReference
: Continues a payment using an existingorderReferenceCode
.
Example
const { initiatePayment, isLoading } = useMPWCheckout();
MPWCheckout
A component that initiates the payment process. It provides an easy-to-use interface for both inline and popup modes. Requires a publicKey to be passed in the provider.
Props
requestBody
: An object containing the details of the payment.onSuccess
(optional): A callback function that is called when the payment is successful.onFailure
(optional): A callback function that is called when the payment fails.onClosed
(optional): A callback function that is called when the payment modal or window is closed by clicking the close button.displayMode
(optional): "inline" or "popup". Defaults to "inline".
Example
<MPWCheckout
requestBody={requestBody}
onSuccess={handleSuccess}
onFailure={handleFailure}
displayMode="popup"
>
Pay Now
</MPWCheckout>
MPWCheckoutRef
Use this component to continue a payment that has already been initiated. An orderReferenceCode is required. No publicKey is required in the provider.
Props
orderReferenceCode
: (string): Required reference code from the initial payment.onSuccess
(optional): A callback function that is called when the payment is successful.onFailure
(optional): A callback function that is called when the payment fails.onClosed
(optional): A callback function that is called when the payment modal or window is closed by clicking the close button.displayMode
(optional): "inline" or "popup". Defaults to "inline".
Example
<MPWCheckoutRef
orderReferenceCode={"orderReferenceCode"}
onSuccess={handleSuccess}
onFailure={handleFailure}
displayMode="popup"
>
Pay Now
</MPWCheckoutRef>
MPWCheckoutModal
A modal component that displays the checkout process inline. This is necessary when using the MPWCheckout
component or when you want to have full control of the checkout process.
Props
isOpen
: Boolean to control the visibility of the modal.orderReferenceCode
: The order reference code returned from the payment initiation.
Contributing
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
License
This project is licensed under the MIT License.