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 with the payment_token until the user has completed the action and you've received the payment_token_updated 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>

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. When the customer finishes, the iframe posts one completion message to your page:

{ "success": true, "redirectUrl": "https://example.com/success" }

redirectUrl echoes the success_url or failure_url from your request, matching success. See the Embedded Checkout guide for how to render the flow, validate the message's origin, and handle it.

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