Skip to navigation

Truemed’s application sandbox lets you test subscription requests and webhook handlers without moving real funds. You can save a token, charge it, and test the customer-action paths. Card-processor features, including multi-capture support, can differ from production.

Test the failure paths, not just the happy path. A subscription integration that has never handled a 422 will break on its first expired LMN.

Set up the sandbox

StepWhere
Create a sandbox API keydev.truemed.com/developers/api-keys
Point requests at the dev base URLhttps://dev-api.truemed.com/
Add a sandbox webhook for both payment_session_complete and payment_token_updateddev.truemed.com/developers/webhooks

A sandbox key only works against the dev base URL. See Before You Begin for the full setup.

Provision a test token

  1. Create a payment session against dev with tokenize: true, exactly as in New Subscriber.

  2. Open the redirect_url and complete the health survey as the customer would.

  3. Enter the test card—no real funds move:

    • Card number: 4242 4242 4242 4242
    • Expiration: any future date
    • CVC / ZIP: any values
  4. In the Payments tab of the dev dashboard, open the Actions menu on the test payment and choose Approve LMN.

  5. Confirm both webhooks arrive: payment_session_complete with status: captured, and payment_token_updated carrying the payment_token. If you created the session with kind: authorization, payment_token_updated arrives when you approve the LMN, before you capture, and payment_session_complete reports status: authorized until you capture.

Store the payment_token from the webhook. The rest of this page uses it. If payment_token_updated never arrives, the LMN wasn’t approved—no token was provisioned.

Charge the token

Charge it the way your billing job will, with no customer present:

curl https://dev-api.truemed.com/payments/v1/create_payment_session \
-X POST \
-H "Content-Type: application/json" \
-H "x-truemed-api-key: $TRUEMED_API_KEY" \
-d '{
"payment_token": "dev_tm_token_...",
"total_amount": 4200,
"success_url": "https://example.com/account/orders",
"failure_url": "https://example.com/account/orders",
"idempotency_key": "test_period_2",
"order_items": [
{ "name": "Monthly B12", "quantity": 1, "sku": "b12-monthly", "price": 4200, "amount_details": {} }
],
"amount_details": {}
}'

There’s nothing to approve this time—a recurring charge runs no new survey and issues no new LMN, so it bills against the approved LMN already on file and the dashboard offers no Approve action. Confirm payment_session_complete reports status: captured. That’s a complete billing period.

Drive a failure

Use the Actions menu on a test payment to push the token into a blocked state.

Dashboard actionWhat it doesUse it to test
Approve LMNIssues the LMN; the payment proceedsYour fulfillment path on captured
Reject LMNRejects the LMN; the session moves to rejectedYour cancel-and-notify path, and confirming no token is provisioned
Expire LMNApproves the LMN, then marks it expiredThe TakeHealthSurvey path—charge the token afterwards and you’ll get a 422

To test the requalification loop end to end: expire the LMN, charge the token, confirm you get 422 with next_action: "TakeHealthSurvey", send yourself to the redirect_url, complete the survey, confirm payment_token_updated arrives with a failed_payment_session_id, then charge again with a new payment session.

Also confirm your handler treats payment_token_updated as a stand-down signal and clears whatever warning you raised. See Token Lifecycle.

There’s no dashboard lever for forcing an expired or declined card, so a charge that fails that way can’t be driven end to end. The closest you can get is calling update_payment_token with update_card_info: true, which returns the same next_action and redirect_url shape. That exercises your update-card handling only—it is not a failed charge, and no 422 is involved.

Test saved-card multi-capture

Multi-capture collects one authorization through several captures. Enable saved cards and multi-capture for a test channel with Truemed. Use kind: "authorization", request_multicapture: true, and a positive, non-trial amount. Test tokenize: true on the initial order. After approval, wait for payment_token_updated. Create a later order with payment_token before you capture the initial order.

In the retry cases below, token mode means saving cards, reusing a token, or neither.

CaseCheck
AuthorizationThe create response omits multicapture_available. After authorization, read it through retrieval or payment_session_complete webhooks.
Funded cardsEvery card funding the order must support multi-capture. Test a $0 saved-card share and a backup that funds a shortfall.
Token reuseConfirm that the later order can use a card saved as a $0 backup. Check that capture or void sends no second token setup webhook.
Partial capturesFor a $100 order with availability true, capture $40 with final: false, then $60 with final: true.
ClosureCheck partially_captured after the first capture. Final capture or void releases unused holds, including verification holds.
RefundsTarget each capture by its capture_id. A refund must stay within its captures[].amount_refundable from session retrieval.
ValidationAutomatic-capture and trial combinations with saved-card multi-capture return 400 InvalidRequestParameter. Disabled required features return 400 FeatureNotEnabled.
RetriesIdentical requests return the original session. When either request combines saved cards with multi-capture, token mode, token identity, and multi-capture intent must match.

Test retry changes in both directions, including after capture, and expect 400 IdempotencyViolation. Also check that requests which neither save nor reuse cards retain their existing retry behavior.

Read authorization_expires_at through session retrieval after authorization. This timestamp gives the latest capture time and depends on the cards and configured recovery support. Use Manual and Delayed Capture for expired-hold recovery limits.

Record Stripe acceptance before rollout

Stripe is the card processor used for these acceptance checks. Application sandbox success does not prove that Stripe accepts the combined saved-card and multi-capture request. Some application test environments omit the processor options that request multi-capture, so they cannot establish processor acceptance.

Coordinate an approved Stripe test-mode setup with Truemed before rollout. Record the account configuration, application environment, Stripe API version, and test-card case. Show multicapture_available: true, partial and final captures, and refunds against the selected captures. Record both initial card saving and a later unattended token order. Include refusal coverage and expired-hold recovery when that recovery forms part of the integration.

Before you go live

  • Swap credentials and base URL. Production key, and https://api.truemed.com/.
  • Recreate both webhooks in production. payment_session_complete and payment_token_updated. Missing the second one means you never receive tokens.
  • next_action is wired to customer messaging. Both UpdatePaymentMethod and TakeHealthSurvey reach the customer with the redirect_url.
  • The expiration-monitoring job is scheduled. See Prevent failures before they happen.
  • Fulfillment is idempotent. Webhook retries must not duplicate shipments, emails, or credits.
  • Saved-card multi-capture has Stripe acceptance evidence. Record both initial card saving and later token use before rollout.
  • Item changes call update_payment_token. And you only confirm the change when next_action comes back "None".
  • Walk the Implementation Readiness Checklist.