@atomicfi/transact-capacitor
v1.0.1
Published
Capactior plugin to use native sdks from Atomic
Readme
@atomicfi/transact-capacitor
Capactior plugin to use native sdks from Atomic
Install
npm install @atomicfi/transact-capacitor
npx cap syncAPI
presentTransact(...)presentAction(...)hideTransact()pauseTransact(...)resumeTransact(...)resolveDataRequest(...)addListener('onInteraction', ...)addListener('onDataRequest', ...)addListener('onAuthStatusUpdate', ...)addListener('onTaskStatusUpdate', ...)addListener('onFinish', ...)addListener('onClose', ...)addListener('onLaunch', ...)removeAllListeners()- Interfaces
- Type Aliases
The Transact Capacitor plugin interface.
presentTransact(...)
presentTransact(options: PresentTransactOptions) => Promise<TransactResult>Launch a Transact flow. Resolves when the flow finishes or is closed.
| Param | Type |
| ------------- | ------------------------------------------------------------------------- |
| options | PresentTransactOptions |
Returns: Promise<TransactResult>
presentAction(...)
presentAction(options: PresentActionOptions) => Promise<TransactResult>Present a specific action by ID. Resolves when the action completes or is closed.
| Param | Type |
| ------------- | --------------------------------------------------------------------- |
| options | PresentActionOptions |
Returns: Promise<TransactResult>
hideTransact()
hideTransact() => Promise<void>Programmatically hide the Transact overlay.
pauseTransact(...)
pauseTransact(options?: PauseTransactOptions | undefined) => Promise<void>Pause the active Transact session, dismissing the UI while preserving session state so it can be resumed later with {@link resumeTransact}.
| Param | Type |
| ------------- | --------------------------------------------------------------------- |
| options | PauseTransactOptions |
resumeTransact(...)
resumeTransact(options?: ResumeTransactOptions | undefined) => Promise<void>Resume a previously paused Transact session.
| Param | Type |
| ------------- | ----------------------------------------------------------------------- |
| options | ResumeTransactOptions |
resolveDataRequest(...)
resolveDataRequest(options: DataRequestResponse) => Promise<void>Respond to an onDataRequest event with card or identity data.
| Param | Type |
| ------------- | ------------------------------------------------------------------- |
| options | DataRequestResponse |
addListener('onInteraction', ...)
addListener(eventName: 'onInteraction', listenerFunc: (event: InteractionEvent) => void) => Promise<PluginListenerHandle>| Param | Type |
| ------------------ | --------------------------------------------------------------------------------- |
| eventName | 'onInteraction' |
| listenerFunc | (event: InteractionEvent) => void |
Returns: Promise<PluginListenerHandle>
addListener('onDataRequest', ...)
addListener(eventName: 'onDataRequest', listenerFunc: (event: DataRequestEvent) => void) => Promise<PluginListenerHandle>| Param | Type |
| ------------------ | --------------------------------------------------------------------------------- |
| eventName | 'onDataRequest' |
| listenerFunc | (event: DataRequestEvent) => void |
Returns: Promise<PluginListenerHandle>
addListener('onAuthStatusUpdate', ...)
addListener(eventName: 'onAuthStatusUpdate', listenerFunc: (event: AuthStatusUpdateEvent) => void) => Promise<PluginListenerHandle>| Param | Type |
| ------------------ | ------------------------------------------------------------------------------------------- |
| eventName | 'onAuthStatusUpdate' |
| listenerFunc | (event: AuthStatusUpdateEvent) => void |
Returns: Promise<PluginListenerHandle>
addListener('onTaskStatusUpdate', ...)
addListener(eventName: 'onTaskStatusUpdate', listenerFunc: (event: TaskStatusUpdateEvent) => void) => Promise<PluginListenerHandle>| Param | Type |
| ------------------ | ------------------------------------------------------------------------------------------- |
| eventName | 'onTaskStatusUpdate' |
| listenerFunc | (event: TaskStatusUpdateEvent) => void |
Returns: Promise<PluginListenerHandle>
addListener('onFinish', ...)
addListener(eventName: 'onFinish', listenerFunc: (event: FinishEvent) => void) => Promise<PluginListenerHandle>| Param | Type |
| ------------------ | ----------------------------------------------------------------------- |
| eventName | 'onFinish' |
| listenerFunc | (event: FinishEvent) => void |
Returns: Promise<PluginListenerHandle>
addListener('onClose', ...)
addListener(eventName: 'onClose', listenerFunc: (event: CloseEvent) => void) => Promise<PluginListenerHandle>| Param | Type |
| ------------------ | --------------------------------------------------------------------- |
| eventName | 'onClose' |
| listenerFunc | (event: CloseEvent) => void |
Returns: Promise<PluginListenerHandle>
addListener('onLaunch', ...)
addListener(eventName: 'onLaunch', listenerFunc: () => void) => Promise<PluginListenerHandle>| Param | Type |
| ------------------ | -------------------------- |
| eventName | 'onLaunch' |
| listenerFunc | () => void |
Returns: Promise<PluginListenerHandle>
removeAllListeners()
removeAllListeners() => Promise<void>Interfaces
TransactResult
Result returned when a Transact flow finishes or is closed.
| Prop | Type | Description |
| -------------- | ------------------------------------------------------------ | --------------------------------------------- |
| finished | Record<string, any> | Present when the flow completed successfully. |
| closed | Record<string, any> | Present when the flow was closed by the user. |
| error | string | Error message if the flow failed to launch. |
PresentTransactOptions
Options for {@link TransactPluginPlugin.presentTransact}.
| Prop | Type | Description |
| ----------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| config | TransactConfig | The Transact configuration. |
| environment | TransactEnvironment | Environment to connect to. Defaults to production. |
| presentationStyle | 'formSheet' | 'fullScreen' | iOS only. Modal presentation style. |
| debug | boolean | Enable debug mode. iOS: forwards debug logs to console.log and makes the WKWebView inspectable. Android: makes the WebView inspectable via chrome://inspect. Logs print automatically — no listener required. |
TransactConfig
Top-level configuration object for a Transact session.
Properties are grouped by scope compatibility:
- Shared —
publicToken,scope,tasks,theme,language,deeplink,metadata - UserLink-only —
linkedAccount,search,handoff,experiments,customer,features,sessionContext,conversionToken,inSdk - PayLink-only —
deferredPaymentMethodStrategy
| Prop | Type | Description |
| ----------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| publicToken | string | Required. Public token returned from AccessToken creation. |
| scope | ScopeType | Required. Product scope — 'user-link' or 'pay-link'. |
| tasks | TransactTask[] | Required. Task operations to execute. Operations differ per scope. |
| theme | TransactTheme | Shared. Visual theme customization. |
| language | LanguageType | Shared. Display language — 'en' or 'es'. Defaults to 'en'. |
| deeplink | TransactDeeplink | Shared. Deeplink into a specific step in the Transact flow. |
| metadata | Record<string, string> | Shared. Custom key-value pairs returned in webhook events. |
| linkedAccount | string | UserLink-only. Linked account ID for immediate authentication. |
| search | TransactSearch | UserLink-only. Search filtering by company tags. |
| handoff | HandoffType[] | UserLink-only. Views to hand off to the host app via SDK events. |
| experiments | TransactExperiments | UserLink-only. Override feature flags from the Atomic Console. |
| customer | TransactCustomer | UserLink-only. Override the customer name displayed in the UI. |
| features | TransactFeatures | UserLink-only. Feature toggles. |
| sessionContext | string | UserLink-only. Optional session context string. |
| conversionToken | string | UserLink-only. Token for conversion tracking. |
| inSdk | boolean | UserLink-only. When false, removes SDK-dependent UI elements. Defaults to true. |
| deferredPaymentMethodStrategy | DeferredPaymentMethodStrategyType | PayLink-only. Strategy for providing deferred payment method data. - 'sdk' — Respond via the native resolveDataRequest method. - 'api' — Send data via the Update User API endpoint. |
TransactTask
A single task in the Transact workflow.
operation— Shared (required). Operations differ by scope.distribution,onComplete,onFail— UserLink-only.
| Prop | Type | Description |
| ------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| operation | OperationType | Required. The task operation — see {@link Operation} for scope-specific values. |
| distribution | TransactDistribution | UserLink-only. Deposit distribution settings. Only meaningful with deposit operation. |
| onComplete | 'continue' | 'finish' | UserLink-only. Action on task success: 'continue' or 'finish'. Defaults to 'continue'. |
| onFail | 'continue' | 'finish' | UserLink-only. Action on task failure: 'continue' or 'finish'. Defaults to 'continue'. |
TransactDistribution
UserLink-only. Deposit distribution settings for the deposit operation.
Enforces deposit configuration and eliminates incompatible search results.
| Prop | Type | Description |
| --------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
| type | 'total' | 'fixed' | 'percent' | Distribution type: 'total', 'fixed', or 'percent'. |
| amount | number | Dollar amount (for 'fixed') or percentage of paycheck (for 'percent'). |
| canUpdate | boolean | If true, the user can override the default amount. Defaults to false. |
TransactTheme
Visual theme customization for the Transact UI.
| Prop | Type | Description |
| ----------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| brandColor | string | Any valid CSS color value for buttons and accent elements. |
| overlayColor | string | Any valid CSS background-color value for the modal overlay. |
| dark | boolean | Enable dark mode. |
| display | string | Set to 'inline' to render inside a container element instead of as a modal. |
| navigationOptions | TransactNavigationOptions | Navigation bar element visibility. |
TransactNavigationOptions
Controls for navigation bar element visibility.
| Prop | Type | Description |
| ------------------------ | -------------------- | -------------------------------------------------------------------------- |
| showBackButton | boolean | Whether the back button is visible. Defaults to true. |
| showBackButtonText | boolean | Whether a text label appears next to the back button. Defaults to false. |
| showCloseButton | boolean | Whether the close/exit button is displayed. Defaults to true. |
TransactDeeplink
Deeplink configuration to navigate directly to a specific step.
Both login-company and search-company are supported by UserLink and PayLink.
| Prop | Type | Description |
| --------------- | --------------------------------------------- | ------------------------------------------------------------------ |
| step | StepType | The step to navigate to — 'login-company' or 'search-company'. |
| companyId | string | Company ID to deeplink into. |
| app | AppType | PayLink manage-only. App to deeplink into — see {@link App}. |
| payments | string[] | PayLink manage-only. Payment IDs to target. |
| accountId | string | PayLink manage-only. Account ID to target. |
TransactSearch
UserLink-only. Search filtering by company tags.
| Prop | Type | Description |
| ------------------ | ---------------------- | ----------------------------------------------------------------- |
| tags | TagType[] | Filter companies by tags. |
| excludedTags | TagType[] | Exclude companies matching these tags. |
| ruleId | string | Identifier for a search experience defined in the Atomic Console. |
TransactExperiments
UserLink-only. Override feature flags from the Atomic Console.
| Prop | Type | Description |
| ------------------------ | -------------------- | --------------------------------------------------- |
| fractionalDeposits | boolean | Override the Fractional Deposit feature flag value. |
TransactCustomer
UserLink-only. Override the customer name displayed in the Transact UI.
| Prop | Type | Description |
| ---------- | ------------------- | ------------------------------ |
| name | string | Customer name shown in the UI. |
TransactFeatures
UserLink-only. Feature toggles for the Transact session.
| Prop | Type | Description |
| ------------------------ | -------------------- | ------------------------------------------------------- |
| fractionalDeposits | boolean | Enable or disable fractional (decimal) deposit amounts. |
| customSearch | boolean | Enable or disable custom search functionality. |
TransactEnvironment
Environment configuration for connecting to Atomic services.
| Prop | Type | Description |
| ------------------ | -------------------------------------------------- | --------------------------------------------------------------- |
| environment | 'production' | 'sandbox' | 'custom' | Environment target: 'production', 'sandbox', or 'custom'. |
| transactPath | string | Custom Transact URL. Required when environment is 'custom'. |
| apiPath | string | Custom API URL. Required when environment is 'custom'. |
PresentActionOptions
Options for {@link TransactPluginPlugin.presentAction}.
| Prop | Type | Description |
| ----------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Required. The action ID to present. |
| environment | TransactEnvironment | Environment to connect to. Defaults to production. |
| theme | TransactTheme | Visual theme customization. |
| metadata | Record<string, string> | Custom key-value pairs returned in webhook events. |
| presentationStyle | 'formSheet' | 'fullScreen' | iOS only. Modal presentation style. |
| debug | boolean | Enable debug mode. iOS: forwards debug logs to console.log and makes the WKWebView inspectable. Android: makes the WebView inspectable via chrome://inspect. Logs print automatically — no listener required. |
PauseTransactOptions
Options for {@link TransactPluginPlugin.pauseTransact}.
| Prop | Type | Description |
| -------------- | -------------------- | ------------------------------------------------------------ |
| animated | boolean | Whether the pause animation should play. Defaults to true. |
ResumeTransactOptions
Options for {@link TransactPluginPlugin.resumeTransact}.
| Prop | Type | Description |
| -------------- | -------------------- | ------------------------------------------------------------- |
| animated | boolean | Whether the resume animation should play. Defaults to true. |
DataRequestResponse
Response payload for resolving an onDataRequest event.
| Prop | Type | Description |
| -------------- | ----------------------------------------------------- | ------------------ |
| card | CardData | Payment card data. |
| identity | IdentityData | Identity data. |
CardData
Payment card information for resolving data requests.
| Prop | Type | Description |
| ------------ | ------------------- | ------------------------ |
| number | string | Full card number. |
| expiry | string | Card expiration date. |
| cvv | string | Card verification value. |
IdentityData
Identity information for resolving data requests.
| Prop | Type |
| ---------------- | ------------------- |
| firstName | string |
| lastName | string |
| postalCode | string |
| address | string |
| address2 | string |
| city | string |
| state | string |
| phone | string |
| email | string |
PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |
InteractionEvent
Payload for the onInteraction event.
| Prop | Type | Description |
| ----------- | ------------------- | ------------------------ |
| name | string | Name of the interaction. |
| value | any | Interaction value. |
DataRequestEvent
Payload for the onDataRequest event.
| Prop | Type | Description |
| -------------------- | --------------------- | ---------------------- |
| fields | string[] | Requested data fields. |
| taskId | string | |
| userId | string | |
| identifier | string | |
| taskWorkflowId | string | |
| externalId | string | |
AuthStatusUpdateEvent
Payload for the onAuthStatusUpdate event.
| Prop | Type | Description |
| ------------- | --------------------------------------------------------------------- | ------------------------------------------- |
| status | string | Authentication status. |
| company | TransactCompanyEvent | Company associated with the authentication. |
TransactCompanyEvent
Company information included in event payloads.
| Prop | Type |
| -------------- | --------------------------------------------------------------------------------- |
| _id | string |
| name | string |
| branding | { color: string; logo: { url: string; backgroundColor?: string; }; } |
TaskStatusUpdateEvent
Payload for the onTaskStatusUpdate event.
| Prop | Type | Description |
| ----------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| taskId | string | |
| product | string | |
| status | TaskStatusType | Current task status. |
| failReason | FailReasonType | Reason for failure. Only present when status is 'failed'. |
| company | TransactCompanyEvent | Company associated with the task. |
| depositData | DepositDataEvent | UserLink — Deposit data returned on successful deposit operations. |
| switchData | SwitchDataEvent | PayLink — Payment method data returned on successful switch operations. |
| managedBy | { company: TransactCompanyEvent; } | Present when a task is managed by another company. |
DepositDataEvent
UserLink — Deposit data from a successful deposit operation.
| Prop | Type |
| ------------------------ | ------------------- |
| accountType | string |
| distributionAmount | number |
| distributionType | string |
| lastFour | string |
| routingNumber | string |
| title | string |
SwitchDataEvent
PayLink — Payment method data from a successful switch operation.
| Prop | Type |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| paymentMethod | { type: string; brand?: string; expiry?: string; lastFour?: string; accountType?: string; routingNumber?: string; accountNumberLastFour?: string; } |
FinishEvent
Payload for the onFinish event.
| Prop | Type |
| ------------ | ------------------- |
| taskId | string |
CloseEvent
Payload for the onClose event.
| Prop | Type |
| ------------ | ------------------- |
| reason | string |
Type Aliases
Record
Construct a type with a set of properties K of type T
{ [P in K]: T; }
ScopeType
(typeof Scope)[keyof typeof Scope]
OperationType
(typeof Operation)[keyof typeof Operation]
LanguageType
(typeof Language)[keyof typeof Language]
StepType
(typeof Step)[keyof typeof Step]
AppType
(typeof App)[keyof typeof App]
TagType
(typeof Tag)[keyof typeof Tag]
HandoffType
(typeof Handoff)[keyof typeof Handoff]
DeferredPaymentMethodStrategyType
(typeof DeferredPaymentMethodStrategy)[keyof typeof DeferredPaymentMethodStrategy]
TaskStatusType
(typeof TaskStatus)[keyof typeof TaskStatus]
FailReasonType
(typeof FailReason)[keyof typeof FailReason]
