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

# Get Agent Payment Readiness

> Check whether an agent can be armed to take payments, and read its current in-call payment config

Reports whether an agent can be enabled to take card payments during calls, the two preconditions behind that, and — if the payment tool is already enabled — its current guardrails. Use it to discover **why** enabling is blocked before calling [`PUT /v1/agents/{agentId}/payments/tool`](/api-reference/payments/agent-tool).

Enabling in-call payments requires **both**:

1. the agent's organization is charge-ready in Stripe (`can_accept_payments`), and
2. the agent has Twilio SMS configured (`twilio_configured`) — the payment link is delivered to the caller by text.

<Note>
  The platform fee is intentionally **not** returned by this endpoint.
</Note>

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

## Query Parameters

<ParamField query="refresh" type="boolean" default="false">
  By default the merchant's Stripe charge-readiness is served from cache, so this endpoint is cheap to poll. Pass `refresh=true` to force a live re-sync from Stripe for this call (slower) — useful right after a merchant finishes onboarding.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.telzino.com/v1/agents/aadcdc82-0c96-4171-a812-6d68ae71c44c/payments/readiness" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

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

  const response = await fetch(
    `https://api.telzino.com/v1/agents/${agentId}/payments/readiness`,
    { headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' } }
  );

  const r = await response.json();
  if (!r.can_enable) {
    if (!r.can_accept_payments) console.log('Merchant not charge-ready — onboard first');
    else if (!r.twilio_configured) console.log('Configure Twilio SMS on this agent first');
  }
  ```

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

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

  response = requests.get(
      f'https://api.telzino.com/v1/agents/{agent_id}/payments/readiness',
      headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
  )

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "agent_id": "aadcdc82-0c96-4171-a812-6d68ae71c44c",
    "can_enable": true,
    "feature_locked": false,
    "can_accept_payments": true,
    "account_status": "active",
    "charges_enabled": true,
    "twilio_configured": true,
    "payment_tool_enabled": false,
    "success_url": "https://telzino.com/",
    "max_single_charge_cents": 50000,
    "max_per_call_cents": 100000,
    "max_attempts_per_call": 5
  }
  ```

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

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

  ```json 502 theme={null}
  {
    "error": "Failed to load payment status"
  }
  ```
</ResponseExample>

## Response Fields

| Field                     | Type    | Description                                                                                                                                                                                                                           |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id`                | string  | The agent UUID                                                                                                                                                                                                                        |
| `can_enable`              | boolean | `true` only when `can_accept_payments` **and** `twilio_configured` are true **and** `feature_locked` is false — i.e. every blocker is clear                                                                                           |
| `feature_locked`          | boolean | `true` when **Card Payments (Stripe)** is locked for the organization in [Feature Administration](/admin-guide/dashboard/feature-administration). Enabling the tool will return `403`; disabling an already-armed tool still succeeds |
| `can_accept_payments`     | boolean | Merchant precondition: org is `active` and `charges_enabled` in Stripe                                                                                                                                                                |
| `account_status`          | string  | Merchant Stripe status — `not_started`, `onboarding`, `active`, `restricted`                                                                                                                                                          |
| `charges_enabled`         | boolean | Whether Stripe allows the merchant to accept charges                                                                                                                                                                                  |
| `twilio_configured`       | boolean | Agent precondition: full Twilio SMS credentials are present on the agent                                                                                                                                                              |
| `payment_tool_enabled`    | boolean | Whether the in-call payment tool is currently armed on this agent                                                                                                                                                                     |
| `success_url`             | string  | Where the caller is redirected after paying (agent config)                                                                                                                                                                            |
| `max_single_charge_cents` | integer | Largest single charge allowed (agent guardrail)                                                                                                                                                                                       |
| `max_per_call_cents`      | integer | Cumulative cents allowed in one call (agent guardrail)                                                                                                                                                                                |
| `max_attempts_per_call`   | integer | Max payment links in one call (agent guardrail)                                                                                                                                                                                       |

<Note>
  When `payment_tool_enabled` is `false`, the guardrail and `success_url` fields report the **defaults** that would apply if you enabled the tool without overriding them.
</Note>