Order Monitoring

Order Monitoring pulls e-commerce order data from merchants like Amazon to enrich bank transactions with itemized purchase details. This guide covers the full flow from initial account connection through ongoing data synchronization.

There are two phases: initial connection where a user authenticates with a merchant and their orders are fetched, and continuous access where Atomic refreshes the data on a recurring basis.

This guides assumes you have previously viewed the Integration Guide and installed the Transact SDK.

Initial Connection Flow

The initial connection flow establishes a link between the user's e-commerce account and Atomic, enabling order data retrieval.

Launching Transact

To connect an e-commerce account, launch the Transact SDK with the appropriate configuration. You can either deeplink directly to a specific merchant or present the order connection page for future multi-merchant support.

If you know the user wants to connect their Amazon account, you can deeplink directly:

import { Atomic } from '@atomicfi/transact-react-native'

  Atomic.transact({
    config: {
      publicToken: 'YOUR_PUBLIC_TOKEN',
      product: 'present',
      deeplink: {
        step: 'login-company',
        companyId: 'AMAZON_COMPANY_ID'
      }
    },
    onTaskStatusUpdate: (event) => {
    console.log('Task status:', event.status)
  }
})

See the Transact SDK reference for more details on the options available for configuring the experience.

User Authentication

When the user authenticates with the merchant Atomic uses TrueAuth to establish a persistent connection. This allows Atomic to refresh the merchant data on a preset cadence without requiring the user to re-authenticate.

On successful authentication, an account object is created and stored on Atomic's side. This account contains details about the connection, orders, bills, payment methods, and payment history.

Initial Data Fetch

During the connection Task, Atomic fetches the user's order history. Fetch duration scales with order count—up to a minute for users with extensive purchase history.

Completion & Notification

Atomic provides webhooks for real-time notification of events as they process. When the connection Task completes, the account's connection status is set to connected and orders become available via the GET /accounts API.

Listen to the pay-link-accounts-updatedwebhook to receive real-time updates when account and order data is saved and ready to retrieve.

{
  "eventType": "pay-link-accounts-updated",
  "eventTime": "2024-10-20T18:00:54.761Z",
  "user": {
    "identifier": "YOUR_INTERNAL_IDENTIFIER"
  },
  "data": {
    "accounts": [
      {
        "_id": "ID_FOR_THE_ACCOUNT",
        "updateType": "created"
      },
      {
        "_id": "ID_FOR_THE_ACCOUNT",
        "updateType": "updated"
      },
      {
        "_id": "ID_FOR_THE_ACCOUNT",
        "updateType": "disconnected"
      }
    ]
  }
}

• accounts.updateType - Indicates the state of the Account. updated means that the account data has been fullly synced to Atomic and is ready for retrieval. Refer to the API reference for full details.
• accounts._id - Atomic-generated identifier for the connected account. Store this to retrieve orders and track updates.
• user.identifier - The identifier for the user which was passed to Atomic when the access token was created.

Data Model

After a successful connection, Atomic stores account and order data that you can retrieve via API. To integrate effectively, you'll need to store certain identifiers and understand the order object structure.

The following are a sample of useful data elements. Please refer to the API and Webhook references for more information.

Accounts

Atomic provides the following account-level data:

• connectionStatus - Whether the account is initial, connected, or disconnected
• lastSyncedAt - Timestamp of the most recent data sync
• _id - The Atomic account identifier you must store to correlate future updates and webhooks

Orders

Each order contains:

• date - Order date
• lineItems - Breakdown of costs (subtotal, shipping, tax)
• products - Items in the order with descriptions and amounts
• paymentMethod - Payment information including last 4 digits when available, or a text description for non-card payments (e.g., "gift card", "Affirm", "Google Play")

{
  "_id": "67376c5befe988922e8adef6",
  "sourceId": "112-2968911-3747422",
  "date": "2024-10-20T18:00:54.761Z",
  "amount": 13.37,
  "lineItems": [
    {
      "description": "Item(s) Subtotal",
      "amount": 12.49
    },
    {
      "description": "Shipping & Handling",
      "amount": 0
    },
    {
      "description": "Estimated tax to be collected",
      "amount": 0.87
    }
  ],
  "paymentMethod": {
    "type": "card",
    "lastFour": "2345",
    "brand": "Mastercard"
  },
  "products": [
    {
      "description": "AAA Alkaline Batteries",
      "amount": 12.49,
      "returnBy": "2024-12-19T23:59:59.000Z"
    }
  ]
}

Consumer Responsibilities

As the consumer of this data, you are responsible for:

• Persisting the Atomic account/user ID mapping
• Pulling orders from Atomic via the API
• Stitching orders to bank transactions using amount, date, payment method, and merchant identification

Continuous Access

After the initial connection, Atomic keeps order data up to date through daily scheduled refreshes without requiring user action.

For each account, a refresh Task fetches new or changed orders, such as newly settled transactions. Orders are stored the same way as the initial connection and associated with the same account ID.

To stay informed of data changes, listen for the pay-link-accounts-updated webhook, which fires when an account is created, data is saved, and other lifecyle events for an account.

On receiving these webhooks:

1. Call GET /pay-link/accounts/:id for affected account IDs.
2. Read connectionStatus, lastSyncedAt, and orders.
3. Update your internal models and re-run stitching logic for impacted users.

Disconnections & Failures

Understanding when and why accounts become disconnected helps you build a robust integration.

Failure Modes

An account can become disconnected due to:

• Merchant-side security events: Password reset or security flags on the user's account with the merchant.
• Expired sessions: The cached session has expired or been revoked
• Transient errors: Occasionally, the merchant returns an error page, when order data is pulled, resulting in a disconnected account.

Handling Disconnections

When you detect a disconnected account:

1. Update your UI to show the account as disconnected
2. Pause your stitching processes for this user until the account is reconnected
3. Prompt the user to reconnect via the same connection flow
4. Reconnection re-runs the initial connect pattern and re-establishes continuous access

Failure Reasons Reference

The following table lists common failure reasons you may encounter in Task webhooks:

Order-to-Transaction Stitching

Order-to-transaction stitching connects the detailed order data from Atomic (items, quantities, merchants) to the corresponding charges in a user's bank account. This enrichment transforms generic transaction descriptions like "AMZN MKTP US" into itemized purchase details. Since order dates and bank posting dates often differ, use multiple fields to ensure accurate matching.

Recommended Fields

Best Practices

• Use amount as the primary match key
• Apply a ~3-day date window to account for posting delays
• Filter out orders with non-card payment methods (gift cards, EBT, Affirm) that cannot be matched to bank transactions

Sandbox & Testing

Atomic provides a sandbox environment with mock merchant connectors for testing your integration.

1. Wire up your webhook handler for pay-link-accounts-updated
2. Run a sandbox task (merchant login is mocked)
3. Wait for webhooks, then fetch accounts and orders via GET /pay-link/accounts/:id
4. Verify parsing of account status, lastSyncedAt, and orders
5. Exercise your stitching logic against the sample data