Overview
Payment tools manage billing modes, subscription setup, and pay-per-use payments.
get_subscription_status
Get the current billing and subscription status for the user.
Parameters
None required.
Returns
{
"billingMode": "PAY_AS_YOU_GO",
"paymentStatus": "ACTIVE",
"freeTrialActive": false,
"freeTrialEndTimestamp": null,
"nextBillingTimestamp": null,
"nextBillingAmount": null,
"paymentOptions": [
{
"id": "opt_monthly",
"title": "Monthly Subscription",
"price": "$29.99/month",
"description": "Unlimited consultations",
"priceAmountCents": 2999,
"isDefault": true,
"billingMode": "SUBSCRIPTION",
"interval": "month"
},
{
"id": "opt_paygo",
"title": "Pay Per Use",
"price": "$30/consultation",
"description": "Pay only when you need care",
"priceAmountCents": 3000,
"isDefault": false,
"billingMode": "PAY_AS_YOU_GO",
"interval": "consultation"
}
]
}
Billing Modes
| Mode | Description |
|---|
NONE | No payment method configured |
PAY_AS_YOU_GO | Pay $30 per consultation |
SUBSCRIPTION | Monthly subscription with unlimited consultations |
LEGACY | Legacy billing plan |
Payment Statuses
| Status | Description |
|---|
PENDING | Payment setup in progress |
ACTIVE | Payment method active |
FAILED | Payment failed |
CANCELLED | Subscription cancelled |
ACTIVE_UNTIL_EXPIRY | Cancelled but active until period ends |
create_payment_setup
Create a Stripe Checkout session for payment setup.
Parameters
| Parameter | Type | Required | Description |
|---|
paymentOptionId | string | No | ID of the payment plan (from get_subscription_status) |
Returns
{
"paymentUrl": "https://checkout.stripe.com/...",
"price": "$29.99",
"interval": "month"
}
How It Works
- Call
create_payment_setup to get a Stripe-hosted checkout URL
- Direct the user to open
paymentUrl in their browser
- User completes payment setup on Stripe’s secure checkout page
- Payment is automatically activated after successful checkout
Billing Mode Support
| Mode | Checkout Type |
|---|
| Subscription | Creates subscription checkout (recurring billing) |
| Pay-per-use | Creates card setup checkout (saves card for $30 holds) |
Payment is activated automatically when the user completes checkout. You do NOT need to call subscribe separately — Stripe handles everything.
subscribe
Activate the user’s subscription after payment method is set up.
Prerequisites
- User has completed payment setup via
create_payment_setup
- Payment method has been successfully added in Stripe
Parameters
None required.
Returns
{
"billingMode": "SUBSCRIPTION",
"paymentStatus": "ACTIVE"
}
confirm_provider_connection
Confirm and connect with a healthcare provider (pay-per-use accounts only).
Preconditions
- Conversation must be in
PAYMENT_REQUIRED status
paymentType must be pay_per_use (check via get_consultation_status)
Parameters
| Parameter | Type | Required | Description |
|---|
conversationId | string | Yes | The conversation ID |
What Happens
On success, a $30 payment hold is placed on the user’s card and they are queued for provider matching.
Returns
{
"success": true,
"status": "MATCHING",
"message": "You've been added to the provider queue"
}
If Payment Type is Subscription Required
If paymentType is subscription_required, this tool will return an error. Use the subscription setup flow instead:
- Call
get_subscription_status to check billing
- Call
create_payment_setup to get a payment URL
- Direct user to complete payment at that URL
- Call
subscribe to activate the subscription
- Then the consultation can proceed
Workflow
When consultation reaches PAYMENT_REQUIRED, check paymentType to determine the flow:
Pay Per Use
Subscription Required
Check paymentType
paymentType is pay_per_use
Call confirm_provider_connection
Places $30 hold on user’s card
MATCHING
User is queued for provider
ACTIVE
Provider connects and consultation begins
Check paymentType
paymentType is subscription_required
Call create_payment_setup
Get Stripe checkout URL
User completes Stripe checkout
Direct user to paymentUrl
Call subscribe
Activate the subscription
MATCHING
User is queued for provider
ACTIVE
Provider connects and consultation begins
cancel_subscription
Cancel the user’s active subscription.
This action cannot be undone via the API — user would need to resubscribe.
Prerequisites
- User must have an active subscription
- Will fail if user has no subscription or is on pay-per-use
Parameters
None required.
Returns
{
"billingMode": "SUBSCRIPTION",
"paymentStatus": "ACTIVE_UNTIL_EXPIRY"
}
What Happens
- Subscription is cancelled at the end of the current billing period
- User retains access until the period ends (
ACTIVE_UNTIL_EXPIRY status)
