Skip to main content

Account Linking FAQ

Answers to commonly asked questions about Account Linking.

How does Account Linking handle accounts that require 2FA, CAPTCHA, or other authentication challenges?​

Sometimes the user's input is required to successfully log in to a retailer account. This can happen when the user has two-factor authentication enabled, or when the retailer shows a CAPTCHA for extra verification.

In Retailer Webview Authentication, the SDK shows the webview throughout the entire authentication process. With Host App Authentication, Actual handles these extra steps by exposing the webview when 2FA or CAPTCHAs are detected.

For both flows, BRAccountLinkingError indicates the stages of this process:

  • BRAccountLinkingErrorVerificationNeeded — the SDK has encountered a page requiring user input. The UIViewController parameter of the callback will be populated with the view controller you should display.
  • BRAccountLinkingErrorVerificationCompleted — the user successfully authenticated; dismiss the view controller.

Example:

let taskId = BRAccountLinkingManager.shared().grabNewOrders(for: .walmart) { retailer, order, remaining, viewController, errorCode, sessionID in
    if errorCode == .verificationNeeded {
        self.present(viewController, animated: true)
    } else if errorCode == .verificationCompleted {
        self.dismiss(animated: false)
    } else if errorCode == .none {
        if remaining <= 0 {
            // Grab Orders completed — no more orders to fetch
        }
    } else {
        // Grab Orders failed — check errorCode for more info
    }
}

Can I execute Account Linking from a background thread?​

Account Linking is not thread-safe. All execution should be done on the main thread.

No. Linking multiple accounts for the same retailer is not supported. Unlink the existing account before linking a different one.

Can I change a user's credentials?​

Credentials cannot be modified after a BRAccountLinkingConnection object is created. To change credentials, unlink the account and create a new connection:

BRAccountLinkingManager.shared().unlinkAccount(for: .walmart) {
    let connection = BRAccountLinkingConnection(retailer: .walmart, username: "new-user", password: "new-pass")
    connection.configuration.dayCutoff = 30
    BRAccountLinkingManager.shared().linkAccount(with: connection) { error, viewController, sessionId in
        // Handle result
    }
}
note

It is recommended to call loginUser(forLinkedRetailer:withCompletion:) before linking if unsure whether credentials are valid.

How does Account Linking handle user credentials?​

All account credentials are encrypted and stored locally on the device's keychain. Credentials never leave the device and are only used when a retailer session expires and re-authentication is required.

What happens if grabNewOrders returns success but I don't see any new orders?​

The most common reasons:

  • Your dayCutoff or dateCutoff may be too small. Verify your account has purchases within the cutoff window.
  • The SDK maintains an internal date of the last successful search per retailer. You may need to reset history while testing:
BRAccountLinkingManager.shared().resetHistory(for: .walmart)
note

Unlinking an account does not reset the user's order cache. You must explicitly call resetHistory(for:) if you want to re-fetch previously seen orders.

Contact blinkreceipt@microblink.com if orders are still not appearing after these steps.

Can I collect purchase information for in-store purchases?​

Yes, Account Linking supports in-store purchases as long as they are visible in the account. Target, Walmart, and Kroger are examples of merchants that expose in-store purchase history.

What order types are supported?​

  • In-Store — Purchases made in a physical store.
  • Delivery — Online purchases shipped to the customer.
  • Pickup — Online purchases picked up in store.
  • Digital — Movies, eBooks, songs, digital storage, etc.

Does Account Linking return order status?​

Yes. The following statuses are returned: ordered, ready for pickup, shipped, completed, cancelled, refunded, returned. Depending on the retailer and order type, these appear in:

  • BRScanResults.ereceiptOrderStatus — Overall order status
  • BRShipment.status — Per-shipment status (Delivery orders only)
  • BRProduct.shippingStatus — Per-product status

Will Account Linking re-return an order if its status changes (e.g., shipped → delivered)?​

No. Account Linking returns each order only once. To get the most recent version, reset the order history and re-fetch:

BRAccountLinkingManager.shared().resetHistory(for: .walmart)