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
}'
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();
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()
{
"agent_id": "aadcdc82-0c96-4171-a812-6d68ae71c44c",
"payment_tool_enabled": true
}
{
"error": "Max total per call must be between the max per charge ($250.00) and $10,000.00."
}
{
"error": "Forbidden"
}
{
"error": "Card payments are not available for this organization"
}
{
"error": "Agent not found"
}
{
"error": "Merchant is not charge-ready (complete Stripe onboarding first)"
}
Payments
Enable / Disable Agent Payments
Arm or disarm an agent’s ability to take card payments during calls
PUT
/
v1
/
agents
/
{agentId}
/
payments
/
tool
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
}'
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();
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()
{
"agent_id": "aadcdc82-0c96-4171-a812-6d68ae71c44c",
"payment_tool_enabled": true
}
{
"error": "Max total per call must be between the max per charge ($250.00) and $10,000.00."
}
{
"error": "Forbidden"
}
{
"error": "Card payments are not available for this organization"
}
{
"error": "Agent not found"
}
{
"error": "Merchant is not charge-ready (complete Stripe onboarding first)"
}
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
- Twilio SMS is ready for the agent — its organization has a usable Twilio connection and the agent has a From Number (the payment link is delivered by text).
GET /v1/agents/{agentId}/payments/readiness. Disabling (enabled: false) simply removes the tool and is always allowed.
Path Parameters
string
required
UUID of the agent. Must belong to an organization in your account.Example:
aadcdc82-0c96-4171-a812-6d68ae71c44cBody Parameters
boolean
required
true to arm the payment tool, false to remove it.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.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).integer
Cumulative cents allowed across one call. Used only when enabling. Must be ≥
max_single_charge_cents and ≤ 1000000 (10,000).Defaultsto‘100000‘(1,000).integer
Maximum number of payment links in one call. Used only when enabling. Must be between
1 and 20. Defaults to 5.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
}'
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();
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()
{
"agent_id": "aadcdc82-0c96-4171-a812-6d68ae71c44c",
"payment_tool_enabled": true
}
{
"error": "Max total per call must be between the max per charge ($250.00) and $10,000.00."
}
{
"error": "Forbidden"
}
{
"error": "Card payments are not available for this organization"
}
{
"error": "Agent not found"
}
{
"error": "Merchant is not charge-ready (complete Stripe onboarding first)"
}
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. 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 ready for the agent (no usable organization Twilio connection, or no From Number) |
502 | Could not verify Stripe status (transient); retry |
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.
