mainstack-payments 0.3.3 → 0.3.4

package/README.md

@@ -1,14 +1,23 @@
-<!-- @format -->
-
-# Mainstack Payments
-
-This is a documentation of how the Mainstack Payments library works, and how to use it in your project.
-
+<!--@@joggrdoc@@-->
+<!-- @joggr:version(v2):end -->
+<!-- @joggr:warning:start -->
+<!-- 
+  _   _   _    __        __     _      ____    _   _   ___   _   _    ____     _   _   _ 
+ | | | | | |   \ \      / /    / \    |  _ \  | \ | | |_ _| | \ | |  / ___|   | | | | | |
+ | | | | | |    \ \ /\ / /    / _ \   | |_) | |  \| |  | |  |  \| | | |  _    | | | | | |
+ |_| |_| |_|     \ V  V /    / ___ \  |  _ <  | |\  |  | |  | |\  | | |_| |   |_| |_| |_|
+ (_) (_) (_)      \_/\_/    /_/   \_\ |_| \_\ |_| \_| |___| |_| \_|  \____|   (_) (_) (_)
+                                                              
+This document is managed by Joggr. Editing this document could break Joggr's core features, i.e. our 
+ability to auto-maintain this document. Please use the Joggr editor to edit this document 
+(link at bottom of the page).
+-->
+<!-- @joggr:warning:end -->
 ## Installation
 
 To install the Mainstack Payments library, you need to run the following command in your terminal:
 
-```bash
+```typescript
 yarn add mainstack-payments
 ```
 
@@ -16,7 +25,7 @@ yarn add mainstack-payments
 
 To use the Mainstack Payments library, you need to import the library into your project, and then pass a config object to `paymentConfig` prop.
 
-```jsx
+```typescript
 import { MainstackPayments } from "mainstack-payments";
 
 export default function Home() {
@@ -29,39 +38,106 @@ export default function Home() {
 }
 ```
 
+You might also want to import the MainstackPaymentsProvider in your root file if you see some styling on elements not looking appropraite.
+
+```typescriptreact
+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
-- `reference*`: Uniquely generated identifier for this 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
-- `metadata*`: An object that contains additional information about the payment. See more on this [here](#metadata)
-- `baseUrl*`: The base URL of the legacy API. This API is what is used primarily to make payments. It is used initialize, chrage and verify payment.
-- `authMSUrl*`: The base URL of the Mainstack Auth API. This API is used to get transaction fees based on the user's settings.
-- `paymentOptions`: An array of payment options that should be enabled for the user can select from. The options are 'paystack', 'startbutton', 'wallet', 'stripe'
-- `paystackRedirectUrl`: The URL to redirect to after a successful payment with Paystack or Startbutton. this is required if paystack or startbutton is enabled. More on this can be found [here](#paystackredirecturl)
-- `customizations`: This is an object that takes values for `theme_color` for the Pay button, `button_label` and `font_family` for the whole Payment page.
+* `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
+
+* `reference*`: Uniquely generated identifier for this 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
+
+* `metadata*`: An object that contains additional information about the payment. See more on this [here](#metadata)
+
+* `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 store 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.
+
+* `paymentOptions`: An array of payment options that should be enabled for the user can select from. The options are 'paystack', 'startbutton', 'wallet', 'stripe'
+
+* `paystackRedirectUrl`: The URL to redirect to after a successful payment with Paystack or Startbutton. this is required if paystack or startbutton is enabled. More on this can be found [here](#paystackredirecturl)
+
+* `customizations`: This is an object that takes values that adjust layout, styling or display of elements on the library. See full description [here](https://app.joggr.io/app/documents/b5b2ff2f-550d-4057-bed3-441870eaaf5d/edit#customizations).
 
 #### 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 Mainsatck 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
+* -`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
 
-#### paystackRedirectUrl
+* `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 `paystackRedirectUrl` is the URL to redirect to after a successful payment with Paystack or Startbutton. This page will be created by you and should contain the following code:
 
-```jsx
+```typescript
 import { useEffect } from "react";
 
 const PostMessagePage = () => {
@@ -83,31 +159,37 @@ The aim of this is to send a postMessage to the iframe that loads Startbutton or
 
 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.
-- `customForm`: This takes a ReactNode used to add a custom form to the payment page. This prop should also be used with `customFormValues`, which is an object with the initial values of the custom form, and `customFormValidation` which should contan an object with yup validation schema for the custom form. More on this can be found [here](#customform)
-- `onPaymentComplete`: This is a callback function that is called when the payment is completed.
-- `onGoBack`: This is a callback function that is called when the user clicks the back button on the payment page.
-- `onInitializePayment`: This 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 triggering your `formik.validateForm()` to validate the errors on your custom form and handle them accordingly.
+* `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.
 
-#### customForm
+* `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"**
 
-In order to update the formik values for your custom form, you can add a `ref` to the `MainstackPayments` component and call the `updateCustomFormValues` method on the ref with the new values in your onChange handler. The `updateCustomFormValues` method takes 2 arguments, the first is a string of the formik value you want to update and the second is the value you want to update it with.
+* `customForm`: This takes a ReactNode used to add a custom form to the payment page.
 
-```jsx
-import { useRef } from "react";
+* `defaultFormValues`: This is an object with `fullname` and `email` keys. Their values are passed to their respective inputs as default values.
 
-const ref = useRef(null);
+* `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.
 
-const handleChange = (e) => {
-  ref.current.updateCustomFormValues("name", e.target.value);
-};
-<MainstackPayments
-  ref={ref}
-  customForm={CustomForm}
-  customFormValues={{ name: "John Doe" }}
-  customFormValidation={customFormValidation}
-  onChange={handleChange}
-/>;
+* `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.
+
+```typescript
+      <MainstackPayments
+              paymentConfig={config}
+              onGoBack={goBack}
+              onPaymentComplete={(e) => onPaymentSuccess(e)}
+              customForm={
+                <>{customForm}</>
+              }
+              onInitializePayment={onInitPayment}
+       />
 ```
 
 > Happy Hacking !!!
+
+<!-- @joggr:editLink(b5b2ff2f-550d-4057-bed3-441870eaaf5d):start -->
+---
+<a href="https://app.joggr.io/app/documents/b5b2ff2f-550d-4057-bed3-441870eaaf5d/edit">
+  <img src="https://cdn.joggr.io/assets/static/badges/joggr-document-edit.svg?did=b5b2ff2f-550d-4057-bed3-441870eaaf5d" alt="Edit doc on Joggr" />
+</a>
+<!-- @joggr:editLink(b5b2ff2f-550d-4057-bed3-441870eaaf5d):end -->