@jpmorgan-payments/embedded-finance-components
v0.5.59
Published
Embedded Finance Components
Downloads
461
Readme
Embedded UI Components
🚧 Pre-release Version Notice
Embedded UI Components and this guide is currently in draft form and under active development. Components are not ready for production use and may change significantly until version 1.x.x is released. Please consider this document as a work in progress.
ADA Compliance Disclaimer
While we strive to incorporate ADA (Americans with Disabilities Act) best practices, please note that developers are responsible for conducting their own comprehensive ADA testing to ensure full compliance with all applicable standards and regulations.
Overview
Embedded UI Components offer a seamless way to integrate sophisticated UI components into your existing applications, providing a plug-and-play solution for Embedded Finance features. These components implement complex API capabilities for client onboarding and account linking, simplifying the integration process for developers.
Important Usage Notes
All Embedded UI Components must be wrapped within the EBComponentsProvider
. The EBComponentsProvider
is specifically designed for these components and is not applicable to any other client components in your application.
Setup and Configuration
EBComponentsProvider
The EBComponentsProvider
is a crucial wrapper component that must be placed at the top level of your Embedded UI Components implementation. It handles authentication, applies theming, and provides necessary context to all child Embedded UI Components.
It is using @tanstack/react-query for handling API calls and authentication as well as Orval generated types for the API requests and responses.
Key Props:
apiBaseUrl
: The base URL for API calls (required)theme
: Customization options for the components' appearance (optional)headers
: Custom headers for API requests (optional)
Usage:
import { EBComponentsProvider } from '@jpmorgan-payments/embedded-finance-components';
const EmbeddedFinanceSection = () => {
return (
<EBComponentsProvider
apiBaseUrl="https://your-api-base-url.com"
theme={{
colorScheme: 'light',
variables: {
primaryColor: '#007bff',
fontFamily: 'Arial, sans-serif',
},
}}
headers={{
'Custom-Header': 'value',
}}
>
{/* Your Embedded UI Components go here */}
</EBComponentsProvider>
);
};
Main Components
1. OnboardingWizardBasic
The OnboardingWizardBasic
component implements the client onboarding process as described in the Embedded Payments API documentation.
Main Features:
- Create a client profile
- Incrementally update client's related parties
- Complete due diligence questions
- Handle client attestations
- Manage requests for additional documentation
- Check and display onboarding status
Usage:
@jpmorgan-payments/embedded-finance-components
import {
EBComponentsProvider,
OnboardingWizardBasic,
} from '@jpmorgan-payments/embedded-finance-components';
const OnboardingSection = () => {
const [clientId, setClientId] = useManageClientExternalState();
const handlePostClientResponse = ({ response, error }) => {
// Handle client creation response or error
setClientId(response.id);
};
const handlePostClientVerificationsResponse = ({ clientId, error }) => {
// Handle post client verifications response or error
};
return (
<EBComponentsProvider apiBaseUrl="https://your-api-base-url.com">
<OnboardingWizardBasic
title="Client Onboarding"
clientId={clientId}
onPostClientResponse={handlePostClientResponse}
onPostClientVerificationResponse={handlePostClientVerificationsResponse}
availableProducts={['EMBEDDED_PAYMENTS', 'MERCHANT_SERVICES']}
availableJurisdictions={['US', 'CA']}
/>
</EBComponentsProvider>
);
};
OnboardingWizard could also accept products and jurisdictions as optional props to customize the onboarding process.
availableProducts
determines which products are selectable in the initial step of the onboarding process. If only one product is provided, the component will default to that product and the field will become read-only.
Similarly, availableJurisdictions
is an array of country codes that are selectable. If only one is provided, it will default to that country.
2. LinkedAccountWidget
The LinkedAccountWidget
component facilitates the process of adding a client's linked account, as described in the Add Linked Account API documentation.
Main Features:
- Add and manage external linked bank accounts for clients
- Handle complex micro-deposits initiation logic
Usage:
import {
EBComponentsProvider,
LinkedAccountWidget,
} from '@jpmorgan-payments/embedded-finance-components';
const LinkedAccountSection = () => {
return (
<EBComponentsProvider apiBaseUrl="https://your-api-base-url.com">
<LinkedAccountWidget variant="default" />
</EBComponentsProvider>
);
};
Please refer to the LinkedAccountProps interface in the codebase for more details.
Theming
The EBComponentsProvider
accepts a theme
prop that allows for extensive customization of the components' appearance. The theme object can include the following properties:
colorScheme
: 'dark' | 'light' | 'system'variables
: An object containing various theme variableslight
: Light theme-specific variablesdark
: Dark theme-specific variables
Theme Design Tokens
Here's a table of available theme design tokens that can be used in the variables
, light
, and dark
properties:
| Token Name | Description | | -------------------------- | -------------------------------------- | | fontFamily | Main font family for text | | backgroundColor | Background color of the main container | | foregroundColor | Main text color | | primaryColor | Primary brand color | | primaryColorHover | Hover state of primary color | | primaryForegroundColor | Text color on primary background | | secondaryColor | Secondary brand color | | secondaryForegroundColor | Text color on secondary background | | destructiveColor | Color for destructive actions | | destructiveForegroundColor | Text color on destructive background | | mutedColor | Color for muted elements | | mutedForegroundColor | Text color on muted background | | accentColor | Accent color for highlights | | accentForegroundColor | Text color on accent background | | cardColor | Background color for card elements | | cardForegroundColor | Text color for card elements | | popoverColor | Background color for popovers | | popoverForegroundColor | Text color for popovers | | borderRadius | Default border radius for elements | | buttonBorderRadius | Border radius specifically for buttons | | borderColor | Color for borders | | inputColor | Background color for input fields | | ringColor | Color for focus rings | | zIndexOverlay | z-index for overlay elements |
Installation
npm install @jpmorgan-payments/embedded-finance-components
or
yarn add @jpmorgan-payments/embedded-finance-components
Contributing
Recommended VSCode plugins:
- Prettier
- Tailwind CSS Intellisense
Recommended VS Code Settings
files.associations
Use the files.associations
setting to tell VS Code to always open .css
files in Tailwind CSS mode:
"files.associations": {
"\*.css": "tailwindcss"
}
editor.quickSuggestions
By default VS Code will not trigger completions when editing "string" content, for example within JSX attribute values. Updating the editor.quickSuggestions
setting may improve your experience:
"strings": "on"
}
Guidelines
- Create a new component in
./src/core
- Export it in
./src/index.tsx
- Also add it to
./src/vanilla/componentRegistry.ts
npm scripts
Build and dev scripts
dev
– start development serverbuild
– build production version of the apppreview
– locally preview production build
Testing scripts
typecheck
– checks TypeScript typeslint
– runs ESLintprettier:check
– checks files with Prettiervitest
– runs vitest testsvitest:watch
– starts vitest watchtest
– runsvitest
,prettier:check
,lint
andtypecheck
scripts
Other scripts
storybook
– starts storybook dev serverstorybook:build
– build production storybook bundle tostorybook-static
prettier:write
– formats all files with Prettier