---
name: talo-operations
description: Operate a Talo Pay account through the Talo Partner Hub — look up and list payments, refund (full or partial), change amounts or extend expirations, check balance and bank movements, follow events, and run sandbox payment tests with simulated transfers. Use when the user asks about their Talo payments, a buyer's transfer, a refund, their Talo balance, or wants to test a payment flow.
---

# Operating a Talo account through the Talo Partner Hub

Two ways in, same operations. Prefer the MCP tools when they are connected; otherwise use the
`talo-hub` CLI (`npx talo-hub …`). Both act on the account the key belongs to:

- `tph_test_…` → Talo **sandbox**: test money, transfers can be simulated.
- `tph_live_…` → Talo **production**: real money. Confirm with the user before any refund or
  amount change, stating the payment and the amount.

Never run `npx talo-hub disconnect` or `DELETE /api/v1/account` unless the user asks for it in
this conversation: it revokes every key and webhook of that environment and ends its dashboard
sessions.

## Connect

- MCP with OAuth (best): `claude mcp add --transport http talo https://talopartnerhub.vercel.app/api/mcp`,
  then authenticate. The user picks sandbox or production and the permissions in the browser; no
  key goes through the conversation. The tools you see are the ones that key may use.
- CLI: `npx talo-hub login` (sandbox) or `npx talo-hub login --production`. It opens the browser;
  the user authorizes in Talo and confirms the code shown in the terminal. `npx talo-hub login` waits until the person authorizes and then exits by itself (0 = connected): that exit is your signal, so don't ask them whether they authorized. Show them the link and code it prints; they compare the code in their browser. If your tool notifies you when a background command exits (Claude Code's background commands do), run it in the background and continue when that notice arrives; otherwise run it in the foreground with a timeout of at least 10 minutes. If it gets cut off, run the same command again: it picks up the same login, with the same link and code. If it expired, running it again checks once whether the person finished in Talo anyway (and collects the key), and otherwise starts a new login with a new link and code. `npx talo-hub mcp`
  prints the MCP setup (OAuth). `--with-key` is for clients without OAuth: for Claude Code it
  prints a command that reads `$TALO_HUB_API_KEY` (PowerShell: `$env:TALO_HUB_API_KEY`), so set it
  first; for `--client cursor` / `desktop` it embeds the active key.
- `get_account` / `npx talo-hub status` shows the account, environment and the key's scope
  (`read`, `charge` or `full`). `insufficient_scope` means ask for a key with more permissions.
- Docs from inside the conversation: `read_docs { page }`.

## Tasks

| The user wants | MCP tool | CLI |
|---|---|---|
| Charge someone | `create_payment` | `payments create --amount <ARS> --motive "…"` |
| A link to share (chat, Instagram, a QR), each buyer pays their own | `create_payment_link` | `links create --title "…" --amount <ARS>` (or `--min`/`--max` for an amount the buyer types) |
| See or stop links | `list_payment_links`, `get_payment_link`, `disable_payment_link` | `links list`, `links get <id>`, `links disable <id>` |
| Know whether a buyer paid | `get_payment` | `payments get <id>` |
| See recent payments | `list_payments` | `payments list --from <date>` |
| Refund | `refund_payment` (omit amount for full) | `payments refund <id> [--amount <ARS>]` |
| Fix the amount | `update_payment_price` | API `PUT /api/v1/payments/{id}/price` |
| Give more time | `extend_payment` | API `PUT /api/v1/payments/{id}/expiration` |
| Balance and movements | `get_balance`, `list_transactions` | `balance`, `transactions` |
| What happened lately | `list_events` | `events list`, `events listen` |
| Test a payment (sandbox) | `simulate_transfer` | `sandbox pay <id> [--amount <ARS>]` |

Give the buyer the **CVU or alias and the exact amount**. A payment is done when its status is
`SUCCESS` (or `OVERPAID`). `UNDERPAID` means the buyer sent less: tell the user how much is
missing (`amount - paid`) instead of treating it as paid. `EXPIRED` can't be paid any more:
create a new payment.

Refunds are asynchronous: they start `PENDING`; check again with `get_payment` after a minute.
Only one refund per payment can be pending at a time.

## Testing a flow in sandbox

1. `create_payment` with an amount (for example 15000).
2. `simulate_transfer` with the payment ID: the full price pays it; pass `amount` lower to get
   `UNDERPAID`, higher for `OVERPAID`.
3. `get_payment` shows the new status a few seconds later, and `list_events` shows
   `payment.updated` and `payment.paid`.

## Errors

Errors are `{ "error": { "code", "message" } }`.

- `talo_reconnect_required`: Talo no longer accepts the account's authorization; the user runs
  `npx talo-hub login` again (`npx talo-hub login --production` for a `tph_live_` key), or
  re-authenticates the MCP server.
- `sandbox_only`: transfers can only be simulated with a `tph_test_` key.
- `talo_rejected`: Talo refused the request; its reason is in `details.talo_message`
  (for example `refund.already.pending`, `refund.amount.exceeds.payment.amount`).