> ## 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.

# Enable / Disable Agent Payments

> Arm or disarm an agent's ability to take card payments during calls

Enables or disables the in-call payment tool on an agent. Enabling writes the payment tool and its guardrails into the agent's configuration — exactly what the voice worker reads at call time to offer payments and text the caller a Stripe link.

**Enabling is gated.** The request is rejected with `409` unless **both** preconditions hold:

* the agent's organization is charge-ready in Stripe (completed Connect onboarding), and
* the agent has Twilio SMS configured (the payment link is delivered by text).

Check these first with [`GET /v1/agents/{agentId}/payments/readiness`](/api-reference/payments/agent-readiness). **Disabling** (`enabled: false`) simply removes the tool and is always allowed.

## Path Parameters

<ParamField path="agentId" type="string" required>
  UUID of the agent. Must belong to an organization in your account.

  **Example:** `aadcdc82-0c96-4171-a812-6d68ae71c44c`
</ParamField>

## Body Parameters

<ParamField body="enabled" type="boolean" required>
  `true` to arm the payment tool, `false` to remove it.
</ParamField>

<ParamField body="success_url" type="string">
  HTTPS URL the caller is redirected to after paying. Used only when enabling; defaults to the platform default if omitted. Must be a valid `https://` URL.
</ParamField>

<ParamField body="max_single_charge_cents" type="integer">
  Largest single charge allowed, in cents. Used only when enabling. Must be between `50` ($0.50) and `1000000` ($10,000). Defaults to `50000` (\$500).
</ParamField>

<ParamField body="max_per_call_cents" type="integer">
  Cumulative cents allowed across one call. Used only when enabling. Must be **≥ `max_single_charge_cents`** and ≤ `1000000` ($10,000). Defaults to `100000` ($1,000).
</ParamField>

<ParamField body="max_attempts_per_call" type="integer">
  Maximum number of payment links in one call. Used only when enabling. Must be between `1` and `20`. Defaults to `5`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT \
    "https://api.telzino.com/v1/agents/aadcdc82-0c96-4171-a812-6d68ae71c44c/payments/tool" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "enabled": true,
      "success_url": "https://acme.example.com/thanks",
      "max_single_charge_cents": 25000,
      "max_per_call_cents": 50000,
      "max_attempts_per_call": 3
    }'
  ```

  ```javascript JavaScript theme={null}
  const agentId = 'aadcdc82-0c96-4171-a812-6d68ae71c44c';

  const response = await fetch(
    `https://api.telzino.com/v1/agents/${agentId}/payments/tool`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        enabled: true,
        success_url: 'https://acme.example.com/thanks',
        max_single_charge_cents: 25000,
      }),
    }
  );

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  agent_id = 'aadcdc82-0c96-4171-a812-6d68ae71c44c'

  response = requests.put(
      f'https://api.telzino.com/v1/agents/{agent_id}/payments/tool',
      headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
      json={'enabled': True, 'max_single_charge_cents': 25000},
  )

  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "agent_id": "aadcdc82-0c96-4171-a812-6d68ae71c44c",
    "payment_tool_enabled": true
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Max total per call must be between the max per charge ($250.00) and $10,000.00."
  }
  ```

  ```json 403 theme={null}
  {
    "error": "Forbidden"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "Card payments are not available for this organization"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Agent not found"
  }
  ```

  ```json 409 theme={null}
  {
    "error": "Merchant is not charge-ready (complete Stripe onboarding first)"
  }
  ```
</ResponseExample>

## Response Fields

| Field                  | Type    | Description                       |
| ---------------------- | ------- | --------------------------------- |
| `agent_id`             | string  | The agent UUID                    |
| `payment_tool_enabled` | boolean | The tool's state after the update |

## Status Codes

| Code  | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Tool state updated                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `400` | Malformed body, or guardrails failed validation (e.g. `max_per_call_cents` \< `max_single_charge_cents`, or a non-https `success_url`)                                                                                                                                                                                                                                                                                                                                                    |
| `401` | Missing or invalid access token                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `403` | The agent's organization is not in your account, **or** Card Payments (Stripe) is locked for it in [Feature Administration](/admin-guide/dashboard/feature-administration). Only *arming* a tool that is currently off is blocked: `enabled: false` always succeeds, and re-sending `enabled: true` for an agent whose tool is already on succeeds too — so a locked organization can still adjust its guardrails (for example lowering `max_single_charge_cents`) or switch the tool off |
| `404` | Agent not found                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `409` | Enabling blocked — merchant not charge-ready, or Twilio SMS not configured on the agent                                                                                                                                                                                                                                                                                                                                                                                                   |
| `502` | Could not verify Stripe status (transient); retry                                                                                                                                                                                                                                                                                                                                                                                                                                         |

<Warning>
  Enabling the payment tool authorizes the agent to create real charges on the merchant's Stripe account during calls, bounded by the guardrails above. The guardrails are validated server-side on every enable — the same rules the dashboard enforces.
</Warning>