@bigbinary/neeto-payments-frontend v1.4.16

neeto-payments-nano

The neeto-payments-nano manages payments across neeto products. The nano exports the @bigbinary/neeto-payments-frontend NPM package and neeto-payments-engine Rails engine for development.

Contents

1. Development with Host Application
   • Engine
     • Installation
     • Usage
   • Frontend package
     • Installation
     • Instructions for development
     • Components
     • Hooks
     • Functions
2. Instructions for Publishing

Development with Host Application

Engine

The engine is used to manage payments across neeto products.

Installation

1. Add this line to your application's Gemfile:

   source "NEETO_GEM_SERVER_URL" do
      # ..existing gems
   
      gem 'neeto-payments-engine'
   end

2. And then execute:

   bundle install

3. Add this line to your application's config/routes.rb file:

   mount NeetoPaymentsEngine::Engine, at: '/payments'

4. Configure the following environment variables.

   APP_URL=#Application URL
   STRIPE_PUBLISHABLE_KEY='pk_test_fnFiGXjRkMXnLkueiNKJidGU00V83aRC0V'
   STRIPE_SECRET_KEY='sk_test_eyKnYYoSDcvojBAiFoDv3QJQ00z0yOlt89'

   NB: Replace APP_URL environment variable value with the host application's base URL without a trailing slash for example: https://app.neetocal.net. Stripe environment variables values are test mode keys.

5. Run the following command to subscribe Stripe webhooks events.

   bundle exec rails neeto_payments_engine:stripe:webhooks:subscribe

   • After successful subscription, the above command will return the list of events subscribed and the details of environment variable.
   • Sample output

       *** Successfully subscribed for webhooks ***
       Please add the following environment variable
       STRIPE_WEBHOOK_SECRET='whsec_06LHs3IOmLOgEzXDm3otErje8I4Q15ME'
       ==============================================
       Subscribed events: [
          "account.updated",
          "payment_intent.payment_failed",
          "payment_intent.processing",
          "payment_intent.succeeded",
          "charge.refund.updated",
          "charge.refunded"
       ]

   • Add the returned environment variable and its value.

6. Add the following secret values to config/secrets.yml.

   host: <%= ENV['APP_URL'] || ENV['HEROKU_APP_URL'] %>
   stripe:
     publishable_key: <%= ENV['STRIPE_PUBLISHABLE_KEY'] %>
     secret_key: <%= ENV['STRIPE_SECRET_KEY'] %>
     webhooks:
       secret: <%= ENV['STRIPE_WEBHOOK_SECRET'] %>

7. Add the following line to application's config/initializer/neeto_payments_engine.rb file. Replace the holdable_class value with a model name where you want to associate your Stripe account in the host application.

   NeetoPaymentsEngine.holdable_class = "Organization"

8. Add the following association to the model you defined as holdable_class in step 7.

   has_one :stripe_integration, class_name: "::NeetoPaymentsEngine::Stripe::Account", foreign_key: :holdable_id

9. Add the following association to the chargeable model. The chargeable model is the model in the host application which needs to charge for its service. For example Meeting model in neetoCal where meeting service is a chargeable one.

   has_one :charge, as: :chargeable, class_name: "::NeetoPaymentsEngine::Stripe::Charge", dependent: :destroy

10. Add the following association to the payable model.

    has_one :payment, as: :payable, class_name: "::NeetoPaymentsEngine::Stripe::Transaction", dependent: :destroy

11. Add the following queue to your sidekiq config file config/sidekiq.yml

    queues:
      - payment # For neeto-payments-engine

Usage

You can learn more about setup and usage here: 1. Services

Frontend package

Installation

1. Install the latest neeto-payments-frontend package using the below command:

   yarn add @bigbinary/neeto-payments-frontend

2. neeto-payments-frontend has a few peer dependencies that are required for the proper functioning of the package. Install all the peer dependencies using the below command:

   yarn add @bigbinary/neeto-commons-frontend@2.0.54 @bigbinary/neeto-filters-frontend@2.8.1 @bigbinary/neeto-icons@1.9.22 @bigbinary/neeto-molecules@1.0.9 @bigbinary/neetoui@4.4.10 @honeybadger-io/js@5.1.1 @honeybadger-io/react@5.1.3 axios@1.3.4 classnames@2.3.2 formik@2.2.9 js-logger@1.6.1 mixpanel-browser@2.45.0 ramda@0.28.0 react-helmet@6.1.0 react-query@3.39.3 react-router-dom@5.3.4 react-toastify@8.2.0 yup@1.0.2

Instructions for development

Check the Frontend package development guide for step-by-step instructions to develop the frontend package.

Components

1. Dashboard (source code)

Props

• holdableId: To specify the ID of the entity that holds the stripe account. This is an optional prop. If the value is not specified, the current organization ID is taken as the default value while querying for transactions.
• payableEntityColumns: To specify the columns from the payable entity which need to be additionally displayed. It is an optional prop that defaults to [] if not specified.
• tabs: To specify the tabs to be displayed in the payments dashboard. It is an optional parameter.
• headerProps: To specify the props to be passed to the neetoUI Header component used in the Dashboard.

Configuration

• Refer to the Dashboard section for detailed information on the available configurations for the Dashboard component.

Usage

import React, { useState } from "react";
import { Dashboard } from "@bigbinary/neeto-payments-frontend";

const App = () => {
  const headerProps = {
    className: "w-80",
    // Your header properties
  };

  return (
    <Dashboard
      tabs={["all", "successful"]}
      headerProps={headerProps}
    />
  );
};

export default App;

2. PaymentKindRestrictionAlert (source code)

Props

• isOpen: To specify whether the Stripe connect restriction alert should be opened or closed.
• paymentKind: To specify the type of Stripe payment kind for rendering related content to alert either as "standard" or "platform". If Stripe Standard is connected the alert shall forbid Stripe Platform connect and vice versa.
• onClose: Handler function that is triggered when the disconnect button is clicked.

Usage

import React, { useState } from "react";
import { PaymentKindRestrictionAlert } from "@bigbinary/neeto-payments-frontend";

const App = () => {
  const [isStripePlatformConnectedAlertOpen, setIsStripePlatformConnectedAlertOpen] = useState(false);

  return (
    <PaymentKindRestrictionAlert
      isOpen={isStripePlatformConnectedAlertOpen}
      paymentKind="standard"
      onClose={() => setIsStripePlatformConnectedAlertOpen(false)}
    />
  );
};

export default App;

3. SquareCard (source code)

Props

• card: The Square card instance.
• setCard: Function to set the Square card instance.

Optional Props

• onChange: Event handler function triggered on Square card events.
• id: ID of the container element for the Square card. Defaults to square-card-container.
• options: Configuration options for the Square card. Defaults to {}.
• disabled: Disables pointer events if set to true. Defaults to false.

Usage

import React, { useState } from "react";
import { SquareCard } from "@bigbinary/neeto-payments-frontend";

const App = () => {
  const [squareCard, setSquareCard] = useState(null);
  const handleCardChange = event => {
    // Handle Square card events
  };

  return (
    <SquareCard
      card={squareCard}
      setCard={setSquareCard}
      onChange={handleCardChange}
      disabled={false}
    />
  );
};

export default App;

4. PayoutsDashboard (source code)

Props

• payoutsPageRoute: The route for the payouts page.
• isPlatformEnabled: Indicates whether the platform is enabled or not.

Usage

import React from "react";
import { PayoutsDashboard } from "@bigbinary/neeto-payments-frontend";

const App = () => {
  return (
    <PayoutsDashboard
      isPlatformEnabled
      payoutsPageRoute={routes.admin.payment.stripePayouts.show}
    />
  );
};

export default App;

5. SquareDashboard (source code)

Props

• searchProps: To specify the search props to be passed to the neetoUI Header component used in the Dashboard.

Optional Props

• holdableId: To specify the ID of the entity that holds the stripe account. If the value is not specified, the current organization ID is taken as the default value while querying for transactions.
• payableEntityColumns: To specify the columns from the payable entity which need to be additionally displayed. Defaults to [].
• kind: To specify the type of payment. Defaults to squarePayment.
• headerProps: To specify the props to be passed to the neetoUI Header component used in the Dashboard. Defaults to {}.

Usage

import React from "react";
import { SquareDashboard } from "@bigbinary/neeto-payments-frontend";

const App = () => {
   const searchProps = {
    placeholder: "Search...",
  };

  const headerProps = {
    className: "w-80",
    // Your header properties
  };
  return (
     <SquareDashboard
        searchProps={searchProps}
        headerProps={headerProps}
        kind="squarePayment"
        payableEntityColumns=[]
     />
  );
};

export default App;

Hooks

1. useStripePromise (source code)

• This hook is used to generate the stripePromise object to be passed to the stripe <Elements> context. The useStripePromise hook takes a stripe account identifier as input and returns a Promise.
• Usage in neetoForm.

:memo: Note: STRIPE_PUBLISHABLE_KEY environment variable must be present for this hook to work.

Usage

  const stripeAccountIdentifier = "acct_1Mtqtz2e5McIywz4";
  const stripePromise = useStripePromise(stripeAccountIdentifier);
  ...
  <Elements stripe={stripePromise}>
    <CardElement />
  </Elements>

2. useSquareCard (source code)

• This hook manages the state and functionality related to the Square card instance, providing methods for setting the card, accessing the current card instance, and tokenizing the card.
• Usage in neetoInvoice.

Returns

• card: The Square card instance.
• setCard: Function to set the Square card instance.
• tokenizeCard: Asynchronous function to tokenize the Square card instance. It returns a Promise that resolves to the tokenized card. If no card instance is found, a warning is logged, and an empty string is returned. If tokenization is successful, the token is returned. In case of errors during tokenization, an error is logged, and an empty string is returned.

Usage

  const { card, setCard, tokenizeCard } = useSquareCard();

Functions

1. buildStripeTransactionLink (source code)

• This function is used to generate the stripe transaction link from payment identifier.

Parameters 1. identifier: The payment identifier. 2. isLive: Specifying whether or not the environment is live. It defaults to true.

Usage

const transactionLink = buildStripeTransactionLink(
  "pi_3MqWX92fKivMPpZ11EPmOBBR",
  false
);

Instructions for Publishing

Consult the building and releasing packages guide for details on how to publish.