@bigbinary/neeto-payments-frontend 3.3.22 → 3.3.24

package/README.md

@@ -1,295 +1,1127 @@
 # 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](#development-with-host-application)
-    - [Engine](#engine)
-        - [Installation](#installation)
-        - [Usage](#usage)
-    - [Frontend package](#frontend-package)
-        - [Installation](#installation-1)
-        - [Instructions for development](#instructions-for-development)
-        - [Components](#components)
-        - [Hooks](#hooks)
-        - [Functions](#functions)
-2. [Instructions for Publishing](#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:
-    ```ruby
-    source "NEETO_GEM_SERVER_URL" do
-       # ..existing gems
 
-       gem 'neeto-payments-engine'
-    end
+The `neeto-payments-nano` is a comprehensive payment processing solution designed for the Neeto ecosystem. Implemented as a Ruby on Rails engine with associated React frontend components (`@bigbinary/neeto-payments-frontend`), it provides a unified interface for managing payments across different providers, abstracting away provider-specific complexities.
+
+This engine enables host applications to:
+
+-   Integrate with multiple payment providers (Stripe, Razorpay, UPI).
+-   Process payments.
+-   Handle payment splits for marketplace scenarios (Stripe).
+-   Manage refunds.
+-   Store and reuse payment methods securely (optional).
+-   Configure fee structures and apply taxes/discounts.
+-   Provide administrative dashboards for monitoring transactions, refunds, payouts, and accounts.
+
+# Table of Contents
+
+-   [Installation (Backend Engine)](#installation-backend-engine)
+    -   [1. Add the Gem](#1-add-the-gem)
+    -   [2. Install Gems](#2-install-gems)
+    -   [3. Install Migrations](#3-install-migrations)
+    -   [4. Run Migrations](#4-run-migrations)
+    -   [5. Mount the Engine](#5-mount-the-engine)
+-   [Configuration (Backend Engine)](#configuration-backend-engine)
+    -   [1. Initializer](#1-initializer)
+    -   [2. Model Associations](#2-model-associations)
+    -   [3. Secrets and Credentials](#3-secrets-and-credentials)
+    -   [4. Stripe Connect Signup](#4-stripe-connect-signup)
+    -   [5. OAuth Callback URI Registration](#5-oauth-callback-uri-registration)
+-   [Frontend Integration](#frontend-integration)
+    -   [1. Install Frontend Package](#1-install-frontend-package)
+    -   [2. Install Peer Dependencies](#2-install-peer-dependencies)
+    -   [3. Components](#3-components)
+    -   [4. Hooks](#4-hooks)
+    -   [5. Constants](#5-constants)
+    -   [6. API Calls - Specify Providers](#4-api-calls---specify-providers)
+-   [Core Concepts](#core-concepts)
+-   [Webhook Handling](#webhook-handling)
+    -   [Development Environment Setup](#development-environment-setup)
+        -   [1. Tunneling](#1-tunneling)
+        -   [2. Stripe Webhook Setup (Manual)](#2-stripe-webhook-setup-manual)
+        -   [3. Razorpay Webhook Setup (Manual)](#3-razorpay-webhook-setup-manual)
+-   [Authentication (JWT for OAuth)](#authentication-jwt-for-oauth)
+-   [Callbacks](#callbacks)
+    -   [Mandatory Callbacks](#mandatory-callbacks)
+    -   [Optional Callbacks (Implement as needed)](#optional-callbacks-implement-as-needed)
+-   [Exposed Entities](#exposed-entities)
+-   [API Endpoints](#api-endpoints)
+-   [Incineration Concern](#incineration-concern)
+-   [Deprecated Patterns](#deprecated-patterns)
+-   [Development Environment Setup](#development-environment-setup-1)
+-   [Helper methods](#helper-methods)
+-   [Testing & Debugging](#testing--debugging)
+-   [Gotchas & Tips](#gotchas--tips)
+-   [Publishing](#publishing)
+
+## Installation (Backend Engine)
+
+Follow these steps to integrate the `neeto-payments-engine` into your host Rails application:
+
+### 1. Add the Gem
+Add the gem to your application's `Gemfile`:
+```ruby
+# Gemfile
+source "NEETO_GEM_SERVER_URL" do
+  gem "neeto-payments-engine"
+end
+```
+
+### 2. Install Gems
+Run bundler to install the gem and its dependencies:
+```bash
+bundle install
+```
+
+### 3. Install Migrations
+Copy the engine's database migrations into your host application. **This step is crucial.**
+```bash
+bundle exec rails neeto_payments_engine:install:migrations
+```
+
+### 4. Run Migrations
+Apply the migrations to your database:
+```bash
+bundle exec rails db:migrate
+```
+
+### 5. Mount the Engine
+Add the engine's routes to your application's `config/routes.rb`:
+```ruby
+# config/routes.rb
+mount NeetoPaymentsEngine::Engine, at: "/payments" # Or your preferred mount point
+```
+This makes the engine's API endpoints available, by default under `/payments`.
+
+Once the installation is done, we have to do some configuration for the engine to work as intended. Please go through the whole README to complete the process of setting up `neeto-payments-nano` in your host app.
+
+## Configuration (Backend Engine)
+
+### 1. Initializer
+Create an initializer file `config/initializers/neeto_payments_engine.rb` to configure the engine:
+
+```ruby
+# config/initializers/neeto_payments_engine.rb
+NeetoPaymentsEngine.is_card_preserving_enabled = false # Set to true to enable saving payment methods
+
+# IMPORTANT: Configure which model holds the payment integration for each provider.
+# Replace "Organization" or "User" with your actual model names.
+# This configuration is MANDATORY.
+NeetoPaymentsEngine.providers_holdable_class = {
+  stripe_standard: "Organization", # e.g., Organization or User that owns the Stripe Standard account
+  stripe_platform: "Organization", # Typically Organization that owns the Stripe Platform account
+  razorpay: "Organization",        # e.g., Organization or User that owns the Razorpay account
+  upi: "Organization"              # Typically Organization that owns the UPI VPA list
+}
+```
+-   **`providers_holdable_class`:** This hash maps each payment provider type supported by the engine to the class name (as a String) of the model in your host application that will "hold" or own the integration for that provider. The engine uses polymorphic associations (`holdable_type`, `holdable_id`) based on this setting to link payment provider accounts (like `Stripe::Account`, `Integrations::Razorpay`) to your application's models. Failing to configure this correctly will result in errors when the engine attempts to find or create payment provider integrations. Example: In NeetoCal each `User` can connect their own `stripe_standard` account, but in NeetoPay, only one `stripe_standard` account can exist in an `Organization`.
+
+### 2. Model Associations
+Ensure the models specified in `providers_holdable_class` have the correct `has_one` or `has_many` associations defined to link to the engine's integration models. Adapt the following examples based on your configuration:
+
+```ruby
+# app/models/organization.rb (Example if Organization is a holdable)
+class Organization < ApplicationRecord
+  # If Organization holds Stripe Standard Connect account(s)
+  has_one :stripe_connected_account, -> { where(payment_provider: :stripe_standard) }, class_name: "::NeetoPaymentsEngine::Stripe::Account", as: :holdable, dependent: :destroy
+  # OR if one Org can hold many standard accounts (less common)
+  # has_many :stripe_connected_accounts, -> { where(payment_provider: :stripe_standard) }, class_name: "::NeetoPaymentsEngine::Stripe::Account", as: :holdable, dependent: :destroy
+
+  # We have to add this association no matter what because
+  # it's internally required by the engine. Change the parent association
+  # to Organization/User/Whatever depending on your host app.
+  has_one :stripe_platform_account, class_name: "::NeetoPaymentsEngine::Stripe::PlatformAccount", inverse_of: :organization, dependent: :destroy
+
+  # If Organization holds the Razorpay account
+  has_one :razorpay_integration, -> { where(payment_provider: :razorpay) }, class_name: "::NeetoPaymentsEngine::Integration", as: :holdable, dependent: :destroy
+
+  # If Organization holds the UPI VPAs list
+  has_one :upi_integration, -> { where(payment_provider: :eupi) }, class_name: "::NeetoPaymentsEngine::Integration", as: :holdable, dependent: :destroy
+
+  # General association (optional, can be useful)
+  has_many :payment_integrations, class_name: "::NeetoPaymentsEngine::Integration", as: :holdable, dependent: :destroy
+
+  # If Organization itself can have fees associated
+  has_one :fee, class_name: "::NeetoPaymentsEngine::Fee", as: :feeable, dependent: :destroy
+  has_one :split, class_name: "::NeetoPaymentsEngine::Split", dependent: :destroy # If Org defines platform split %
+end
+
+# app/models/user.rb (Example if User is a holdable for Stripe Standard)
+class User < ApplicationRecord
+  has_one :stripe_connected_account, -> { where(payment_provider: :stripe_standard) }, class_name: "::NeetoPaymentsEngine::Stripe::Account", as: :holdable, dependent: :destroy
+  # Add other associations if User can hold other provider accounts
+end
+```
+
+Add associations to your **Payable** models (e.g., `Invoice`, `Booking`, `Meeting` - the item being paid for) - you don't need to add this until you create your `Payable` models in your host app:
+```ruby
+# app/models/invoice.rb (Example Payable Model)
+class Invoice < ApplicationRecord
+  # Association to the payment record for this invoice
+  has_one :payment, class_name: "::NeetoPaymentsEngine::Payment", as: :payable, dependent: :destroy
+
+  # Optional: If fees are directly configured on the payable item itself
+  has_one :fee, class_name: "::NeetoPaymentsEngine::Fee", as: :feeable, dependent: :destroy
+end
+```
+
+### 3. Secrets and Credentials
+Configure API keys and secrets securely using environment variables and secrets file.
+
+**Essential ENV variables for `neeto-payments-engine`:**
+
+*   **`.env.development` (Commit this file):** Contains non-sensitive defaults, placeholders, or development-specific configurations.
+    ```dotenv
+    # .env.development
+
+    # Base URL of your host application (adjust port if needed)
+    APP_URL='http://app.lvh.me:<APP_PORT>/'
+
+    # --- Stripe ---
+    # Base URL for OAuth callback (using tunnelto 'connect' subdomain for dev)
+    STRIPE_CALLBACK_BASE_URL="https://connect.tunnelto.dev" # Or your tunnel URL
+
+    # --- Razorpay (if used) ---
+    RAZORPAY_CLIENT_SECRET="rzp_test_..." # Test Key ID can often be committed
+    RAZORPAY_CLIENT_ID="..."      # OAuth Client ID is usually safe
+    RAZORPAY_WEBHOOK_SECRET=".." # webhook secret
+    RAZORPAY_CALLBACK_BASE_URL="https://connect.tunnelto.dev" # Or your tunnel URL
     ```
-2. And then execute:
-    ```zsh
-    bundle install
+
+*   **`.env.local` (Add this file to `.gitignore` - DO NOT COMMIT):** Contains sensitive API keys, secrets, and private keys. This file overrides values in `.env.development`.
+
+    ```dotenv
+    # .env.local (DO NOT COMMIT THIS FILE)
+
+    # --- Stripe ---
+    STRIPE_SECRET_KEY="sk_test_..." # Your TEST Stripe Secret Key
+    STRIPE_WEBHOOK_SECRET="whsec_..." # Your TEST Stripe Webhook Signing Secret (from manual setup)
+    # Can find this from Stripe dashboard
+    STRIPE_PUBLISHABLE_KEY="pk_test_..."
+    # First sign up for Stripe Connect, then go to OAuth section of Stripe
+    # Connect to get the client id. You'd also have to register OAuth callback
+    # URI in that page.
+    STRIPE_CLIENT_ID="ca_..."
+
+    # --- Razorpay (if used) ---
+    RAZORPAY_KEY_SECRET="..."          # Your TEST Razorpay Key Secret
+    RAZORPAY_WEBHOOK_SECRET="..."      # Your TEST Razorpay Webhook Secret (you set this)
+    RAZORPAY_CLIENT_SECRET="..."       # Your TEST Razorpay OAuth Client Secret
+
+    # --- JWT Keys ---
+    # Generate using: openssl genrsa -out private.pem 2048 && openssl rsa -in private.pem -pubout -out public.pem
+    # Copy the *entire* content including -----BEGIN...----- and -----END...----- lines.
+    CONNECT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
+    ...your private key content...
+    -----END RSA PRIVATE KEY-----"
+    CONNECT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
+    ...your public key content...
+		-----END PUBLIC KEY-----"
+
+    # --- Optional ---
+    # OPEN_EXCHANGE_RATE_API_KEY="your_actual_key" # Sensitive API key
     ```
-3. Add this line to your application's `config/routes.rb` file:
-    ```ruby
-    mount NeetoPaymentsEngine::Engine, at: '/payments'
+
+    **Loading Secrets:** Ensure these secrets are loaded into `Rails.application.secrets`. An example `config/secrets.yml` structure:
+
+    ```yaml
+    # config/secrets.yml
+    default: &default
+      host: <%= ENV['APP_URL'] %>
+      stripe:
+        publishable_key: <%= ENV['STRIPE_PUBLISHABLE_KEY'] %>
+        secret_key: <%= ENV['STRIPE_SECRET_KEY'] %>
+        client_id: <%= ENV['STRIPE_CLIENT_ID'] %>
+        webhooks:
+          secret: <%= ENV['STRIPE_WEBHOOK_SECRET'] %>
+      razorpay:
+        key_id: <%= ENV["RAZORPAY_KEY_ID"] %>
+        key_secret: <%= ENV["RAZORPAY_KEY_SECRET"] %>
+        client_id: <%= ENV["RAZORPAY_CLIENT_ID"] %>
+        client_secret: <%= ENV["RAZORPAY_CLIENT_SECRET"] %>
+        oauth_callback_base_url: <%= ENV["RAZORPAY_CALLBACK_BASE_URL"] %>
+        webhook:
+          secret: <%= ENV["RAZORPAY_WEBHOOK_SECRET"] %>
+      jwt:
+        connect_private_key: <%= ENV['CONNECT_PRIVATE_KEY'].inspect %>
+        connect_public_key: <%= ENV['CONNECT_PUBLIC_KEY'].inspect %>
+
+      # Optional: If using Open Exchange Rates for currency conversion
+      open_exchange_rates:
+	      api_key: <%= ENV["OPEN_EXCHANGE_RATE_API_KEY"] %>
+      # ... other secrets ...
+
+    development:
+      <<: *default
+      # Development specific overrides
+
+    production:
+      <<: *default
+      # Production specific overrides (use credentials!)
     ```
-4. Configure the following environment variables.
-   ```yaml
-   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.
-   ```shell
-   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`.
-   ```yaml
-   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.
-   ```ruby
-   NeetoPaymentsEngine.holdable_class = "Organization"
-   ```
-8. Add the following association to the model you defined as holdable_class in
-   step 7.
-   ```ruby
-   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.
-   ```ruby
-   has_one :charge, as: :chargeable, class_name: "::NeetoPaymentsEngine::Stripe::Charge", dependent: :destroy
-   ```
-10. Add the following association to the payable model.
-    ```ruby
-    has_one :payment, as: :payable, class_name: "::NeetoPaymentsEngine::Stripe::Transaction", dependent: :destroy
+
+    **Secrets Management:**
+    -   **Development:** Use `.env.local` (which is typically gitignored) to store sensitive keys locally.
+    -   **Staging/Production:** Use environment variables managed by your deployment platform (e.g., NeetoDeploy, Heroku Config Vars) or Rails encrypted credentials. **Do not commit secrets directly into your repository.**
+
+### 4. Stripe Connect Signup
+You **must** sign up for Stripe Connect via the Stripe dashboard, even if you only intend to use a Stripe Platform account. This registration enables the necessary APIs for account management and OAuth flows used by the engine.
+
+### 5. OAuth Callback URI Registration
+Register the following callback URIs in your respective payment provider dashboards:
+*   **Stripe:** `https://<your_connect_subdomain_or_app_domain>/payments/api/v1/public/stripe/oauth/callback`
+    *   `<your_connect_subdomain_or_app_domain>`: This should be the publicly accessible URL that routes to your Rails app. In development, this is typically your `tunnelto` URL using the `connect` subdomain (e.g., `https://connect.tunnelto.dev`). In production, it might be your main application domain or a dedicated subdomain.
+*   **Razorpay:** `https://<your_razorpay_oauth_base_url>/payments/api/v1/public/razorpay/oauth/callback`
+    *   `<your_razorpay_oauth_base_url>`: This must match the value you configured for `RAZORPAY_OAUTH_CALLBACK_BASE_URL`. Use the `connect` subdomain via `tunnelto` in development.
+
+## Frontend Integration
+
+Integrate the React components provided by the `@bigbinary/neeto-payments-frontend` package.
+
+### 1. Install Frontend Package
+```bash
+yarn add @bigbinary/neeto-payments-frontend
+```
+
+### 2. Install Peer Dependencies
+If the host app already includes all of the following peer deps, then you don't have to install anything explicitly. Use the latest version of each of these peer dependencies if you need to install:
+```bash
+# DO NOT INSTALL THE VERSIONS MENTIONED BELOW AS IT MIGHT BE OUTDATED.
+# ALWAYS PREFER INSTALLING THE LATEST VERSIONS.
+# If something isn't working, then refer to these versions and see
+# what's causing the breakage.
+yarn add @babel/runtime@7.26.10 @bigbinary/neeto-cist@1.0.15 @bigbinary/neeto-commons-frontend@4.13.28 @bigbinary/neeto-editor@1.45.23 @bigbinary/neeto-filters-frontend@4.3.15 @bigbinary/neeto-icons@1.20.31 @bigbinary/neeto-molecules@3.16.1 @bigbinary/neetoui@8.2.75 @honeybadger-io/js@6.10.1 @honeybadger-io/react@6.1.25 @tailwindcss/container-queries@^0.1.1 @tanstack/react-query@5.59.20 @tanstack/react-query-devtools@5.59.20 antd@5.22.0 axios@1.8.2 buffer@^6.0.3 classnames@2.5.1 crypto-browserify@3.12.1 dompurify@^3.2.4 formik@2.4.6 https-browserify@1.0.0 i18next@22.5.1 js-logger@1.6.1 mixpanel-browser@^2.45.0 os-browserify@0.3.0 path-browserify@^1.0.1 qs@^6.11.2 ramda@0.29.0 react@18.2.0 react-dom@18.2.0 react-helmet@^6.1.0 react-i18next@12.3.1 react-router-dom@5.3.3 react-toastify@8.0.2 source-map-loader@4.0.1 stream-browserify@^3.0.0 stream-http@3.2.0 tailwindcss@3.4.14 tty-browserify@0.0.1 url@^0.11.0 util@^0.12.5 vm-browserify@1.1.2 yup@0.32.11 zustand@4.3.2
+```
+*Note: Carefully manage potential version conflicts with your host application.*
+
+### 3. Components
+Import components into your React application as needed.
+
+ 1. `TaxesDashboard` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/main/app/javascript/src/components/TaxesDashboard/index.jsx))
+
+    **Props**
+    - `feeId`: The unique identifier for the tax fee.
+    - `breadcrumbs`: Data for rendering the header breadcrumbs.
+    - `paymentUrl` _(optional)_: The URL of the pricing page to redirect users if payments are not enabled.
+    - `headerSize` _(optional)_: Specifies the size of the header. Default size is `small`
+    - `noDataHelpText` _(optional)_: Help text displayed when there is no data available.
+    - `onTaxesChange` _(optional)_: Callback function triggered after performing actions in the taxes dashboard.
+    - `titleHelpPopoverProps`_(optional)_: Data for the header help popover.
+
+    **Usage**
+    ```jsx
+    import React from "react";
+    import { TaxesDashboard } from "@bigbinary/neeto-payments-frontend";
+
+    const App = () => {
+      return (
+        <TaxesDashboard
+          feeId={fee.id}
+          breadcrumbs={[{text: "Settings" ,link: routes.admin.form.settings}]}
+        />
+      );
+    };
     ```
-11. Add the following queue to your sidekiq config file `config/sidekiq.yml`
-    ```yaml
-    queues:
-      - payment # For neeto-payments-engine
+
+2. `PaymentsDashboard` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/main/app/javascript/src/components/PaymentsDashboard/index.jsx))
+
+    **Props**
+    - `dashboardKind`: Accepts either `connected` or `platform` (default: `platform`). Use `connected` to display payments related to split transfers. Use `platform` to display payments received from customers.
+    - `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.
+    - `searchProps`: Allows specifying additional columns to be included in the search functionality. By default, only the `identifier` column from the payments table is searchable.
+    - `holdableIds`: Provide the holdable IDs for each payment provider when the holdable entity is not a `User` or `Organization` model.
+
+    **Usage**
+    ```jsx
+    import React from "react";
+    import { PaymentsDashboard } from "@bigbinary/neeto-payments-frontend";
+
+    const App = () => {
+
+      // neeto-filters-engine search prop syntax.
+      const SEARCH_PROPS = {
+        node: "bookings:payable.meeting.name",
+        model: "Meeting",
+        placeholder: "Search by identifier or meeting name",
+      };
+
+      // Only required if the payment provider holdable modal is not a User or Organization
+      const holdableIds = { stripeStandard: formId, razorpay: formId }
+
+      const payableEntityColumns =   {
+        title: "Submission",
+        dataIndex: ["payable", "id"],
+        key: "submission",
+        ellipsis: true,
+        width: "300px",,
+      },
+
+      return (
+        <PaymentsDashboard
+          {...{ payableEntityColumns, holdableIds }}
+          searchProps={SEARCH_PROPS}
+        />
+      );
+    };
     ```
+3. `RefundsDashboard` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/main/app/javascript/src/components/RefundsDashboard/index.jsx))
 
-### Usage
-You can learn more about setup and usage here:
-  1. [Services](/docs/engine/services.md)
-  2. [Stripe integration](/docs/engine/stripe_integrations.md)
-  2. [Razorpay integration](/docs/engine/razorpay_integrations.md)
-  3. [Stripe payment](/docs/engine/stripe_payment.md)
-  4. [Razorpay payment](/docs/engine/razorpay_payment.md)
-
-## Frontend package
-### Installation
-1. Install the latest `neeto-payments-frontend` package using the below command:
-   ```zsh
-   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:
-   ```zsh
-   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](https://neeto-engineering.neetokb.com/p/a-d34cb4b0) for step-by-step instructions to develop the frontend package.
-
-### Components
-#### 1. `Dashboard` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/42ad8330442696b102d8555930162d75cf94931e/app/javascript/src/components/Dashboard/index.jsx))
-
-**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](/docs/frontend/dashboard.md) section for detailed information on the available configurations for the `Dashboard` component.
-
-**Usage**
-```jsx
-import React, { useState } from "react";
-import { Dashboard } from "@bigbinary/neeto-payments-frontend";
-
-const App = () => {
-  const headerProps = {
-    className: "w-80",
-    // Your header properties
-  };
+    **Props**
+    - `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.
+    - `searchProps`: Allows specifying additional columns to be included in the search functionality. By default, only the `identifier` column from the refunds table is searchable.
 
-  return (
-    <Dashboard
-      tabs={["all", "successful"]}
-      headerProps={headerProps}
-    />
-  );
-};
+   **Usage**
+    ```jsx
+    import React from "react";
+    import { SplitTransfersDashboard } from "@bigbinary/neeto-payments-frontend";
+
+    const App = () => {
+
+      // neeto-filters-engine search prop syntax.
+      const SEARCH_PROPS = {
+        node: "bookings:payable.meeting.name",
+        model: "Meeting",
+        placeholder: "Search by identifier or meeting name",
+      };
+
+      const payableEntityColumns =   {
+        title: "Submission",
+        dataIndex: ["payable", "id"],
+        key: "submission",
+        ellipsis: true,
+        width: "300px",,
+      },
+
+      return (
+        <SplitTransfersDashboard
+          {...{ payableEntityColumns }}
+          searchProps={SEARCH_PROPS}
+        />
+      );
+    };
+    ```
+
+4. `SplitTransfersDashboard` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/main/app/javascript/src/components/SplitTransfersDashboard/index.jsx))
+
+    **Props**
+    - `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.
+    - `searchProps`: Allows specifying additional columns to be included in the search functionality. By default, only the `identifier` column from the payment splits table is searchable.
+   **Usage**
+    ```jsx
+    import React from "react";
+    import { RefundsDashboard } from "@bigbinary/neeto-payments-frontend";
+
+    const App = () => {
+
+      // neeto-filters-engine search prop syntax.
+      const SEARCH_PROPS = {
+        node: "bookings:payable.meeting.name",
+        model: "Meeting",
+        placeholder: "Search by identifier or meeting name",
+      };
+
+      const payableEntityColumns =   {
+        title: "Submission",
+        dataIndex: ["payable", "id"],
+        key: "submission",
+        ellipsis: true,
+        width: "300px",,
+      },
+
+      return (
+        <RefundsDashboard
+          {...{ payableEntityColumns }}
+          searchProps={SEARCH_PROPS}
+        />
+      );
+    };
+    ```
+
+
+5. `AccountsDashboard` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/main/app/javascript/src/components/AccountsDashboard/index.jsx))
+
+   **Usage**
+    ```jsx
+    import React from "react";
+    import { AccountsDashboard } from "@bigbinary/neeto-payments-frontend";
+
+    const App = () => {
+
+      return (<AccountsDashboard />);
+    };
+    ```
+
+6. `PayoutsDashboard` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/main/app/javascript/src/components/PayoutsDashboard/index.jsx))
+
+    **Props**
+      - `isPlatformEnabled`: Indicates whether platform integration is enabled.
+      - `payoutsPageRoute`: The route used to display detailed payout information.
+
+
+   **Usage**
+    ```jsx
+    import React from "react";
+    import { PayoutsDashboard } from "@bigbinary/neeto-payments-frontend";
+
+    const App = () => {
+
+      return (
+        <PayoutsDashboard
+          isPlatformEnabled={true}
+          payoutsPageRoute={routes.admin.payments.payouts.show}
+        />
+      );
+    };
+    ```
+7. `RazorpayPaymentButton` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/main/app/javascript/src/components/RazorpayPaymentButton.jsx))
+
+    **Props**
+    - `label`: The button label. Defaults to `Pay`.
+    - `payableId`: The ID of the payable entity.
+    - `discountCode`: The discount code to be applied, if any.
+    - `email`: The customer's email address.
+    - `name`: The customer's name.
+    - `theme`: The theme configuration object.
+    - `payableType`: The type of the payable entity.
+    - `onBeforePayment`: A callback function triggered before the payment is initiated.
+    - `onSuccessfulPayment`: A callback function triggered after a successful payment.
+    - `onFailedPayment`: A callback function triggered after a failed payment.
+
+   **Usage**
+    ```jsx
+    import React from "react";
+    import { RazorpayPaymentButton } from "@bigbinary/neeto-payments-frontend";
+
+    const App = () => {
+
+      return (
+        <RazorpayPaymentButton
+          email={customer.email}
+          name={customer.name}
+          discountCode={discountCode.code}
+          payableId={booking.id}
+          theme={meeting.theme}
+        />
+      );
+    };
+    ```
+
+8. `ConfirmUpiPaymentButton` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/main/app/javascript/src/components/ConfirmUpiPaymentButton/index.jsx))
+
+    **Props**
+    - `vpas`: A list of UPI IDs presented for the user to select during confirmation.
+    - `identifier`: The unique identifier associated with the payment.
+    - `paymentId`: The ID of the payment.
+    - `onSuccess`: A callback function triggered upon successful confirmation.
 
-export default App;
+    **Usage**
+
+    ```jsx
+    import React from "react";
+    import { ConfirmUpiPaymentButton } from "@bigbinary/neeto-payments-frontend";
+
+    const App = () => {
+
+      return (
+          <ConfirmUpiPaymentButton
+            identifier={payment.identifier}
+            payableId={payment.payableId}
+            paymentId={payment.paymentId}
+            vpas={meeting.fee.vpas}
+          />
+      );
+    };
+    ```
+
+### 4. Hooks
+
+1. `useStripePromise` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/main/app/javascript/src/hooks/useStripePromise.js))
+
+    This hook can used to provide the value for the `stripe` prop of the Stripe `Element` component.
+
+    **Usage**
+
+    ```jsx
+    import React from "react";
+    import { useStripePromise } from "@bigbinary/neeto-payments-frontend";
+
+    const App = () => {
+
+      const stripePromise = useStripePromise({
+        stripePlatformAccount // The integration object for the Stripe platform account. No value is required if the platform account integration is not configured.
+
+        stripeAccountIdentifier: paymentRecipient?.stripeConnectedAccount?.identifier, // Stripe Standard account integration identifier
+      });
+
+      return (
+          <Elements stripe={stripePromise}>
+          </Elements>
+      );
+    };
+    ```
+2. `useRazorpayPayment` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/main/app/javascript/src/hooks/useRazorpayPayment.js))
+
+    This hook returns a function that can be used to initiate a Razorpay payment. Use it only if you want to trigger the payment flow through a custom button in the host application.
+
+
+    **Usage**
+
+    ```jsx
+    import React from "react";
+    import { useRazorpayPayment } from "@bigbinary/neeto-payments-frontend";
+
+    const App = () => {
+
+      const { makePayment } = useRazorpayPayment({
+        payableId, // The ID of the payable entity.
+        onBeforePayment, // A callback function triggered before the payment is initiated.
+        onSuccessfulPayment, //  A callback function triggered after a successful payment.
+        onFailedPayment, // A callback function triggered after a failed payment.
+        customAmount, // The custom amount value to be used when a fee of type `range` or `variable` is configured.
+
+      });
+
+    };
+    ```
+
+### 5. constants
+
+1. CURRENCY_OPTIONS
+
+    A list of supported currencies in `{ value, label }` format. This can be used as options for the NeetoUI `Select` component.
+
+### 6. Others
 ```
+// Example: Payment Settings Page
+import React, { useState, useEffect } from 'react';
+import axios from 'axios';
+import { PaymentsDashboard, StripeConnect } from '@bigbinary/neeto-payments-frontend';
+import { useQueryParams } from "@bigbinary/neeto-commons-frontend"; // Assuming you use this hook
+
+const PaymentSettingsPage = () => {
+  const [integrations, setIntegrations] = useState({});
+  const [isLoading, setIsLoading] = useState(true);
+  const [isStripeConnectOpen, setIsStripeConnectOpen] = useState(false);
+  const { app: returnedApp, error: oauthError } = useQueryParams(); // For handling OAuth callbacks
+
+  useEffect(() => {
+    const fetchIntegrations = async () => {
+      setIsLoading(true);
+      try {
+        // IMPORTANT: Specify ONLY the providers your application actually uses.
+        const usedProviders = ["stripe_standard"]; // Example: only using Stripe Standard
+        const response = await axios.get('/payments/api/v1/integrations', {
+          params: { providers: usedProviders }
+        });
+        setIntegrations(response.data);
+      } catch (err) {
+        console.error("Failed to fetch integrations:", err);
+        // Handle error appropriately (e.g., show toast notification)
+      } finally {
+        setIsLoading(false);
+      }
+    };
+    fetchIntegrations();
 
-#### 2. `PaymentKindRestrictionAlert` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/42ad8330442696b102d8555930162d75cf94931e/app/javascript/src/components/Stripe/Connect/PaymentKindRestrictionAlert/index.jsx))
+    // Handle OAuth callback results
+    if (returnedApp === 'stripe' && oauthError) {
+      console.error("Stripe connection failed:", oauthError);
+      // Show error message to user
+    } else if (returnedApp === 'stripe') {
+      console.log("Stripe connection initiated successfully. Waiting for webhook verification.");
+      // Maybe show a success message, fetchIntegrations will update the state eventually
+    }
+    // Add similar checks for Razorpay if using OAuth
 
-**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.
+  }, [returnedApp, oauthError]);
 
-**Usage**
-```jsx
-import React, { useState } from "react";
-import { PaymentKindRestrictionAlert } from "@bigbinary/neeto-payments-frontend";
+  // Determine holdableId based on your app's logic (e.g., current organization)
+  // This might come from context, props, or another state hook
+  const currentHoldableId = integrations.stripe_standard_account?.holdable_id || 'your_org_or_user_id'; // Replace with actual logic
 
-const App = () => {
-  const [isStripePlatformConnectedAlertOpen, setIsStripePlatformConnectedAlertOpen] = useState(false);
+  if (isLoading) {
+    return <div>Loading payment settings...</div>;
+  }
 
   return (
-    <PaymentKindRestrictionAlert
-      isOpen={isStripePlatformConnectedAlertOpen}
-      paymentKind="standard"
-      onClose={() => setIsStripePlatformConnectedAlertOpen(false)}
-    />
+    <div>
+      <h1>Payment Settings</h1>
+
+      {/* Conditionally render based on integration status */}
+      {!integrations.stripe_standard_account?.is_connected && (
+        <button onClick={() => setIsStripeConnectOpen(true)}>
+          Connect Stripe Account
+        </button>
+      )}
+      {integrations.stripe_standard_account?.is_connected && (
+        <p>Stripe Account Connected: {integrations.stripe_standard_account.identifier}</p>
+        // Add disconnect button here
+      )}
+
+      {/* Stripe Connect Modal */}
+      <StripeConnect
+        isOpen={isStripeConnectOpen}
+        onClose={() => setIsStripeConnectOpen(false)}
+        holdableId={currentHoldableId} // Pass the ID of the Organization/User model instance
+        returnUrl={`${window.location.origin}/payment-settings`} // URL Stripe redirects back to (should match registered URI)
+        isPlatform={false} // Set true only if connecting a Stripe Platform account
+      />
+
+      {/* Example Dashboard (only show if integrated) */}
+      {integrations.stripe_standard_account?.is_connected && (
+        <>
+          <h2>Payments Overview</h2>
+          <PaymentsDashboard
+            // Example: Use 'connected' kind if viewing standard account payments
+            dashboardKind="connected"
+            // Pass holdable ID for the specific account being viewed
+            holdableIds={{ stripe_standard: currentHoldableId }}
+          />
+        </>
+      )}
+    </div>
   );
 };
 
-export default App;
+export default PaymentSettingsPage;
 ```
 
-#### 4. `PayoutsDashboard` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/42ad8330442696b102d8555930162d75cf94931e/app/javascript/src/components/PayoutsDashboard/index.jsx))
+### 4. API Calls - Specify Providers
+When calling the `/api/v1/integrations` endpoint (or other APIs that might implicitly check integrations), **you must pass the `providers` parameter** listing only the providers your application uses. Omitting this or including unused providers can lead to errors if the engine tries to load configurations or associations that don't exist for your setup.
 
-**Props**
-- `payoutsPageRoute`: The route for the payouts page.
-- `isPlatformEnabled`: Indicates whether the platform is enabled or not.
+```javascript
+// Correct: Fetching only Stripe Standard integration status
+axios.get('/payments/api/v1/integrations', {
+  params: { providers: ["stripe_standard"] }
+});
 
-**Usage**
-```jsx
-import React from "react";
-import { PayoutsDashboard } from "@bigbinary/neeto-payments-frontend";
+// Incorrect (if not using all providers): Might cause errors
+// axios.get('/payments/api/v1/integrations');
+```
 
-const App = () => {
-  return (
-    <PayoutsDashboard
-      isPlatformEnabled
-      payoutsPageRoute={routes.admin.payment.stripePayouts.show}
-    />
-  );
-};
+## Core Concepts
 
-export default App;
+-   **Polymorphic Associations:** `payable` (what's being paid for), `accountable` (the payment account, e.g., `Stripe::Account`), and `holdable` (owner of the integration, e.g., `Organization`) link the engine to host app models dynamically based on configuration.
+-   **Single Table Inheritance (STI):** Used for provider-specific models like `Payments::Stripe`, `Payments::Razorpay`, `Integrations::Razorpay`.
+-   **Service Objects:** Encapsulate business logic (e.g., `Stripe::Payments::CreateService`).
+-   **Callbacks:** Host applications implement methods in `NeetoPaymentsEngine::Callbacks` to customize behavior. See the [Callbacks](#callbacks) section.
+-   **Webhooks:** Asynchronous events from providers update payment statuses. See [Webhook Handling](#webhook-handling).
+-   **JWT Authentication:** Secures OAuth callback flows using RSA keys.
+
+## Webhook Handling
+
+-   Webhooks are crucial for updating payment statuses asynchronously.
+-   Endpoints are available at `/payments/api/v1/public/<provider>/webhooks`.
+-   Signatures are verified using configured secrets.
+
+### Development Environment Setup
+
+#### 1. Tunneling
+Use a tool like `ngrok` or `tunnelto` to expose your local development server to the internet. The `connect` subdomain is reserved within Neeto for receiving callbacks from third-party services. Refer to [Using Tunnelto](https://neeto-engineering.neetokb.com/articles/using-tunnelto) and [Exposing Tunnelto Locally](https://neeto-engineering.neetokb.com/articles/writing-payment-tests) for more details.
+```bash
+# Example using tunnelto
+tunnelto --subdomain connect --port <YOUR_RAILS_APP_PORT>
+# This makes https://connect.tunnelto.dev forward to your local app
 ```
 
-#### 5. `TaxesDashboard` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/main/app/javascript/src/components/TaxesDashboard/index.jsx))
+#### 2. Stripe Webhook Setup (Manual)
+*   Go to your **Stripe Test Dashboard** > Developers > Webhooks.
+*   Click "Add endpoint".
+*   Endpoint URL: `https://connect.tunnelto.dev/payments/api/v1/public/stripe/webhooks` (replace with your actual tunnel URL).
+*   Select events to listen to. Refer to `config/stripe/webhooks.yml` in the engine for the required list (e.g., `payment_intent.succeeded`, `charge.refunded`, `account.updated`).
+*   Click "Add endpoint".
+*   After creation, find the **Signing secret** (starts with `whsec_...`).
+*   **Copy this secret** and set it as the `STRIPE_WEBHOOK_SECRET` in your local `.env.local` or development credentials.
+*   **Note:** The `neeto_payments_engine:stripe:webhooks:subscribe` rake task is **not recommended** for development setup as it doesn't create the endpoint and might show outdated secrets. Manual setup provides better control and ensures you have the correct, current secret. Refer to the [Official Stripe Webhook Documentation](https://docs.stripe.com/webhooks) for more details.
 
-**Props**
-- `feeId`: The unique identifier for the tax fee.
-- `breadcrumbs`: Data for rendering the header breadcrumbs.
-- `paymentUrl` _(optional)_: The URL of the pricing page to redirect users if payments are not enabled.
-- `headerSize` _(optional)_: Specifies the size of the header. Default size is `small`
-- `noDataHelpText` _(optional)_: Help text displayed when there is no data available.
-- `onTaxesChange` _(optional)_: Callback function triggered after performing actions in the taxes dashboard.
-- `titleHelpPopoverProps`_(optional)_: Data for the header help popover.
+#### 3. Razorpay Webhook Setup (Manual)
+*   Go to your **Razorpay Partners Dashboard**.
+*   Go to Applications
+*   Create a new application or open the existing application
+*   Add test webhook
+*   Webhook URL: `https://connect.tunnelto.dev/payments/api/v1/public/razorpay/webhooks` (replace with your tunnel URL).
+*   Set a **Secret** (create a strong random string).
+*   Select Active Events (e.g., `payment.authorized`, `payment.captured`, `payment.failed`, `refund.processed`, `refund.failed`).
+*   Save the webhook.
+*   **Copy the Secret you set** and configure it as `RAZORPAY_WEBHOOK_SECRET` in your local development environment.
 
-**Usage**
-```jsx
-import React from "react";
-import { TaxesDashboard } from "@bigbinary/neeto-payments-frontend";
+## Authentication (JWT for OAuth)
 
-const App = () => {
-  return (
-    <TaxesDashboard
-      feeId={fee.id}
-      breadcrumbs={[{text: "Settings" ,link: routes.admin.form.settings}]}
-    />
-  );
-};
+-   Secures the OAuth callback flow for connecting Stripe/Razorpay accounts.
+-   Uses RSA public/private keys (`CONNECT_PUBLIC_KEY`, `CONNECT_PRIVATE_KEY`) configured in your secrets.
+-   The `ConnectLinkService` creates a short-lived JWT containing user context when initiating the OAuth flow.
+-   The `JwtService` verifies the token signature using the public key upon callback.
 
-export default App;
+## Callbacks
+
+Host applications **must** implement specific methods within a `NeetoPaymentsEngine::Callbacks` module (e.g., in `app/lib/neeto_payments_engine/callbacks.rb`) to tailor the engine's behavior to their domain logic.
+
+### Mandatory Callbacks
+```ruby
+# app/lib/neeto_payments_engine/callbacks.rb
+module NeetoPaymentsEngine
+  class Callbacks
+    # --- Mandatory Callbacks ---
+
+    # Check user permissions for general payment management access.
+    # @param user [User] The user attempting the action.
+    # @return [Boolean] True if the user has permission.
+    def self.can_manage_payments?(user)
+      user.has_role?(:admin) # Replace with your authorization logic
+    end
+
+    # ... other callbacks ...
+  end
+end
 ```
 
-### Hooks
-#### 1. `useStripePromise` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/42ad8330442696b102d8555930162d75cf94931e/app/javascript/src/hooks/useStripePromise.js))
-
-- 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](https://github.com/bigbinary/neeto-form-web/blob/f84ad909628b7ce3497cbb6f9a1da8631121a167/app/javascript/src/components/Form/Design/Preview/index.jsx#L39).
-
-> :memo: **Note:** `STRIPE_PUBLISHABLE_KEY` environment variable must be present
-> for this hook to work.
-
-**Usage**
-```jsx
-  const stripeAccountIdentifier = "acct_1Mtqtz2e5McIywz4";
-  const stripePromise = useStripePromise(stripeAccountIdentifier);
-  ...
-  <Elements stripe={stripePromise}>
-    <CardElement />
-  </Elements>
+### Optional Callbacks (Implement as needed)
+```ruby
+# app/lib/neeto_payments_engine/callbacks.rb
+module NeetoPaymentsEngine
+  class Callbacks
+    # --- Optional Callbacks (Implement as needed) ---
+
+    # Return the fee object applicable to the payable item.
+    # @param payable [Object] The host application's payable model instance (e.g., Invoice, Booking).
+    # @return [NeetoPaymentsEngine::Fee, nil] The Fee object or nil if no fee applies.
+    def self.get_fee(payable)
+      # Example: Find fee based on payable's attributes or associated product/service
+      payable.applicable_fee # Replace with your actual logic
+    end
+
+    # Check if a payment can be processed for this payable item.
+    # @param payable [Object] The host application's payable model instance.
+    # @return [Boolean] True if payment is allowed, false otherwise.
+    def self.payment_processable?(payable)
+      # Example: Check if the payable is in a state allowing payment (e.g., 'pending', 'unpaid')
+      payable.can_be_paid? # Replace with your actual logic
+    end
+
+    # Return an ActiveRecord::Relation scope for payable objects.
+    # Used by the engine, e.g., when filtering payments by associated payables.
+    # @param organization [Organization] The organization context.
+    # @param payable_type [String, nil] The stringified class name of the payable type (e.g., "Invoice"), or nil.
+    # @return [ActiveRecord::Relation] A scope of payable objects.
+    def self.get_payables(organization, payable_type = nil)
+      # Example: Return all Invoices for the organization if type matches
+      if payable_type == "Invoice"
+        organization.invoices
+      elsif payable_type == "Booking"
+        organization.bookings
+      else
+        # Return a sensible default or handle all relevant types
+        organization.invoices # Defaulting to invoices here, adjust as needed
+      end
+    end
+
+    # Validate if a discount code is applicable to a specific payable item.
+    # @param discount_code [DiscountCode] Host application's discount code model instance.
+    # @param payable [Object] The host application's payable model instance.
+    # @return [Boolean] True if the discount code is valid for the payable, false otherwise.
+    def self.valid_discount_code?(discount_code, payable)
+      # Example: Check code validity, usage limits, applicability to the payable's item/service
+      discount_code.is_valid_for?(payable) # Replace with your actual logic
+    end
+
+    # Determine if the transaction cookie (used by Stripe flow) should be deleted.
+    # Default logic (return true) is usually sufficient. Delete after success/refund.
+    # @param payment [NeetoPaymentsEngine::Payment] The payment object.
+    # @return [Boolean] True to delete the cookie, false to keep it.
+    def self.delete_transaction_cookie?(payment)
+      true
+    end
+
+    # Return the Stripe connected account associated with the payable's context.
+    # Crucial for marketplace payments where funds go to a connected account.
+    # @param payable [Object] The host application's payable model instance.
+    # @return [NeetoPaymentsEngine::Stripe::Account, nil] The connected account or nil.
+    def self.get_connected_account(payable)
+      # Example: Find the seller/vendor associated with the payable item
+      payable.seller&.stripe_connected_account # Replace with your actual logic
+    end
+
+    # Return the Stripe connected account that should receive the split amount for a given payable.
+    # Often the same logic as get_connected_account.
+    # @param payable [Object] The host application's payable model instance.
+    # @return [NeetoPaymentsEngine::Stripe::Account, nil] The destination account for the split.
+    def self.get_split_account(payable)
+      # Example: Find the recipient/beneficiary for the split payment
+      payable.recipient_user&.stripe_connected_account # Replace with your actual logic
+    end
+
+    # Return a hash of details for a payable item, used in CSV exports.
+    # @param payable [Object] The host application's payable model instance.
+    # @return [Hash] Key-value pairs to include in the export.
+    def self.get_exportable_details(payable)
+      {
+        # Example: Extract relevant fields from your payable model
+        payable_name: payable.try(:name) || "N/A",
+        invoice_number: payable.try(:invoice_number),
+        product_sku: payable.try(:product_sku)
+      }
+    end
+
+    # Return the primary custom hostname for an organization.
+    # Used for registering Stripe Payment Method Domains.
+    # @param organization [Organization] The organization context.
+    # @return [String, nil] The custom hostname or nil.
+    def self.custom_domain_hostname(organization)
+      # Example: Fetch from a dedicated custom domain model or setting
+      organization.custom_domain_setting&.hostname
+    end
+
+    # Determine if a payment related to this payable can be split.
+    # @param payable [Object] The host application's payable model instance.
+    # @return [Boolean] True if splits are allowed for this payable type/context.
+    def self.splittable?(payable)
+      # Example: Enable splits only for specific product types or services
+      payable.allows_splits? # Replace with your actual logic
+    end
+
+    # Determine if a split transfer should be initiated immediately or held.
+    # @param payable [Object] The host application's payable model instance.
+    # @return [Boolean] True to transfer immediately, false to hold (e.g., for review).
+    def self.transferable?(payable)
+      # Example: Hold transfers for items pending review or fulfillment
+      !payable.needs_manual_review? # Replace with your actual logic
+    end
+
+    # Return metadata about the payable to include in Stripe transfers.
+    # @param payable [Object] The host application's payable model instance.
+    # @return [Hash] Metadata hash (keys/values must be strings, limited length).
+    def self.get_payable_details(payable)
+      {
+        payable_id: payable.id.to_s,
+        payable_type: payable.class.name,
+        # Add other relevant identifiers (e.g., order_id, booking_ref)
+        order_reference: payable.try(:order_reference).to_s
+      }
+    end
+
+    # Check permissions specifically for managing the Stripe Platform account (if applicable).
+    # @param user [User] The user attempting the action.
+    # @return [Boolean] True if the user has permission.
+    def self.can_manage_stripe_platform_account?(user)
+      user.has_role?(:super_admin) # Replace with your authorization logic
+    end
+
+    # Check permissions specifically for managing Razorpay integrations.
+    # @param user [User] The user attempting the action.
+    # @return [Boolean] True if the user has permission.
+    def self.can_manage_razorpay_integration?(user)
+      user.has_role?(:admin) # Replace with your authorization logic
+    end
+  end
+end
 ```
 
-### Functions
-#### 1. `buildStripeTransactionLink` ([source code](https://github.com/bigbinary/neeto-payments-nano/blob/42ad8330442696b102d8555930162d75cf94931e/app/javascript/src/utils/index.js#L3))
+## Exposed Entities
+
+The engine exposes various models, services, jobs, and tasks for integration and extension:
+
+-   **Models:** `Payment`, `Fee`, `Refund`, `Split`, `Payments::Split`, `Stripe::Account`, `Stripe::PlatformAccount`, `Integration`, `Customer`, `PaymentMethod`, `Payout`, `WebhookEvent`, etc. Host apps primarily interact with these through ActiveRecord associations defined on their own models.
+-   **Services:** Encapsulate core logic (e.g., `Stripe::Payments::CreateService`, `Razorpay::Accounts::CreateService`, `SplitTransfersFilterService`, `ExportCsvService`). While mostly used internally, filter and export services might be invoked directly or indirectly via controllers.
+-   **Jobs:** Handle background tasks (`Stripe::WebhooksJob`, `StripePlatform::CreatePaymentSplitsJob`, `ExportCsvJob`, `CreatePaymentMethodDomainJob`). These are queued and processed by Sidekiq.
+-   **Concerns:** Reusable modules (`Amountable`, `PaymentProcessable`, `Taxable`, `Stripe::Accountable`, `Refundable`). Mostly for internal engine use.
+-   **Rake Tasks:**
+    -   `neeto_payments_engine:stripe:account:integrate`: Seeds a sample Stripe connected account. **Development/Testing only.**
+    -   `neeto_payments_engine:stripe:webhooks:subscribe`: **Do not rely on this for setup.** See [Webhook Handling](#webhook-handling) for manual setup instructions.
+
+## API Endpoints
+
+The engine exposes several API endpoints under the configured mount path (default `/payments`). Here are some key ones:
+
+| Method | Path                                              | Description                                                              | Authentication |
+| :----- | :------------------------------------------------ | :----------------------------------------------------------------------- | :------------- |
+| GET    | `/api/v1/integrations`                            | List integrated payment provider accounts for the current context.       | Host App Auth  |
+| POST   | `/api/v1/exports`                                 | Initiate a CSV export for dashboards (Payments, Refunds, Splits).        | Host App Auth  |
+| GET    | `/api/v1/payments`                                | List payments with filtering and pagination.                             | Host App Auth  |
+| GET    | `/api/v1/refunds`                                 | List refunds with filtering and pagination.                              | Host App Auth  |
+| PUT    | `/api/v1/recurring_payments/:id`                  | Update the status of an admin-managed recurring payment.                 | Host App Auth  |
+| GET    | `/api/v1/split_transfers`                         | List split transfers (Stripe Platform) with filtering.                   | Host App Auth  |
+| GET    | `/api/v1/split_transfers/:id`                     | Show details of a specific split transfer.                               | Host App Auth  |
+| POST   | `/api/v1/split_transfers/bulk_update`             | Cancel or resume multiple pending/cancelled split transfers.             | Host App Auth  |
+| GET    | `/api/v1/fees/:fee_id/taxes`                      | List taxes configured for a specific fee.                                | Host App Auth  |
+| POST   | `/api/v1/fees/:fee_id/taxes`                      | Create a new tax for a fee.                                              | Host App Auth  |
+| PUT    | `/api/v1/fees/:fee_id/taxes/:id`                  | Update an existing tax for a fee.                                        | Host App Auth  |
+| DELETE | `/api/v1/fees/:fee_id/taxes/:id`                  | Delete a tax from a fee.                                                 | Host App Auth  |
+| GET    | `/api/v1/fees/:fee_id/recurring_setting`          | Get recurring payment settings for a fee.                                | Host App Auth  |
+| PUT    | `/api/v1/fees/:fee_id/recurring_setting`          | Update recurring payment settings for a fee.                             | Host App Auth  |
+| GET    | `/api/v1/stripe/countries`                        | List countries supported by Stripe for account creation.                 | Host App Auth  |
+| POST   | `/api/v1/stripe/accounts`                         | Initiate Stripe connected account creation/onboarding.                   | Host App Auth  |
+| GET    | `/api/v1/stripe/accounts/:id/creation_status`     | Check the status of an async account creation job.                       | Host App Auth  |
+| DELETE | `/api/v1/stripe/accounts/:id`                     | Disconnect a Stripe connected account.                                   | Host App Auth  |
+| GET    | `/api/v1/stripe_platform/account`                 | Get details of the configured Stripe Platform account.                   | Host App Auth  |
+| POST   | `/api/v1/stripe_platform/account`                 | Create/Connect the Stripe Platform account.                              | Host App Auth  |
+| PUT    | `/api/v1/stripe_platform/account`                 | Update Stripe Platform account settings.                                 | Host App Auth  |
+| DELETE | `/api/v1/stripe_platform/account`                 | Disconnect the Stripe Platform account.                                  | Host App Auth  |
+| GET    | `/api/v1/stripe_platform/payouts`                 | List payouts made from the Stripe Platform account.                      | Host App Auth  |
+| GET    | `/api/v1/razorpay/holdables/:holdable_id/account` | Get Razorpay account details for a specific holdable (Deprecated style). | Host App Auth  |
+| GET    | `/api/v1/upi/vpas`                                | List configured UPI VPAs for the organization.                           | Host App Auth  |
+| POST   | `/api/v1/upi/vpas`                                | Add a new UPI VPA.                                                       | Host App Auth  |
+| DELETE | `/api/v1/upi/vpas/:id`                            | Delete a UPI VPA.                                                        | Host App Auth  |
+| PUT    | `/api/v1/upi/payments/:id`                        | Confirm/update a manual UPI payment (Admin action).                      | Host App Auth  |
+| GET    | `/api/v1/integrations/connect/stripe`             | Start Stripe Connect OAuth flow.                                         | Host App Auth  |
+| GET    | `/api/v1/integrations/connect/razorpay`           | Start Razorpay OAuth flow.                                               | Host App Auth  |
+| POST   | `/api/v1/public/stripe/transactions`              | Create a Stripe Payment Intent (Public endpoint).                        | Open           |
+| POST   | `/api/v1/public/razorpay/payments`                | Create a Razorpay Order (Public endpoint).                               | Open           |
+| POST   | `/api/v1/public/upi/payments`                     | Initiate a manual UPI payment (Public endpoint).                         | Open           |
+| GET    | `/api/v1/public/recurring_payments/:payable_id`   | Get status of a customer-managed recurring payment.                      | Open           |
+| PUT    | `/api/v1/public/recurring_payments/:payable_id`   | Allow customer to cancel their recurring payment.                        | Open           |
+| GET    | `/api/v1/public/stripe/oauth/authorize`           | Stripe OAuth authorization step (Redirect handled by engine).            | JWT            |
+| GET    | `/api/v1/public/stripe/oauth/callback`            | Stripe OAuth callback processing endpoint.                               | JWT            |
+| GET    | `/api/v1/public/razorpay/oauth/authorize`         | Razorpay OAuth authorization step (Redirect handled by engine).          | JWT            |
+| GET    | `/api/v1/public/razorpay/oauth/callback`          | Razorpay OAuth callback processing endpoint.                             | JWT            |
+| POST   | `/api/v1/public/stripe/webhooks`                  | Stripe webhook receiver endpoint.                                        | Stripe Sig.    |
+| POST   | `/api/v1/public/razorpay/webhooks`                | Razorpay webhook receiver endpoint.                                      | Razorpay Sig.  |
+| POST   | `/api/v1/public/stripe_platform/webhooks`         | Stripe Platform webhook receiver endpoint.                               | Stripe Sig.    |
+
+*Note: "Host App Auth" means the endpoint relies on the host application's authentication (e.g., `authenticate_user!`). "JWT" means authentication relies on the JWT generated during the OAuth flow. "Open" means no authentication. "Stripe Sig." / "Razorpay Sig." means verification is done via webhook signatures.*
+
+## Incineration Concern
+
+If your host application uses `neeto-org-incineration-engine`, you need to integrate `NeetoPaymentsEngine` models correctly. The `NeetoPaymentsEngine::Fee` model often requires special handling as it might be associated with host application models (`feeable`).
+
+1.  **Initial Setup:** When first adding `neeto-payments-engine`, add `NeetoPaymentsEngine::Fee` to the `SKIPPED_MODELS` list in your host application's `IncinerableConcern` implementation (e.g., in `app/models/concerns/incinerable_concern.rb`). This prevents incineration errors before associations are correctly set up especially while running the whole test suite in host app.
+    ```ruby
+    # In your host app's IncinerableConcern
+    # TODO: Incinerate Fee based on Entity later
+    SKIPPED_MODELS = ["NeetoActivitiesEngine::Activity", "NeetoPaymentsEngine::Fee"]
+    ```
+2.  **Define Associations Later(optional):** Add the `has_one :fee, as: :feeable` association to your host application models that should have fees (e.g., `Product`, `ServicePlan`).
+3.  **Update Incineration Logic(optional):** Once associations are defined, **remove** `"NeetoPaymentsEngine::Fee"` from `SKIPPED_MODELS`. You must then update your `IncinerableConcern.associated_models` method to include logic that correctly finds and targets `NeetoPaymentsEngine::Fee` records associated with the organization being incinerated, likely through the `feeable` association.
+
+    ```ruby
+    # In your host app's IncinerableConcern
+    def self.associated_models(org_id)
+      # Add logic for NeetoPaymentsEngine::Fee
+      "NeetoPaymentsEngine::Fee": {
+        # Example: Find fees associated with Products belonging to the org
+        joins: "JOIN products ON products.id = neeto_payments_engine_fees.feeable_id AND neeto_payments_engine_fees.feeable_type = 'Product'",
+        where: ["products.organization_id = ?", org_id]
+        # Adjust join and where clause based on your actual feeable models
+      },
+      # Add logic for other NeetoPaymentsEngine models if needed,
+      # though many are handled via cascading deletes or direct Org association.
+      # Refer to the engine's IncinerableConcern for models it handles itself.
+      # "NeetoPaymentsEngine::Payment": { ... }
+
+      # rest of the code
+    end
+    ```
+    Consult the engine's own `NeetoPaymentsEngine::IncinerableConcern` (`app/models/concerns/neeto_payments_engine/incinerable_concern.rb`) for the list of models it defines and how it targets them for deletion, to avoid duplication and ensure comprehensive cleanup.
 
-- This function is used to generate the stripe transaction link from payment identifier.
+## Deprecated Patterns
 
-**Parameters**
-1. `identifier`: The payment identifier.
-2. `isLive`: Specifying whether or not the environment is live. It defaults to `true`.
+Please be aware of the following deprecations and use the recommended alternatives:
+
+1.  **Configuration `holdable_class`:**
+    *   **Deprecated:** The singular `NeetoPaymentsEngine.holdable_class = "ClassName"` configuration.
+    *   **Recommended:** Use the hash-based `NeetoPaymentsEngine.providers_holdable_class = { provider: "ClassName", ... }` to configure holdable models per provider. This provides more flexibility.
+
+2.  **Holdable-Scoped APIs:**
+    *   **Deprecated:** API endpoints previously located under `/api/v1/<provider>/holdables/:holdable_id/...` are deprecated.
+    *   **Recommended:** Use the newer API structure:
+        *   For general integration status: `/api/v1/integrations` (passing the `providers` param).
+        *   For provider-specific account management: `/api/v1/<provider>/accounts/...`.
+        *   For provider-specific resources like payouts: `/api/v1/<provider>/payouts/...`.
+
+3.  **`Charge` Model/Concept:**
+    *   **Deprecated:** Older versions might have referred to payment processing entities as `Charge`.
+    *   **Recommended:** The primary entity for payment processing is now `NeetoPaymentsEngine::Payment` (and its STI subclasses like `Payments::Stripe`). Use `Payment` in associations and logic. The concept of `Fee` (`NeetoPaymentsEngine::Fee`) represents the configuration of *what* to charge, while `Payment` represents the actual transaction.
+
+## Development Environment Setup
+
+To run the engine locally integrated with a host application, ensure the following processes are running:
+
+1.  **Rails Server:** Starts the main web application.
+    ```bash
+    bundle exec rails s
+    ```
+2.  **Vite Dev Server:** Compiles and serves frontend assets.
+    ```bash
+    # If using Vite
+    yarn dev
+    ```
+3.  **Sidekiq Worker:** Processes background jobs (like webhook handling).
+    ```bash
+    bundle exec sidekiq -e development -C config/sidekiq.yml
+    ```
+4.  **Tunneling Service (for Webhooks/OAuth):** Exposes your local server to the internet. Use the `connect` subdomain for OAuth callbacks.
+    ```bash
+    # Using tunnelto (replace <YOUR_APP_PORT> with your Rails server port, e.g., 3000)
+    tunnelto --subdomain connect --port <YOUR_APP_PORT>
+    ```
+    *Note: The `connect` subdomain is conventionally used across Neeto applications for receiving callbacks from third-party services like Stripe/Razorpay OAuth.*
 
-**Usage**
-```jsx
-const transactionLink = buildStripeTransactionLink(
-  "pi_3MqWX92fKivMPpZ11EPmOBBR",
-  false
-);
+The `Procfile.dev.PAYMENTS` might look like this:
+```yaml
+web: bundle exec rails s
+vite: yarn dev
+worker: bundle exec sidekiq -e development -C config/sidekiq.yml
+# Tunnel needs to be run in a separate terminal
 ```
 
-# Instructions for Publishing
-Consult the [building and releasing packages](https://neeto-engineering.neetokb.com/articles/building-and-releasing-packages) guide for details on how to publish.
+## Helper methods
+- `currency_format_with_symbol`
+   This helper method converts a currency code (like "INR" or "USD") into its corresponding symbol and returns the formatted amount with the symbol. Example $10.00.
+
+   Usage in host application:
+   - In general modules (e.g., Services or View helpers)
+      ```ruby
+      module ApplicationHelper
+        include ::NeetoPaymentsEngine::CurrencyFormatHelper
+
+        def formatted_amount
+          currency_format_with_symbol(payment&.amount, payment&.currency)
+        end
+      end
+      ```
+
+   - In mailers
+
+     1. Include the helper in your mailer:
+          ```ruby
+          class Packages::PurchaseConfirmedMailer < ApplicationMailer
+            helper ::NeetoPaymentsEngine::CurrencyFormatHelper
+
+            def customer_email
+            end
+          end
+          ```
+      2. Use the method in the mailer view:
+         ```ruby
+           <%= "#{currency_format_with_symbol(@purchase.payment&.amount,@purchase.payment&.currency)}" %>
+         ```
+
+## Testing & Debugging
+
+-   **Dummy App:** Use the `test/dummy` app within the engine's repository for isolated testing.
+-   **Test Helpers:** Utilize `NeetoPaymentsEngine::TestHelpers` (includes `HttpRequestHelpers`) for stubbing API calls to Stripe/Razorpay (`test/helpers/http_request_helpers/`).
+-   **Stripe Test Cards:**
+    *   Valid Card: `4242 4242 4242 4242`
+    *   Declined Card: `4000 0000 0000 0002`
+    *   Expiry Date: Any future date (e.g., `12/30`)
+    *   CVC: Any 3 digits (e.g., `123`)
+    *   ZIP Code: Any valid ZIP (e.g., `12345`)
+    *   [More Stripe Test Cards](https://docs.stripe.com/testing)
+-   **Razorpay Test Cards/UPI:** Refer to [Razorpay Testing Docs](https://razorpay.com/docs/payments/payments/test-card-details/).
+-   **Logging:** Check Rails logs (`log/development.log`) for detailed output from the engine's `LogActivityHelper`.
+-   **Provider Dashboards:** Use the Stripe and Razorpay **Test Mode** dashboards to view API logs, payment details, webhook attempts, and specific error messages.
+-   **JWT Debugging:** Use tools like [jwt.io](https://jwt.io) to decode JWTs generated during OAuth flows. Paste the token and the **public key** (`CONNECT_PUBLIC_KEY`) to verify the signature and inspect the payload (check `exp` claim for expiry).
+
+## Gotchas & Tips
+
+-   **`providers_holdable_class` is Mandatory:** Forgetting to configure this in the initializer will lead to errors when the engine tries to find associated accounts.
+-   **Specify `providers` in API Calls:** When calling `/api/v1/integrations`, always pass the `providers` param listing only the providers you actually use in your host app (e.g., `params: { providers: ["stripe_standard"] }`). Failing to do so might cause errors if the engine tries to load an unconfigured provider (like UPI).
+-   **Stripe Connect Signup:** You *must* complete the Stripe Connect signup process in your Stripe account, even for platform-only usage.
+-   **Webhook Secrets in Dev:** Manually created webhook endpoint secrets from Stripe/Razorpay dashboards are the source of truth for development, not necessarily what rake tasks might print.
+-   **JWT Key Security:** Treat your JWT private key with the same security as your API secret keys.
+-   **Migration Order:** Always run `bundle exec rails neeto_payments_engine:install:migrations` *before* `db:migrate` when setting up or upgrading. We also need to run this rake task and migration after we run `./bin/setup` in the host app.
+
+## Publishing
+
+For instructions on building and releasing the `@bigbinary/neeto-payments-frontend` NPM package and the `neeto-payments-engine` Ruby gem, please refer to the internal guide: [Building and Releasing Packages](https://neeto-engineering.neetokb.com/articles/building-and-releasing-packages).