caps-ui

About CAPS

CAPS (Centralized Art of Living Payment System) is an effort to have a common independent service to integrate multiple payment systems out-of-the-box.

It has two essential parts

• the Backend Server + Database
• the Frontend Component Library

This is the Frontend Component Library.

How It Works

1. A project that needs to integrate CAPS needs to register itself and its corresponding api endpoints with CAPS using the admin pages.*
2. CAPS configuration is done independently for different 'entities'
3. An 'entity' is defined as a combination of ('country', 'organization', 'module')
4. Adding new payment gateways to CAPS for use across all 'entities' is a task done by the highest privileged super-admin.
5. Adding/Configuring new 'entities' can be done by respective developers of the external project.
6. Once the configuration part is over, any frontend project can install the frontend library and use the relevant components provided.
7. All of the rendering of different payment elements for different pgs is handled by this library based on the configuration done in the admin pages for that specific 'entity'.
8. For creating orders and getting/updating transaction statuses at /thankyou page, CAPS-FE communicates with CAPS-BE.

*The access to admin pages can be requested by contacting the respective team members.

About The Library

🧢 caps-ui is a functional component library made to simplify integration of multiple payment systems out-of-the-box.

            🦢  can be used anywhere in the entire Art of Living ecosystem             🌙  minimal code for your frontend applications             🏵️  no more custom CSS handling for different payment-gateways*                    (to-be-shipped with standard theme options applied uniformly) * under development - not yet released Language Support  

Installation

Using npm:

npm install caps-ui

Using specific tarball:

# download the latest stable release from
# https://aolrepo.artofliving.org/projects/MVP/repos/caps-fe

npm install /path/to/caps-ui-x.x.x.tgz

Local Development Setup

Source code

    Download the source code from -
    https://aolrepo.artofliving.org/projects/MVP/repos/caps-fe

Environment Variables

  It is essential to add these environment files
  (where BASE_URL is the api url and API_KEY is the key used for preliminary authentication)

  .env.localdev
    - CAPS_LOCALDEV_BASE_URL
    - CAPS_LOCALDEV_API_KEY
  .env.development
    - CAPS_DEVELOPMENT_BASE_URL
    - CAPS_DEVELOPMENT_API_KEY
  .env.production
    - CAPS_PRODUCTION_BASE_URL
    - CAPS_PRODUCTION_API_KEY
  .env.qa
    - CAPS_QA_BASE_URL
    - CAPS_QA_API_KEY
  .env.uat
    - CAPS_UAT_BASE_URL
    - CAPS_UAT_API_KEY

Installation

Using custom builds:

# after making custom changes, build the bundle
npm run bundle

# and then install like previous step
npm install ./caps-ui-x.x.x.tgz

Usage

There are essentially two pages where an application needs to include components/functions provided by caps-ui to handle payments smoothly:

• Payment Selection Page
• Thank You Page

🟢 Payment Selection Page

This is the page where your customer chooses amongst various payment gateways configured by you, and enters credentials (or is redirect to a hosted page where they enter the credentials) and confirms to initiate a payment.

• Under the hood, CAPS-FE will contact CAPS-BE (the backend) and request to create an order.
• CAPS-BE will contact the pre-configured endpoint (for 'order-validation' ) belonging to the specific entity.
• If your backend confirms that the order is proper and has indeed been initated by you, CAPS-BE will contact the respective PG and initiate a transaction.
• CAPS-BE will share the respective order-id to CAPS-FE for further communication with PG to confirm the transaction.

On this page, include the component <PaymentGateways /> along with some config :

• Customer Details
• Application-Specific Metadata (for your reference)
• Payment-Specific Details*
• Entity-Specific Details (for our reference)
• Styling-Specific Options**

*Please note the amount needs to be lowest denomination of currency

• (1000,  'jpy') => ¥ 1.000
• (1000, 'usd') => $ 10.00
• (1000,'omr') => ﷼1.000
• ...

** under development - not yet released

Example

import {
  GatewayAddress,
  GatewayCustomer,
  GatewayMetadata,
  GatewayStyle,
  PaymentGatewaysConfig,
  PaymentGateways,
} from "caps-ui";

const capsEnvironment: CapsEnvironment = "development";

const customerAddress: GatewayAddress = {
  line1: "Unit 530",
  line2: "910 7 Ave. SW",
  city: "Calgary",
  state: "Alberta (AB)",
  country: "CA",
  pincode: "T2P 3N8",
};

const customerDetails: GatewayCustomer = {
  name: "Raghuvir",
  surname: "Jhaveri",
  phone: "+1-6046576534",
  email: "[email protected]",
  address: customerAddress,
};

const context: GatewayMetadata = {
  donorId: "9092dc16-b783-44d9-aab4-89b9f616cdac",
  campaign: "World Culture Festival",
};

const style: GatewayStyle = {
  theme: "dark",
  size: "XL",
  shadow: [0, -1, 0, 3],
  corners: "rounded",
};

const pconfig: PaymentGatewaysConfig = {
  country: "CA",
  org: 3,
  module: "DX",
  test: false,
  amount: 150000,
  currency: "cad",
  customerInfo: customerDetails,
  metadata: context,
  appearance: style,
  returnUrl: "https://dx.artofliving.org/thankyou",
  environment: capsEnvironment,
};

export const PayPage = () => {
  return <PaymentGateways config={pconfig} />;
};

💬 Thank You Page

This is the page the user will be redirected to when their payment is resolved (successful or perhaps canceled on the bank-authorization page).

• To fetch latest transaction status or initiate a trigger to update the same (for respective PGs like Corvuspay), it is essential to include the paymentStatus() asynchronous function call on this page (as an effect hook, perhaps)
• Under the hood, paymentStatus() will collect the query string params and send the same back to backend.
• From there, backend will do all the processing regarding which payment gateway this transaction belongs to, what is the current status of the transaction after redirect and will try to update CAPS internal tables, if needed (in absence of webhooks functionality for that specific payment-gateway).
• finally CAPS-FE will receive the response from backend and paymentStatus() function will return a promise that resolves to an object of type GatewayReturnStatus

Please note, that this page can be refreshed as many times as possible and CAPS-FE will fetch the transaction status everytime for your customer's convenience.

Example

import { GatewayReturnStatus, paymentStatus } from "caps-ui";

const capsEnvironment: CapsEnvironment = "development";
const [pStatus, setPStatus] = useState<
  GatewayReturnStatus | { error: string }
>();

useEffect(() => {
  paymentStatus(capsEnvironment).then((value) => setPStatus(value));
}, []);

// handle your own frontend-logic using the pStatus state variable
export const ThankyouPage = () => {
  return (
    <div>
      <p>Thank you page</p>
      <p>Details of the payment</p>
      <hr />
      <p>Transaction ID: {pStatus?.id}</p>
      <p>Status: {pStatus?.status}</p>
      <p>Currency: {pStatus?.currency}</p>
      <p>Amount: {pStatus?.amount}</p>
      <p>Payment Method: {pStatus?.method}</p>
      <p>Payment Vendor: {pStatus?.vendor}</p>
      <p>Payment Type: {pStatus?.type}</p>
      <p>Meta data: {JSON.stringify(pStatus?.metadata)}</p>
    </div>
  );
};

Supported Payment Gateways

The list of supported payment gateways is an ongoing task.

• As time progresses, CAPS aims to provide a comprehensive set of features for many payment gateways.
• You can find the latest list here in README.md (both on npm and the aol git repo)

| Payment Gateway | Availability Status | | --------------- | ------------------- | | Stripe | 🚧 | | Swish | 🧾 | | Paypal | 🛠️ | | Corvuspay | 🛠️ |

Additional Resources

• If you're interested, please find a preliminary design flow from earlier discussions regarding CAPS:      Design Flow*

*Please note, this diagram is not up-to-date since the system is still under initial development phase