# Recipes

> Fourteen end-to-end flows with the MCP server: insights dashboard, selling over WhatsApp, recovering failed recurring charges, B2B collections, cash projection with banking data, anomaly detection, month-end close, refunds, recurring subscriptions, plan optimisation, stored-card charges, pausing or cancelling subscribers, integration debugging and Tilopay as a tool for other agents.

- kind: guide
- status: stable
- last_verified: 2026-10-20
- url: https://tilopay.com/en/developers/agentes/mcp/recetas

## Build a real-time insights dashboard [#dashboard-insights]

1. `tilopay_sales_summary` brings totals, costs and net for the period you want to monitor.
2. `tilopay_analyze_sales` turns those numbers into a narrative summary with trends and observations.
3. `tilopay_list_transactions` lists recent transactions to complete the board.
4. `tilopay_get_transaction` opens the detail of any operation that needs review.

> **Warning:** The summary uses UTC, not local time. If you have low volume, trends and top customers may
>   come back empty.

### Example dashboard questions [#ejemplos-dashboard]

- “How did I do today?” → `tilopay_sales_summary` + `tilopay_analyze_sales`.
- “What are my best-selling products or services this week?” → `tilopay_analyze_sales` over the
  last 7 days.
- “Do I have failed or pending transactions?” → `tilopay_list_transactions` filtered by status,
  then `tilopay_get_transaction` for each case.
- “How are my net earnings evolving versus last month?” → compare two `tilopay_sales_summary`
  calls with different date windows.

## Sell over WhatsApp from the catalogue [#cobrar-por-whatsapp]

1. `tilopay_catalog_list_items` lists your products or services so the agent answers
   the customer with real names and prices.
2. `tilopay_catalog_get_item` opens the chosen item when price, currency or description must be
   confirmed before building the order.
3. The agent builds the order, computes the total and confirms it with the customer before charging.
4. `tilopay_save_contact` stores the buyer (name, email, phone) to attach them to the charge and
   reuse them in future sales.
5. `tilopay_create_charge` creates the link for the order total, with a description that
   identifies the order.
6. `tilopay_send_payment_link_whatsapp` prepares the message to the customer.
7. `tilopay_get_payment_link` checks the link status to confirm payment and close the conversation
   with the receipt.

`tilopay_send_payment_link_whatsapp` does not send the message: it returns a `wa.me` link with the
text ready to send in one tap. If there is no phone and no saved contact with that name, the tool
asks for it. The agent can keep polling `tilopay_get_payment_link` to notify you as soon as
the link is paid.

> **Note:** With this recipe a merchant without an online store sells end to end inside the chat: catalogue,
>   order, charge and confirmation, with no human intervention beyond what you choose to
>   require.

## Recover failed recurring charges (smart dunning) [#dunning-inteligente]

1. `tilopay_recurring_list_plans` lists your active plans.
2. `tilopay_recurring_subscriber_payments` walks the payments of each plan's subscribers and
   separates the period's declined charges.
3. `tilopay_get_transaction` opens each decline to read the response code and classify the cause:
   insufficient funds, expired card, blocked card, suspected fraud.
4. Based on the cause, the agent decides the action and proposes it to you: wait for the
   plan's retry when the decline is transient (insufficient funds), or ask the customer for a new
   payment method when it is final (expired or blocked card).
5. `tilopay_create_charge` creates a link for the outstanding amount when the customer must
   pay the instalment with another card.
6. `tilopay_send_payment_link_whatsapp` or `tilopay_send_payment_link_email` prepares the message
   to the customer with wording adapted to the decline reason.
7. `tilopay_get_payment_link` confirms when the customer paid, and `tilopay_recurring_get_subscriber`
   verifies the subscriber's status after recovery.

An agent running this recipe every morning turns the decline list into two queues: the one that
resolves itself with the plan's retry and the one that needs a message to the customer. You
only receives the summary: how many charges were recovered and which remain pending.

> **Warning:** Do not use `tilopay_recurring_manage_subscriber` to "punish" a decline: `pause` and `delete`
>   affect future charges and `delete` cannot be undone. Pausing or removing a subscriber is a
>   merchant decision with explicit human confirmation, never an automatic reaction to a failed
>   charge.

## B2B collections with accounts receivable [#cobranza-b2b]

1. `tilopay_list_contacts` brings your business customers; `tilopay_save_contact`
   registers the missing ones with the payer's name, email and phone.
2. `tilopay_create_charge` creates a link per outstanding invoice, with the invoice number in
   the description.
3. `tilopay_send_payment_link_email` prepares the first send; `tilopay_send_payment_link_whatsapp`
   prepares the reminder when the invoice is still unpaid.
4. `tilopay_get_payment_link` checks each link's status to update the receivables list without
   opening the panel.
5. `baas_search_payment` or `baas_list_payments` look in your bank accounts for a direct
   transfer (SINPE or bank transfer) matching the amount and customer, to mark as paid an invoice
   the customer settled outside the link.
6. `tilopay_delete_payment_link` removes the link of an invoice already paid by transfer, to avoid
   a double charge.

This recipe answers the "have they paid me yet?" that eats administrative hours in businesses that
invoice companies: one list with invoices, links, status and payments received through any channel.

> **Note:** This recipe only uses read-only `baas_*` tools. `baas_send_transfer` exists, but it requires the
>   code sent to the email and is not part of this recipe. The `baas_*` tools require Tilopay to have
>   registered the merchant's banking API credentials; if they are not configured, the tool says so
>   and the recipe keeps working with payment links alone.

## Project cash with gateway and bank data (pocket CFO) [#cfo-de-bolsillo]

1. `tilopay_sales_summary` brings the last weeks of sales to estimate expected income for the next
   period.
2. `tilopay_recurring_list_plans` and `tilopay_recurring_get_plan` quantify committed recurring
   charges and their dates.
3. `baas_list_balances` or `baas_get_balance` bring the real balance of each of your bank
   accounts.
4. `baas_list_payments` lists the last months of transfers to detect recurring outflows: payroll,
   rent, suppliers.
5. `baas_analyze_payments` summarises those movements in natural language to identify patterns and
   peak dates.
6. The agent combines balance, expected inflows and expected outflows into a daily projection,
   flags the days with minimum or negative balance and proposes actions.
7. `tilopay_create_charge` and `tilopay_send_payment_link_email` put outstanding invoices out
   for collection when you approve that action.

The value is in crossing two sources that normally live apart: the gateway knows what is coming in
and the bank knows what is there and what goes out. A weekly routine produces a short briefing with
the projection and the alerts, before the business opens.

> **Warning:** This recipe only uses read-only `baas_*` tools. `baas_send_transfer` exists, but it requires the
>   code sent to the email and is not part of this recipe. If the projection suggests moving funds
>   between accounts, a person executes that with the bank's confirmation; the agent only recommends
>   and records it. The projection is an estimate, not a financial statement.

## Detect anomalies and act [#detector-anomalias]

1. `tilopay_sales_summary` compares the current window (for example the last hour or the day)
   against the same reference period to detect approval drops, decline spikes or sudden changes in
   average ticket.
2. `tilopay_list_transactions` filters by status to see whether declines concentrate on one payment
   method, one currency or a pattern of repeated attempts.
3. `tilopay_get_transaction` opens representative cases to read the response codes.
4. `tilopay_diagnostics` checks credentials and endpoint availability to separate a problem in the
   merchant's integration from a problem with customers or issuers.
5. `tilopay_help_guides` searches the official guides for the explanation and the fix that match the
   response code or the symptom.
6. The agent raises the alert with the diagnosis already done: what changed, since when, probable
   cause and suggested action.

> **Warning:** The sales summary uses UTC. When comparing short windows, align the hours; a "drop" at local
>   midnight may just be the UTC day cut. Many declined attempts in a few minutes with small amounts
>   and different cards may indicate stolen-card testing: report it to support instead of retrying.

## Close the month sales [#cierre-de-mes]

1. `tilopay_sales_summary` returns totals, costs and net for the period.
2. `tilopay_analyze_sales` produces the natural-language report.
3. `tilopay_get_transaction` brings the detail of the transactions that need review.

> **Warning:** The hours and days in the summary are in UTC, not local time. Trends and top customers come back
>   empty when the sample is small.

## Refund with human confirmation [#reembolso]

1. `tilopay_list_transactions` locates the transaction in the date range.
2. `tilopay_get_transaction` shows the detail to confirm it is the right one.
3. The agent asks the user for confirmation. That step is enforced by the MCP client, not by Tilopay.
4. `tilopay_modify_transaction` runs the modification with the action and the amount.

## Review a recurring subscription [#suscripcion-recurrente]

1. `tilopay_recurring_list_plans` lists you recurring billing plans.
2. `tilopay_recurring_get_plan` opens the plan you care about by its ID.
3. `tilopay_recurring_get_subscriber` shows the subscriber detail.
4. `tilopay_recurring_subscriber_payments` lists that subscriber payments to see which went through
   and which did not.

Useful to answer "why does this customer show no charge this month?" without opening the dashboard.

## Optimise subscription plans [#optimizar-planes]

1. `tilopay_recurring_list_plans` lists the active plans with price and frequency.
2. `tilopay_recurring_get_plan` opens each plan for its subscriber count and configuration.
3. `tilopay_recurring_subscriber_payments` walks payments per subscriber to compute, per plan, the
   successful-charge rate, the month when most subscribers stop paying and the average tenure.
4. `tilopay_recurring_get_subscriber` reviews the outliers the analysis flags.
5. The agent presents the comparison between plans: retention, revenue per subscriber and churn
   point, and proposes changes to price, frequency or content.
6. `tilopay_create_charge` lets you test a new offer with a small segment of contacts before
   modifying a plan.

This is pricing analysis with real charge data. The agent does not modify plans: it proposes, and
you decide in the panel.

## Pause or cancel a subscriber [#pausar-suscriptor]

1. `tilopay_recurring_get_subscriber` confirms the subscriber is the right one.
2. The agent asks the user for confirmation, with the name and the plan in plain sight.
3. `tilopay_recurring_manage_subscriber` runs `pause`, `reactivate` or `delete`.

> **Warning:** `tilopay_recurring_manage_subscriber` is marked sensitive: it affects future charges and `delete`
>   cannot be undone. Never run it without explicit human confirmation.

## Charge a group with stored cards [#cobro-masivo]

1. `tilopay_saved_cards_list_groups` lists the collection groups.
2. `tilopay_saved_cards_list_affiliates` shows the affiliates of the chosen group, so you know how
   many cards will be charged.
3. The agent summarises amount, currency, reason and number of affiliates, and asks for confirmation.
4. `tilopay_saved_cards_create_payments` creates the charges.
5. `tilopay_saved_cards_list_collections` and `tilopay_saved_cards_collection_detail` review the
   result: the second one needs the `code` returned by the first.

> **Warning:** `tilopay_saved_cards_create_payments` moves real money from the stored cards. Treat it as a
>   one-shot operation: confirm before, and verify after with the collection detail.

## Debug an integration and support a developer [#depurar-integracion]

1. `tilopay_diagnostics` tests the credentials and one endpoint per API group, to separate a
   credentials problem from a request problem.
2. `tilopay_debug_code` receives the code snippet, log or stack trace and returns diagnosis, root
   cause, fix and risks.
3. `tilopay_help_guides` answers panel usage questions with the official guides.
4. `tilopay_list_transactions` and `tilopay_get_transaction` confirm whether the operation the
   developer believes failed actually reached Tilopay, and with what result.

`tilopay_debug_code` does not read the repository or run the code: it analyses only what you pass
in. Strip credentials from the snippet before sending; the tool masks what it recognises as a secret,
but that does not replace your review.

With these four tools a support agent handles the whole technical onboarding: verifies the account,
finds the cause of the error, delivers the fix with the official guide and confirms against real
transactions. Repeated questions are the signal of which guide or example the portal still needs.

> **Note:** Sandbox test cards are in the portal's testing guide. Sandbox mode is switched from the account;
>   there is no separate host.

## Tilopay as a tool for other agents [#tilopay-como-herramienta]

1. Access is self-service: you add the MCP server in your client with the URL
   `https://mcp.tilopay.com/mcp` and authorize the session with your Tilopay account email and
   password, plus the verification code we send. There is no form and no prior approval.
2. The external agent (an ERP assistant, an online-store bot, an accounting agent) connects to the
   MCP server with that OAuth session and runs `tilopay_diagnostics` to verify the connection.
3. With the tool catalogue loaded, the external agent uses the read tools (`tilopay_sales_summary`,
   `tilopay_list_transactions`, `tilopay_recurring_*`, `baas_*`) to answer business questions inside
   its own conversation.
4. For actions that create or move money (`tilopay_create_charge`,
   `tilopay_modify_transaction`, `tilopay_saved_cards_create_payments`,
   `tilopay_recurring_manage_subscriber`) the external agent applies the confirmation policy
   described on the permissions page before executing.

This recipe changes the MCP's position: it is not just an assistant inside Tilopay, it is the
payments layer any agent can call. Every other recipe on this page works the same when a third-party
agent runs it.

> **Warning:** MCP usage may carry additional costs depending on volume; Tilopay communicates them to the
>   merchant. Tools marked as sensitive require human confirmation in whichever
>   MCP client runs them, Tilopay's or a third party's.

Want these recipes packaged and repeatable? [Install a skill](/en/developers/agentes/mcp/skills).