> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arlohealth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Tools

> Pay-per-use payment management

## Overview

Arlo is **pay-per-use**: the patient is charged per visit, and there are no recurring subscriptions. The payment flow has two independent pieces:

1. **A card on file** — saved once via `create_payment_setup` (never charges the patient)
2. **The per-visit hold** — placed only when the patient explicitly confirms via `confirm_provider_connection`

<Note>
  **Arlo never auto-charges.** `confirm_provider_connection` *is* the patient's confirmation step — only call it once the user has agreed to proceed.
</Note>

## get\_payment\_status

Get the user's current payment status.

### Use this to

* Check whether the user already has a payment method on file
* Poll until `paymentStatus` is `ACTIVE` after the user completes `create_payment_setup`
* Show the per-visit price

### Parameters

None required.

### Returns

```json theme={null}
{
  "billingMode": "PAY_AS_YOU_GO",
  "paymentStatus": "ACTIVE",
  "paymentOptionId": "opt_paygo",
  "paymentOptions": [
    {
      "id": "opt_paygo",
      "title": "Pay Per Use",
      "price": "$30/visit",
      "priceAmountCents": 3000,
      "billingMode": "PAY_AS_YOU_GO"
    }
  ]
}
```

### Payment Statuses

| Status                | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| `PENDING`             | No usable payment method yet — run `create_payment_setup`      |
| `ACTIVE`              | Payment method on file and valid                               |
| `FAILED`              | Payment failed (card declined, etc.)                           |
| `CANCELLED`           | Payment method removed                                         |
| `ACTIVE_UNTIL_EXPIRY` | Legacy subscription cancelled but active until the period ends |

### Billing Modes

| Mode                      | Description                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| `NONE`                    | No payment method configured                                                               |
| `PAY_AS_YOU_GO`           | Pay per visit (the standard mode)                                                          |
| `SUBSCRIPTION` / `LEGACY` | Grandfathered plans from earlier pricing — treat as having access without additional setup |

***

## create\_payment\_setup

Create a Stripe card-setup session to save a payment method for pay-per-use.

<Note>
  This just puts a card on file — it does **not** charge the patient.
</Note>

### Parameters

| Parameter         | Type   | Required | Description                                   |
| ----------------- | ------ | -------- | --------------------------------------------- |
| `paymentOptionId` | string | No       | Payment option ID (from `get_payment_status`) |

### How It Works

1. Call this tool to get a Stripe-hosted card-setup URL
2. Direct the user to open `paymentUrl` in their browser
3. User saves their card on Stripe's secure checkout page
4. Poll `get_payment_status` (every \~15–30 seconds, or when the user says they're done) until `paymentStatus` is `ACTIVE`

Once `paymentStatus` is `ACTIVE`, a conversation that was waiting at a payment gate can proceed — call `confirm_provider_connection` to place the hold.

### Returns

```json theme={null}
{
  "paymentUrl": "https://checkout.stripe.com/...",
  "sessionId": "cs_abc123",
  "paymentOptionId": "opt_paygo",
  "price": 30,
  "billingMode": "PAY_AS_YOU_GO",
  "instructions": "Direct the user to the paymentUrl to save their payment method. This saves a card for pay-per-use; it does NOT charge them."
}
```

### Security

* Card details never pass through Arlo or your agent
* All payment data is handled by Stripe (PCI compliance maintained by Stripe)

***

## confirm\_provider\_connection

Confirm connecting with a healthcare provider. This tool **is** the patient's payment confirmation: calling it places the per-visit payment hold on the card on file and queues the patient for provider matching.

<Warning>
  Only call this once the user has explicitly agreed to proceed. Arlo never auto-charges.
</Warning>

### Preconditions

* Conversation is in `PAYMENT_REQUIRED` status (check via `get_conversation`)
* A payment method is on file (`get_payment_status` shows `ACTIVE`)

### Parameters

| Parameter        | Type   | Required | Description         |
| ---------------- | ------ | -------- | ------------------- |
| `conversationId` | string | Yes      | The conversation ID |

### Returns

```json theme={null}
{
  "success": true,
  "status": "MATCHING",
  "message": "You've been added to the provider queue"
}
```

### If there's no card on file

The payment gate reports `PAYMENT_SETUP_REQUIRED`. Recover with:

<Steps>
  <Step title="Call create_payment_setup">
    Get a Stripe card-setup URL and send it to the user
  </Step>

  <Step title="Poll get_payment_status">
    Wait until `paymentStatus` is `ACTIVE`
  </Step>

  <Step title="Call confirm_provider_connection again">
    Places the per-visit hold and moves the conversation to `MATCHING`
  </Step>
</Steps>

### If the hold fails

`payment_hold_failed` means the card was declined. Call `create_payment_setup` so the user can add a different card, poll `get_payment_status` until `ACTIVE`, then call `confirm_provider_connection` again.

### If the user declines

Call `cancel_request` to dismiss the payment gate — the conversation returns to AI-only chat and can be re-engaged anytime.

***

## What happened to subscriptions?

Earlier versions of this API exposed `subscribe` and `cancel_subscription` tools. Arlo is now pay-per-use only, and those tools are no longer part of the MCP surface. Grandfathered accounts on legacy plans (`billingMode: SUBSCRIPTION` or `LEGACY`) keep their access; the REST API retains [deprecated endpoints](/api-reference/subscriptions/activate) for legacy clients.