Executing Actions on a User's Account

Overview

Actions are a core component of the Manage product. They enable users to cancel, pause, or modify their plans—such as switching to a different tier or adjusting plan terms. Fetching updated data from a merchant is also treated as an Action.

This guide walks you through executing an Action on a user’s account. It assumes you’ve already configured the Transact SDK and the user has connected at least one account.

Taking Action

Fetch Actions for Accounts

Support for specific Actions varies by Company, and the current state of a plan can impact which Actions are available or meaningful. For example, some Companies may support cancellations but not pauses, or prevent a user from initiating a cancellation if one is already pending.

As such, Atomic maintains a list of usable Actions for each linked account. They are a field on the Account object returned in the Get Accounts endpoint. Each Action object contains the following key fields:

  • type: Possible values are cancel, pause, refresh, etc. For a deeper discussion of the types of Actions, please see the Glossary
  • automated: This is a boolean value. true indicates that the Action is completed in the background by Atomic, only requiring user interaction for authentication or MFA input. false indicates the user will use a webview to self-service a change.
  • actionId: This is a unique ID generated by Atomic and used to initialize Transact to the appropriate Action workflow.

Show Action CTAs

When you have retrieved the Actions associated with an Account, you'll want to display them to your user. Patterns for this can vary, but a common approach is to show a series of CTA buttons for the available Actions on a view dedicated to the Account.

Launch the Transact SDK

To execute an Action, use the actionId field in the relevant Action returned from the API. Call the presentAction exported by the Transact SDK, using the actionId as a parameter.

React Native Example 
import { Atomic, Product, Scope } from '@atomicfi/transact-react-native'

// Your implementation here

Atomic.presentAction({
  id,
  onLaunch: (launch) => {
    console.log('Launch event:', launch)
  },
  onClose: (close) => {
    console.log('Close event:', close)
  },
  onFinish: (finish) => {
    console.log('Finish event:', finish)
  } ,
})

The user experience at this point will depend on whether the Action is automated.

Since manual Actions require a user to make a selection or choice (such as selecting a new plan), Atomic will open a webview directly to the relevant webpage for that user. After making that choice, they can exit the webview and Atomic will execute a refresh Action in the background to sync upstream changes to the Account.

Automated Actions happen without user intervention, unless the user needs to authenticate or provide an MFA. Atomic will display a special view in the Transact SDK that lets the user know the Action is ongoing. It can also prompt for authentication or an MFA step if needed.

Since automated Actions can be run in the background, in many cases users may leave during the execution of the Action.

Refresh Actions are always automated, and typically happen in the background.

Show Progress in Your UI

Since Actions and subsequent refreshes can occur in the background, we recommend using your UI to let users know when they are in progress. This can reduce confusion, as users may re-attempt Actions if they're not sure they worked.

To do so, use the onLaunch, onFinish, and onClose callbacks in the presentAction function.

Update your data

Since Actions often change the state of the Account, you will want to refetch any Account data upon their completion.

You can use webhooks, polling, or client-side events to wait for updates to complete in the Atomic system, and then retrieve the data from the GET /pay-link/accounts endpoint.

You can also listen directly for updates using the pay-link-accounts-updated webhook.

For more in depth discussion of the options for retrieving data, review the relevant guide.

Further Reading

Ingest Data
Glossary