Update Payment Token

Endpoint allowing your customers to update their payment method(s) and/or requalify after a cart change. ## Overview The `update_payment_token` endpoint is available for partners to call when customers change the items in their subscription or when they want to update their card(s) on file. If `update_card_info=False` and only the `order_items` are being updated, the user **may or may not need to retake the tele-health survey** depending on a variety of factors. The `next_action` field in the response body will indicate what the customer must do next, and a `redirect_url` will be provided if the customer needs to take action. If you call this endpoint and the `next_action` is not `None`, and a `redirect_url` is present, we don't guarantee you can invoke [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) with the `payment_token` until the user has completed the action and you've received the [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook. <Info title="Customer In The Flow"> The customer must be in the flow when calling this endpoint, typically from within a subscription management dashboard. </Info> **Primary Use Cases for this Endpoint:** - Allowing customers to update their card(s) on file with Truemed - Ensuring that the user is still eligible to use their HSA/FSA after a cart/subscription change. - If the customer must requalify by retaking the tele-health survey, the `next_action` will be `HealthSurvey`, which can be taken by redirecting the customer to the `redirect_url`. <Warning title="Truemed does not handle subscription management"> All subscription related fields here are to enhance the customer experience, a dedicated subscription management system is needed on the partner's side. </Warning> The diagram below outlines the customer flow when using this endpoint: <Steps> <Step title="Partner invokes update"> Partner invokes `update_payment_token` triggered by a customer action. The customer is either updating their payment method(s) or has made a change to the items in their subscription. </Step> <Step title="Customer completes next action"> The partner redirects the customer to the `redirect_url` if `next_action` is not `None`. The customer completes the required action on Truemed's site. </Step> <Step title="Customer returns to partner"> The customer is redirected to the `success_url` upon completion of the next action on Truemed's site. </Step> <Step title="Receive update confirmation"> Truemed issues a [`payment_token_updated`](/api-reference/payment-tokens/payment-token-updated-webhook) webhook indicating that the `payment_token` has been updated. </Step> </Steps> ```mermaid sequenceDiagram participant User participant Partner participant Truemed User->>Partner: Update payment method or cart Partner->>Truemed: update_payment_token request Truemed-->>Partner: redirect_url response Partner-->>User: Redirect to redirect_url (if needed) User->>Truemed: Complete survey or update card Note over User: User eligible or card updated Truemed->>Partner: payment_token_updated webhook Truemed-->>User: Redirect to success_url ``` <Note> The webhook/callback is invoked at the same time the user is being redirected to the `success_url` - we don't guarantee that it will be called before the redirect. </Note> ## Request Notes - **update_card_info** (Optional): boolean - Indicates if this request is to update the card(s) on file. - If set to `True`, the response will always include `redirect_url` so the user can update their payment method(s) on file with Truemed. - **order_items** (Optional): An array of `order_item` objects, each with the following fields: - **name** (Required): string - the name of the item. - **sku** (Required): sku - the SKU or id for this product. - **NOTES**: This should only be supplied when the user is changing the items associated with a given subscription - **success_url** (Required): Where to redirect the user to after the customer successfully completes the tele-health survey and/or updates their payment method(s). - This is often used to display a confirmation screen, or similar - **failure_url** (Required): When the user opts to not complete the tele-health survey or selects "cancel" during the process, or when the user is ineligible to spend HSA/FSA funds on the items in the request. - We attempt to recover from incorrect CVV, or other card detail errors by prompting the user for retry - **use_iframe** (Optional): Optional query parameter that can be used to modify the response's `redirect_url` so it can be used and communicated with in an iframe. - **metadata** (Optional): Any additional data supplied by the partner. This will be echoed back in the `payment_token_updated` webhook after the `update_payment_token` flow is complete. - **Important**: This must be a string. If you want to include JSON, encode it as a string. - **Important**: DO NOT INCLUDE sensitive information in this field. ## iFrame Support If `use_iframe` is set to `true`, `redirect_url` will be iframe-compatible. Partners can create an iframe and set the `src` to `redirect_url` and this will render Truemed's survey and checkout flow in the iframe. When using iframes, the flow completion is communicated via `postMessage`: - **success** - Returns `true` if checkout flow was successful on Truemed's end, `false` if otherwise - **redirectUrl** - string that will be set to `success_url` from the original request body if `success` is `true` or set to `failure_url` if `success` is `false`. Only need to be used if redirect is desired or can handle success and failure differently. ## Response Notes ### Success Case **HTTP Status: 200:** - **next_action**: The action the customer must take. Can be one of the following: - `UpdatePaymentMethod`: Customer must enter a new payment method. - `HealthSurvey`: Customer must take the health survey - `None`: There is no other action needed at this time. - **redirect_url**: Contains a URI through which the customer can complete the `payment_token`. If `next_action=None`, this field won't be present. ### Bad Request **HTTP Status: 400** If a field is missing or the request otherwise can't be processed, we'll return a 400 with the following fields: - **error**: Can be one of: - `MissingField`: One of the required fields is not present in the request - `IdempotencyViolation`: An `idempotency_key` was reused with different request parameters - `ServerError`: There was an internal server error. - Requests can be retried as long as the `idempotency_key` is the same. - `InvalidToken`: The requested token was not found - `IneligibleItemAdded`: A new item is ineligible for HSA/FSA spend. Can be returned when requesting to update the items associated with a customer's `payment_token` - **message**: Indication of one of the following: - Which field was missing - Details on how the total amount was invalid