@atomicfi/transact-capacitor

@atomicfi/transact-capacitor

Capactior plugin to use native sdks from Atomic

Install

npm install @atomicfi/transact-capacitor
npx cap sync

API

• presentTransact(...)
• 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>

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	TransactEnvironmentOption	Environment to connect to. Pass Environment.PRODUCTION / Environment.SANDBOX (or the plain string), or a TransactEnvironment object for custom URLs. Defaults to production.
presentationStyle	'formSheet' | 'fullScreen'	iOS only. Modal presentation style.
debug	boolean	Enable debug mode. Forwards native debug logs to console.log and makes the Transact webview inspectable (iOS: WKWebView via Safari Web Inspector; Android: WebView 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	EnvironmentType	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'.

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]

TransactEnvironmentOption

Environment to connect to. Pass Environment.PRODUCTION / Environment.SANDBOX (or the plain 'production' / 'sandbox' string) as a shorthand, or a TransactEnvironment object (required for custom URLs).

typeof Environment.PRODUCTION | typeof Environment.SANDBOX | TransactEnvironment

EnvironmentType

(typeof Environment)[keyof typeof Environment]

TaskStatusType

(typeof TaskStatus)[keyof typeof TaskStatus]

FailReasonType

(typeof FailReason)[keyof typeof FailReason]