Payments

Overview

Arlo is pay-per-use: the patient is charged per provider visit, and there are no recurring subscriptions. Two independent pieces make up the payment flow:

A card on file — saved once through Stripe (create_payment_setup). Saving the card never charges the patient.
The per-visit hold — placed only when the patient explicitly confirms a provider connection (confirm_provider_connection).

Arlo never auto-charges. The payment gate always waits for the patient’s explicit confirmation.

Checking Payment Status

Use get_payment_status to check the user’s current payment configuration:

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

Billing Mode Values

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 payment setup

Payment Status Values

Status	Description
`PENDING`	No usable payment method yet
`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

The Payment Gate

When a conversation reaches PAYMENT_REQUIRED, the paymentGate object indicates what action is needed:

{
  "status": "PAYMENT_REQUIRED",
  "paymentGate": {
    "consultationSummary": "Based on your symptoms, Arlo can help with...",
    "paymentType": "pay_per_use",
    "ctaText": "Connect with Provider - $30",
    "gateType": "PAY_PER_USE"
  }
}

Gate Types

`gateType`	Meaning	Required Action
`PAY_PER_USE`	Card on file	Confirm with the user, then `confirm_provider_connection` to place the hold
`PAYMENT_SETUP_REQUIRED`	No card yet	`create_payment_setup` first, then confirm

Pay-Per-Use Flow

Conversation reaches PAYMENT_REQUIRED

Triage is complete and the user is ready to connect with a provider

Present summary to user

Show the consultationSummary from the payment gate

User confirms

User agrees to proceed with the per-visit fee

Call confirm_provider_connection

This places the per-visit hold on the user’s card

User enters MATCHING queue

Status changes to MATCHING while finding a provider

Example

const conversation = await getConversation({ conversationId });

if (conversation.status === "PAYMENT_REQUIRED") {
  const { paymentGate } = conversation;

  // Present summary to user
  await showUser(paymentGate.consultationSummary);

  // Get user confirmation — Arlo never auto-charges
  const confirmed = await askUser(paymentGate.ctaText);

  if (confirmed) {
    await confirmProviderConnection({ conversationId });
  } else {
    await cancelRequest({ conversationId }); // dismisses the gate; conversation stays open
  }
}

Card Setup Flow

When there’s no card on file (gateType: "PAYMENT_SETUP_REQUIRED" or paymentStatus: "PENDING"):

Call create_payment_setup

Returns a Stripe-hosted card-setup URL. Saving the card does not charge the user

User saves their card

Direct the user to the paymentUrl in their browser

Poll get_payment_status

Every ~15–30 seconds (or when the user says they’re done) until paymentStatus is ACTIVE

Confirm the connection

Call confirm_provider_connection to place the per-visit hold and enter MATCHING

Stripe Integration

Arlo uses Stripe for payment processing. All card entry happens through Stripe’s hosted pages.

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

Payment Errors

Error	Cause	Resolution
`payment_hold_failed`	Card declined	`create_payment_setup` to add a different card, poll until `ACTIVE`, confirm again
`no_payment_gate`	Conversation not in `PAYMENT_REQUIRED`	Check `get_conversation` for the current status

Handling Payment Failures

try {
  await confirmProviderConnection({ conversationId });
} catch (error) {
  if (error.code === "payment_hold_failed") {
    const { paymentUrl } = await createPaymentSetup();
    await showUser(`Update payment method: ${paymentUrl}`);
    // poll get_payment_status until ACTIVE, then confirm again
  }
}

Legacy Subscriptions

Earlier versions of Arlo offered subscriptions. Grandfathered accounts (billingMode: SUBSCRIPTION or LEGACY) keep their access without per-visit setup. The REST API retains deprecated endpoints (activate, cancel) for legacy clients; they are not part of the MCP tool surface.

Getting Started

Tutorials

Concepts

Overview

Checking Payment Status

Billing Mode Values

Payment Status Values

The Payment Gate

Gate Types

Pay-Per-Use Flow

Example

Card Setup Flow

Stripe Integration

Payment Errors

Handling Payment Failures

Legacy Subscriptions

​Overview

​Checking Payment Status

​Billing Mode Values

​Payment Status Values

​The Payment Gate

​Gate Types

​Pay-Per-Use Flow

​Example

​Card Setup Flow

​Stripe Integration

​Payment Errors

​Handling Payment Failures

​Legacy Subscriptions

Overview

Checking Payment Status

Billing Mode Values

Payment Status Values

The Payment Gate

Gate Types

Pay-Per-Use Flow

Example

Card Setup Flow

Stripe Integration

Payment Errors

Handling Payment Failures

Legacy Subscriptions