Optum Wallet v0
Optum Wallet v0 introduces user-tagged HSA card payment methods for internal merchants. It displays an informational HSA balance banner when an authorized user's Optum Bank balance is available, and lets that user tag or untag a saved CARD payment method as their Optum Bank HSA card through UI Widget v3.
For implementation guidance, see the UI Widget integration guide.
Key Benefits
A customer opens their wallet at an internal merchant and sees their available Optum Bank HSA balance in an informational banner. They tap Add HSA Card CTA from the banner,the add payment method screen opens up with the "Optum Bank HSA" checkbox selected by default. They enter the card details and the card is saved as Optum Bank HSA card. The next time they pay, that card appears second in their wallet, right after their default payment method, with the Optum Bank HSA icon and label.
| Without OW v0 HSA capabilities | With OW v0 HSA capabilities |
|---|---|
| Customers do not see their available Optum Bank HSA balance in the wallet experience. | Eligible authorized users see an informational HSA balance banner. |
| Authorized users cannot apply an HSA designation through Widget v3 flows. | Authorized users can apply an HSA designation through supported Widget v3 flows. |
| HSA usage is not identified in the merchant payout output. | Applicable payments and refunds carry the captured HSA designation into the Individual Merchant Payout Report. |
How It Works
Standard Flow
Tagging a Card via Add Payment Method
Business Rules
Pre-Conditions
HSA balance bannerandHSA taggingare two independent, product-level feature flags; either can be ON or OFF without affecting the other.- Merchant has
CARDpayment method type configured. - An HSID is available for the authorized user — the merchant provides it directly or obtains it from EIMP through an MCID exchange (HSID authentication itself is out of scope).
- Session runs on UI Widget v3 for an authorized user — not a guest, not an agent.
- Mode is
PAYMENT_WITH_WALLET,WALLET, orPAYMENT_METHOD_SELECTfor the banner; tagging additionally supportsPAYMENT_METHOD_ENTRY.
Post-Conditions
| Outcome | Behaviour |
|---|---|
| ✅ Banner eligibility fully met | Banner displays the highest-balance eligible Optum Bank HSA account; the value is not refreshed again in that session. |
| ❌ Balance retrieval fails or balance is negative/unavailable | Banner is not displayed; the payment-method experience is not blocked. |
| ✅ Wallet has no HSA-tagged card and banner is displayed | Add HSA Card CTA opens the existing Add Payment Method experience with Optum Bank HSA Card preselected. |
| ✅ User confirms a new HSA card while one is already tagged | The HSA tag moves to the newly selected card; the previously tagged card no longer displays as HSA. |
| ✅ Payment completes with a stored HSA-tagged card | Existing Stripe processing is used unchanged; the captured HSA value is stored for reporting. |
| ❌ Merchant-exposed API submits an HSA tag change | Supported card fields are saved; the HSA designation change is ignored with no error or warning. |
Constraints
| Constraint | Detail |
|---|---|
| Single designation per card | A card can be only one of default, MANUFACTURER_CARD, or HSA-tagged — never more than one. |
| Single HSA card per wallet | Only one HSA-tagged card is allowed per wallet; tagging a new card automatically untags the prior one. |
| No balance refresh | The HSA balance is fetched once at session start and held for the session's duration — no retry or refresh. |
| No cross-session refresh | A designation change made in one widget session is not reflected in another widget already open; a new session is required. |
| User-managed, not verified | CCG persists the user's selection as-is and does not validate that the card is actually an HSA/FSA-eligible card. |
Out of Scope
- External merchants.
- Guest users and agents for HSA tagging and untagging.
- Merchant-exposed API support for changing the HSA tag.
- HSA-specific actions in UI Widget v2, including for authorized users.
- HSID authentication implementation.
Unchanged Behavior
- Payment and refund transactions remain undistributed.
- HSA-tagged card payments and refunds continue through the existing Stripe processing flow.
- HSA card deletion remains available across UI Widget v2/v3 and merchant-exposed API v1/v2, regardless of the tagging flag state.
Payment Method Sorting
Saved payment methods are returned in a consistent order from every payment-method search endpoint used by UI Widgets or merchant-exposed APIs:
| Priority | Payment-method group |
|---|---|
| 1 | Default payment method |
| 2 | HSA-tagged card |
| 3 | Remaining payment methods, sorted by most recent add/update activity (creation time when no update exists) |
Widget v2 and merchant API v1 inherit this sorting because they share the customer service.
HSA Payment Method Tile Presentation
| Condition | Expected outcome |
|---|---|
| Nickname exists | Display the nickname. |
| No nickname exists | Display Optum Bank HSA (localized for English and Spanish). |
| HSA-tagged tile renders in Widget v3 | Use the approved HSA icon and preserve the masked card-number presentation. |
| Widget v2 displays the card | Use the existing v2 label and icon logic, unmodified. |
Reporting
| Condition | Expected outcome |
|---|---|
| Payment completes successfully with a stored HSA-tagged card | Store the captured value in payment_metadata[hsaTagged] and include it in the Individual Merchant Payout Report. |
| Refund is processed against that payment | Store the original payment's captured value in refund_metadata[hsaTagged]. |
| Pay & Save matches an existing HSA-tagged method | Use the saved method; preserve Default, MF, and hsaTagged settings; report the preserved HSA value. |
| HSA tagging flag is later disabled | Continue reporting the previously captured HSA designation. |
Reporting scope is limited to the Individual Merchant Payout Report for single and split payments and their refunds, initiated through merchant API v1/v2 or any Widget version. It does not apply to the Combined Payout Report, the Transaction-Level Fee Report, or disputes.
API and Webhook Exposure
hsaTagged is exposed through existing paymentMethodDetails structures without changing request contracts:
| Area | Operations | Response field |
|---|---|---|
| Customer service | PATCH/GET /payment-methods/{id}, POST /payment-methods/search, GET/POST /customers/{customerId}/payment-method(s)[/search] | paymentMethodDetails.hsaTagged (and card.hsaTagged where the legacy card object exists) |
| V1 payment | POST/GET /payments, GET /payments/{paymentId}, PATCH .../capture|cancel|confirm | data.paymentMethod.paymentMethodDetails.hsaTagged |
| V2 payment | POST/GET /v2/payments, GET /v2/payments/{paymentId}, PATCH .../capture|cancel|allocations/{id}/confirm | data.paymentAllocations[].paymentMethod.paymentMethodDetails.hsaTagged |
| V2 refund | POST /v2/refunds, GET /v2/refunds/{refundId} | data.refundAllocations[].paymentAllocation.paymentMethod.paymentMethodDetails.hsaTagged |
hsaTagged is not added to: POST/GET /refunds (v1), /customers/{customerId}/setup-payment-methods endpoints, or any payment/refund request payload.
Documentation and Localization
- OpenAPI specs, webhook docs, feature overview, and integration guides are updated to cover
hsaTagged. - Reporting field definitions and the sample report file are updated to include the HSA Tagged column.
- Banner and HSA tile text are localized in English and Spanish.
Scenarios
✅ Standard Scenarios
| # | Scenario | Starting condition | Expected outcome |
|---|---|---|---|
| 1 | Eligible balance banner | Banner flag ON, CARD configured, HSID available, authorized Widget v3 session, valid non-negative balance | Display the informational banner using the highest eligible balance. |
| 2 | Add first HSA card | Eligible banner is displayed and wallet has no HSA-tagged card | Show CTA; open Add Payment Method with HSA preselected; hide CTA after save. |
| 3 | Replace HSA designation | Wallet already contains an HSA-tagged card | Show the replacement warning and, after confirmation, move the designation to the newly selected card. |
| 4 | Use stored HSA card for payment | Supported payment uses an HSA-tagged stored card | Process through the existing flow and capture hsaTagged for reporting after successful completion. |
| 5 | Balance retrieval failure | Eligibility is otherwise met but retrieval fails | Hide the banner and leave the payment-method experience unchanged. |
| 6 | Unsupported API tag change | Merchant API submits an HSA tag change | Ignore the designation change, apply supported card updates, and return no HSA-specific warning. |
Edge Cases
The probability of these edge cases occurring in production is low. Most are inherent to session-scoped state rather than transient failures.
Edge Cases
| # | Scenario | Outcome | Recovery |
|---|---|---|---|
| 1 | Parallel widgets open at once | Each widget keeps the HSA-tagging state loaded at session start. | Start a new session to retrieve the updated state. |
| 2 | Pay & Save matches a duplicate card | Use the existing saved method and preserve Default, MF, and hsaTagged settings. | Regression testing verifies webhook and report propagation. |
| 3 | HSA-tagged card deleted while tagging flag is OFF | Deletion remains available. | If the banner is eligible and the flag is later ON, CTA behavior follows the current wallet state. |
| 4 | Multiple HSA accounts at Optum Bank | Use only the account with the highest balance. | Balances are not aggregated. |
| 5 | V1 refund response | hsaTagged is not exposed because paymentMethodDetails is absent on this response. | No new response object is introduced. |
:::
Notifications
CCG includes hsaTagged in the applicable existing payment-method, payment, and refund webhook payloads — no new webhook events are introduced for this capability:
| Webhook group | Events carrying hsaTagged |
|---|---|
| Payment method | PAYMENT_METHOD_CREATED, PAYMENT_METHOD_UPDATED, PAYMENT_METHOD_DELETED, PAYMENT_METHOD_REPLACED |
| Payment | PAYMENT_SUCCEEDED, PAYMENT_FAILED, PAYMENT_AUTHORIZED, PAYMENT_CANCELED, PAYMENT_ACCEPTED, PAYMENT_PARTIALLY_SUCCEEDED |
| Refund | REFUND_SUCCESS, REFUND_FAILED, REFUND_PENDING, REFUND_PARTIAL_SUCCESS |
Dispute webhooks (DISPUTE_INITIATED, DISPUTE_FUNDS_WITHDRAWN, DISPUTE_WON, DISPUTE_CLOSED) do not carry hsaTagged — their payload only includes paymentMethodType.