Payments

Overview

Arlo is pay-per-use: the patient pays per provider visit, and there are no recurring subscriptions. Each visit is approved by the patient on a Stripe Checkout page, where they authorize a temporary hold for the visit price. Nothing is charged until a doctor joins, and the hold is released otherwise. There is no card on file to set up ahead of time. Onboarding completes without payment, and the Stripe link is the whole payment flow, every visit.

Arlo never auto-charges. The payment gate always waits for the patient to act on Stripe’s page.

How a visit is paid

Conversation reaches PAYMENT_REQUIRED

Triage is complete. The paymentGate object carries a consultationSummary of what a provider can help with

Relay the summary

The patient decides whether they want a visit

Call start_visit_payment

Returns a paymentUrl, a Stripe-hosted page valid for about 30 minutes

The patient approves the hold

On Stripe’s page. Stripe may offer to remember the card there; Arlo never collects card details

MATCHING

Once the hold is placed the conversation moves to MATCHING on its own. Await a provider with wait_for_reply

A doctor joins

The hold is captured. If no doctor joins, it is released

The payment gate

When a conversation reaches PAYMENT_REQUIRED, paymentGate is present on get_conversation, and inlined on the wait_for_reply or send_message result that completed triage:

{
  "status": "PAYMENT_REQUIRED",
  "paymentGate": {
    "consultationSummary": "Based on your symptoms, a provider can help with...",
    "ctaText": "Continue to payment",
    "paymentType": "pay_per_use",
    "gateType": "PAY_PER_USE",
    "isLoading": false,
    "requestId": "req_abc123"
  }
}

Field	Meaning
`consultationSummary`	Markdown summary of what Arlo can help with. Relay it before asking the patient to proceed
`paymentType`	`pay_per_use`, or `null` while the gate is still being set up (summary still generating). Re-read shortly
`gateType`	`PAY_PER_USE`. `PAYMENT_SETUP_REQUIRED` survives only on older records and is approved the same way
`isLoading`	The summary is still being generated

Every gate is approved the same way: start_visit_payment.

Checking payment status

get_payment_status returns the per-visit price and the account’s payment state:

{
  "billingMode": "PAY_AS_YOU_GO",
  "paymentStatus": "PENDING",
  "paymentOptions": [
    {
      "id": "opt_paygo",
      "title": "Pay Per Use",
      "price": "$25/visit",
      "priceAmountCents": 2500,
      "billingMode": "PAY_AS_YOU_GO"
    }
  ]
}

Both billingMode and paymentStatus are informational for US accounts. paymentStatus: "PENDING" is the normal state for an account that pays per visit, and it does not block start_visit_payment.

`billingMode`	Description
`NONE`	No payment method configured
`PAY_AS_YOU_GO`	Pay per visit, the standard mode

`paymentStatus`	Description
`PENDING`	No saved payment method. Normal
`ACTIVE`	A payment method is on file
`FAILED`	A past payment failed
`CANCELLED`	Payment method removed

Holds

A hold is a temporary authorization on the patient’s card for the visit price, not a charge.

Captured when a doctor joins the conversation.
Released when the patient cancels: cancel_request while MATCHING pulls the request back and voids the hold. The patient is not charged.
Voided after 5 days without a provider. Arlo drops the conversation back to PAYMENT_REQUIRED with a triage message explaining why, so the patient can decide whether to approve a fresh hold.

Example

const conversation = await getConversation({ conversationId });

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

  // Present the summary; Arlo never auto-charges
  await showUser(paymentGate.consultationSummary);
  const wantsVisit = await askUser("Continue to payment?");

  if (wantsVisit) {
    const { paymentUrl } = await startVisitPayment({ conversationId });
    await showUser(`Approve the visit here: ${paymentUrl}`);
    // Once approved the conversation moves to MATCHING on its own
    await waitForReply({ conversationId });
  } else {
    await cancelRequest({ conversationId }); // dismisses the gate; conversation stays open
  }
}

Payment errors

Error	Cause	Resolution
`no_payment_gate`	Conversation not in `PAYMENT_REQUIRED`	Check `get_conversation` for the current status
`summary_loading`	The gate is still being set up	Wait a moment and call `start_visit_payment` again
Link expired or cancelled	The Stripe page is short-lived (about 30 minutes)	Call `start_visit_payment` again for a fresh link

A declined card is handled on Stripe’s page; the patient retries there. Nothing reaches your agent until the hold is placed.

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

Getting Started

Tutorials

Concepts

Overview

How a visit is paid

The payment gate

Checking payment status

Holds

Example

Payment errors

Stripe integration

​Overview

​How a visit is paid

​The payment gate

​Checking payment status

​Holds

​Example

​Payment errors

​Stripe integration

Overview

How a visit is paid

The payment gate

Checking payment status

Holds

Example

Payment errors

Stripe integration