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

# Payments Overview

> Onboard your merchants to Stripe, check charge-readiness, and read their payment ledger — all through Stripe Connect

The Payments API lets a partner get its **merchants** (organizations) ready to accept card payments and monitor their activity. Telzino runs on **Stripe Connect**, which shapes how the whole surface works — read this first.

## How payments work here

<Steps>
  <Step title="Telzino is the Stripe platform — there are no merchant API keys">
    Telzino holds a single Stripe account and acts as the **platform**. Each of your merchants is a Stripe **connected account** that Telzino creates and controls. Merchants never obtain, and you never send, a Stripe secret key — you authenticate to this API with your normal Telzino access token.
  </Step>

  <Step title="You onboard a merchant">
    Call [`POST /v1/organizations/{organization_id}/payments/onboarding`](/api-reference/payments/onboarding). Telzino creates the connected account if one doesn't exist and returns a Stripe **Account Session `client_secret`** and the platform **`publishable_key`**. You render Stripe's embedded onboarding component with those two values so the merchant submits their **own** banking and identity details directly to Stripe. This is the one step that needs a browser front-end — everything else is plain REST.
  </Step>

  <Step title="The merchant becomes charge-ready">
    Once Stripe finishes verification, the connected account's `charges_enabled` flips true. Check a single merchant with [`GET /v1/organizations/{organization_id}/payments/status`](/api-reference/payments/status), or list all of yours at once with [`GET /v1/payments/merchants`](/api-reference/payments/merchants).
  </Step>

  <Step title="You arm an agent to take payments">
    Being charge-ready isn't enough on its own — you enable the payment tool on a specific **agent** with [`PUT /v1/agents/{agentId}/payments/tool`](/api-reference/payments/agent-tool). This is gated: the merchant must be charge-ready **and** the agent must have Twilio SMS configured (the link is texted to the caller). Check both preconditions first with [`GET /v1/agents/{agentId}/payments/readiness`](/api-reference/payments/agent-readiness).
  </Step>

  <Step title="Payments happen, and you read the ledger">
    Charges are created by the Telzino AI agent during calls (bounded by the per-agent guardrails you set in the previous step) — this API does **not** create charges directly. Review completed and failed payments with [`GET /v1/payments/transactions`](/api-reference/payments/transactions).
  </Step>
</Steps>

## Who can call what

Every request is authenticated with your Telzino access token and scoped to the organizations you own (account → resellers → organizations). You can only onboard, inspect, or read transactions for **your own merchants** — an organization outside your account returns `403` (or is simply absent from list results). Authentication works exactly like the rest of the API; see [Authentication](/api-reference/authentication).

## Account status values

A merchant's connected account moves through these states:

| `account_status` | Meaning                                                                           |
| ---------------- | --------------------------------------------------------------------------------- |
| `not_started`    | No connected account yet — call the onboarding endpoint                           |
| `onboarding`     | Account created; Stripe is still collecting or verifying details                  |
| `active`         | Verification complete and `charges_enabled` — the merchant can take payments      |
| `restricted`     | Stripe disabled the account (missing/failed requirements) — re-onboard to resolve |

<Note>
  A merchant can accept payments only when `account_status` is `active` **and** `charges_enabled` is `true`. Both existing status endpoints expose that as the convenience field `can_accept_payments`.
</Note>

## Endpoints

| Endpoint                                                                                             | Purpose                                                     |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [`POST /v1/organizations/{organization_id}/payments/onboarding`](/api-reference/payments/onboarding) | Start or resume a merchant's Stripe Connect onboarding      |
| [`GET /v1/organizations/{organization_id}/payments/status`](/api-reference/payments/status)          | Get one merchant's charge-readiness                         |
| [`GET /v1/payments/merchants`](/api-reference/payments/merchants)                                    | List all your merchants with charge-readiness               |
| [`GET /v1/agents/{agentId}/payments/readiness`](/api-reference/payments/agent-readiness)             | Check whether an agent can be armed, and its current config |
| [`PUT /v1/agents/{agentId}/payments/tool`](/api-reference/payments/agent-tool)                       | Enable or disable an agent's in-call payments               |
| [`GET /v1/payments/transactions`](/api-reference/payments/transactions)                              | Read the payment ledger across your merchants               |