How does account linking handle two-factor authentication and CAPTCHA?
When a retailer requires additional verification (2FA, CAPTCHA, or other challenges), the SDK detects this automatically and surfaces a webview for the user to complete the challenge. Your app receives a callback indicating verification is needed, along with the view controller to present. Once the user completes the challenge, a second callback confirms verification is complete and you dismiss the view controller.
With Retailer Webview Authentication, the webview stays visible throughout the entire login flow, so 2FA and CAPTCHA are handled inline. With Host App Authentication, the webview only appears when these challenges are detected.
How are user credentials stored?
All account credentials are encrypted and stored locally on the device’s keychain. Credentials never leave the device. They are only used when the retailer session expires and re-authentication is required.
Can I link multiple accounts for the same retailer?
No. Only one account per retailer is supported at a time. To switch accounts, unlink the current account first, then link the new one.
How do I change a user’s credentials?
You cannot modify credentials on an existing connection. To update credentials:
- Unlink the existing account for that retailer.
- Create a new connection with the updated credentials.
- Verify the new credentials (recommended).
- Link the new connection.
Can account linking collect in-store purchases?
Yes, as long as the in-store purchases are visible in the user’s online retailer account. Retailers like Walmart, Target, and Kroger allow customers to see in-store purchases through their website or app.
What order types does account linking support?
Account linking supports four order types: In-Store, Delivery, Pickup, and Digital (movies, eBooks, songs, etc.). Not every retailer supports all order types. See the Supported Merchants page for details.
Does account linking return order status?
Yes. Possible status values include: ordered, ready for pickup, shipped, completed, cancelled, refunded, and returned. Depending on the retailer and order type, status may appear at the order level, the shipment level (delivery orders only), or the individual product level.
Will account linking return an order again if its status changes?
No. Account linking returns each order only once. To get an updated version of a previously retrieved order, reset the order history for that retailer and retrieve again.
Why am I not seeing any orders after a successful grab?
The most common causes:
- Day cutoff too short. Make sure your
dayCutoff(ordateCutoff) is large enough to include the orders you expect. The default is 15 days. - Cache not reset. The SDK tracks the last successful retrieval date for each retailer. Subsequent calls only return orders since that date. During testing, reset the order history for the retailer between test runs.
- No qualifying orders. Log in to the retailer account directly and confirm the expected purchases are visible there.
Can I run account linking on a background thread?
No. Account linking is not thread-safe. All operations should run on the main thread.
What is the default day cutoff?
The default is 15 days. You can change this by setting dayCutoff (number of days) or dateCutoff (specific date) on the connection’s configuration before linking.
Does unlinking an account clear the order history cache?
No. Unlinking removes stored credentials but does not reset the internal tracking of previously retrieved orders. If the same user re-links, the SDK will only return new orders since the last successful retrieval. To fully reset, explicitly call the reset history method for that retailer.
How does the SDK handle retailer session expiration?
When a retailer session expires, the SDK uses the locally stored credentials to re-authenticate automatically. If re-authentication fails (e.g., the retailer now requires 2FA), the SDK surfaces the challenge to the user through the standard verification flow.