Mainstack-payments NPM

Installation

To install the Mainstack Payments library, you need to run the following command in your terminal:

yarn add mainstack-payments

Usage

To use the Mainstack Payments library, you need to import the library into your project, and then pass a config object to paymentConfig prop.

import { MainstackPayments } from "mainstack-payments";

export default function Home() {
  const config = {};
  return (
    <Box>
      <MainstackPayment paymentConfig={config} />
    </Box>
  );
}

You might also want to import the MainstackPaymentsProvider in your root file if you see some styling on elements not looking appropraite.

const MainstackPaymentsProvider = dynamic(
  () =>
    import("mainstack-payments").then((mod) => mod.MainstackPaymentsProvider),
  {
    ssr: false,
  }
);

function MyApp({ Component, pageProps }: AppProps) {
  return (
     <ChakraProvider theme={theme}>
          <MainstackPaymentsProvider>
          </MainstackPaymentsProvider>
     </ChakraProvider>
  )
}

The config object should contain the following properties:

amount*: The amount for the product to be paid
accountId*: The account ID of the user making the payment
currency*: The currency to be used for the payment
transactionFeesSlug*: The slug of the transaction fees to be applied to the payment usually determined by the backend, e.g 'store-pro-plan'
userAllowsWalletPayment*: A boolean value that states if the merchant has allowed wallet payment
userAllowsCardPayment*: A boolean value that states if the merchant has allowed card payment
userAllowsCryptoPayment*: A boolean value that states if the merchant has allowed crypto wallet payments.
metadata*: An object that contains additional information about the payment. See more on this here
baseUrl*: The base URL of the legacy API. This API is what is used primarily to make payments. It is used initialise, charge and verify payment.
hasDiscountCode: A optional boolean to show the discount code input. Default is false.
mainstackProductId: A User's ID for a particular product, e.g store_id, bookings_id etc.
STRIPE_SECRET_KEY: Stripe secret key for stripe payments, usually stored in an env.
STRIPE_SECRET_KEY_GBP: Stripe secret key for stripe payments in GBP, usually stored in an env.
applyTrancheFee: Boolean that is passed to the transaction fees endpoint and dictates if a tranch fee should be applied for transaction fees.This is specifically for Pay In Tranches payments. Default is false.
shouldApplyTax: A boolean that determines if tax fees should be calculated and collected. Default is false.
ip: This is for the user's ip address to determine their tax fee. Only needed if you want to collect tax fees.
paymentOptions: An array of payment options that should be enabled for the user can select from. The options are 'paystack', 'startbutton', 'wallet', 'stripe', 'crypto'
paymentRedirectUrl: The URL to redirect to after a successful payment with Paystack, Startbutton or Stripe UK payments (which may require 3DS). More on this can be found here
cryptoRedirectUrl: The URL to redirect to after a successful crypto wallet payment. This is different to paymentRedirectUrl as you are fully in control of this page and should ideally be the receipt page. The following url query parameters will be added to the url from the payment library: reference : payment reference generated by mainstack, payment_intent : generated by stripe. This is required if userAllowsCryptoPayment is true.
customizations: This is an object that takes values that adjust layout, styling or display of elements on the library. See full description here.
paymentModel: string that specifies if the payment model is 'ips' or 'default'

metadata

The metadata object should contain the following properties:

-productName: The name of the product being paid for
-type: The type of product being paid for
-account_id: The account ID of the user making the payment
-user_id: The user ID of the user making the payment
-product_id: The product ID of the product being paid for
-mainstack_product_type: What Category of Mainstack Product is being paid for, accepted values are 'store', 'editor', 'bookings', 'mediakit', 'invoicing', 'hosted_courses'
[key:string] : Any other key-value pair that you want to add to the metadata object

Customizations

theme_color: custom color the the Pay button
button_label: custom label for the Pay button
font_family: To set the font family for all the payment library texts and inputs
hideDetails: Boolean that hide the summary details section of the payment library. Default is false.
hideBackButton : Boolean to remove the back button that is next to the Pay button.
isSingleColumn : This converts the payment library layout from 2 columns to a single column. Not that this happens by default on mobile screens.
padding : This can be used to adjust the surrounding padding of the payment library.
showDefaultInputFields This is an object used to determine what default input fields will be shown on the checkout form. They include:
- email : For the Email input. Default is true.
- fullname: For the Name input. Default is true.
- phone: For the PhoneNumber input. Default is false.

The paymentRedirectUrl is the URL to redirect to after a successful payment with Paystack, Startbutton or Stripe UK. This page will be created by you and should contain the following code:

import { useEffect } from "react";

const PostMessagePage = () => {
  useEffect(() => {
    (() => {
      window.parent.postMessage({ type: "Payment Completed" }, "*");
    })();
  }, []);

  return <div></div>;
};

export default PostMessagePage;

The aim of this is to send a postMessage to the iframe that loads the payment option to let them know that payment is complete and they can close the iframe and verify the payment.

Extra Props

Other Props that can be passed to the MainstackPayments component are:

summaryTitle: This takes a string or ReactNode and is used to replace the title of the payment summary section, the default is always the Product name.
checkoutTitle: This takes a string or ReactNode and is used to replace the title of the checkout form section, the default is always "Checkout Details"
customForm: This takes a ReactNode used to add a custom form to the payment page.
defaultFormValues: This is an object with fullname and email keys. Their values are passed to their respective inputs as default values.
onPaymentComplete: This is a callback function that is called when the payment is completed. It contains a payload that will include the amount, default input values, and reference of the payment, as well as some other optional data.
onGoBack: This is a callback function that is called when the user clicks the back button on the payment page.
onInitializePayment: This is an async function is called just as the payment is about to be initialized and is useful for triggering any actions before the payment is initialized, like validating your custom form or making an api call to validate something with the user's name or email before proceeding with payment. It contains an argument that has the values for the default form inputs, and must return a promise that resolves an object with a terminate boolean property. The payment initialization will terminate immediately the promise resolves depending on what the value of terminate is.

      <MainstackPayments
              paymentConfig={config}
              onGoBack={goBack}
              onPaymentComplete={(e) => onPaymentSuccess(e)}
              customForm={
                <>{customForm}</>
              }
              onInitializePayment={onInitPayment}
       />