Create a subscription (existing subscriber)

When a customer already has an active subscription with you and wants to start paying with HSA/FSA funds, you provision a token on its own—no charge, no order. create_payment_token runs the same survey and card entry as a new subscriber, minus the payment.

This flow is a variant of New Subscriber. Read that page for the shared parts; this page covers only what differs.

When to use this flow

Use create_payment_token when the customer is mid-subscription and there’s nothing to charge right now—you’re switching their payment method for future billing periods. If you’re charging them today, use create_payment_session with tokenize: true instead.

How this differs from a new subscriber

	New subscriber	Existing subscriber
Endpoint	`create_payment_session` with `tokenize: true`	`create_payment_token`
Amount charged	The first order	Nothing
`total_amount`	Required	Ignored
Identifier returned	`id`, the payment session	`provision_token_request_id`, the setup request
Webhooks fired	`payment_session_complete` and `payment_token_updated`	`payment_token_updated` only

Because no payment session exists, there’s no payment_session_complete webhook and nothing to fulfill. The only outcome that matters is whether a token gets provisioned.

Create the token

order_items still matters: the LMN is scoped to what the customer is subscribed to, so send the items in their current subscription.

$ curl https://api.truemed.com/api/v1/payment_tokens/create \
>   -X POST \
>   -H "Content-Type: application/json" \
>   -H "x-truemed-api-key: $TRUEMED_API_KEY" \
>   -d '{
>     "idempotency_key": "sub_12345_token_setup",
>     "customer_name": "Alex Smith",
>     "customer_email": "alex@example.com",
>     "success_url": "https://example.com/account/payment-method/success",
>     "failure_url": "https://example.com/account/payment-method/canceled",
>     "metadata": "subscription_12345",
>     "order_items": [
>       {
>         "sku": "b12-monthly"
>       }
>     ]
>   }'

1 {
2   "provision_token_request_id": "8a1f0c2e-77b4-4f0a-9c31-2f5c7a9d4e10",
3   "redirect_url": "https://app.truemed.com/..."
4 }

Store the provision_token_request_id against the customer. It comes back on the payment_token_updated webhook, and it’s how you match the eventual token to the right subscription.

On failure, the response carries an error enum and a message describing the problem—useful while you’re building.

What happens next

Redirect the customer to the redirect_url. From here the flow is identical to a new subscriber: they complete the health survey, enter their HSA/FSA card, and return to your success_url, where you show a “payment method saved” message. See How the flow works.

There’s no need to poll retrieve_provision_token_request for status. The payment_token_updated webhook tells you when the token is ready.

Wait for payment_token_updated before charging. A token isn’t guaranteed—if the customer abandons the survey or no LMN is issued, the webhook never fires and no token exists. Returning to your success_url is not confirmation.

Next steps

Recurring Charges

Charge the stored token on your billing schedule.

Token Lifecycle

What to do when a charge fails and the customer has to act.