# Sales and transactions

> MCP tools to query transactions, measure sales and modify a transaction.

- kind: mcp-tool
- status: stable
- access: destructive
- last_verified: 2026-10-07
- url: https://tilopay.com/en/developers/agentes/mcp/ventas

## What it covers [#que-cubre]

This group covers reading transactions and analysing your sales, plus modifying a transaction: capture, refund or reversal. The modification moves real money and is marked as sensitive.

## Tools [#herramientas]

### Sales summary and trends [#tilopay-sales-summary]

- `tilopay_sales_summary`
- Access: Read only
- API operation: `POST /api/v1/consultTransactions (y cálculo local)` — https://tilopay.com/en/developers/api/procesos-operativos/consult-transactions

Computes sales metrics from the transactions: totals by currency, average ticket, approval rate, sales by day, weekday and hour, top customers, decline reasons and trend.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `startDate` | string | yes | Start date "YYYY-MM-DD HH:mm:ss" |
| `endDate` | string | yes | End date "YYYY-MM-DD HH:mm:ss" |
| `includeDeclined` | boolean | — | Include declined transactions to measure the approval rate (true by default) |
| `environment` | string (production | test) | — | "production" (default) or "test" (your account's test mode) |
| `currency` | array<string> | — | Array of ISO codes, e.g. ["CRC","USD"]; empty = all |

**Returns**

`{ summary, trends, environmentNote }`

summary carries range, timezoneNote, totalRows, payments {total, approved, declined, approvalRate}, refunds {total, approved, failed, successRate}, byCurrency per currency with payments, itemised costs (commission, iva_commission, cost, cost_iva, retention_iva, retention_rent, totalDeducted, taxWithholdings, pspCost), netToLiquidate, reconciles and reconciliationDelta; refunds; and netForPeriod. It also returns daily, sample, byWeekday, byHour, topCustomers, declineReasons, refundFailureReasons and transactionTypes. byWeekday, byHour and topCustomers come back null when the sample is too small (fewer than 30 rows or fewer than 5 distinct days). trends comes back null in that same case. Hours and days are in UTC.

### Sales analyst agent [#tilopay-analyze-sales]

- `tilopay_analyze_sales`
- Access: Read only
- API operation: `POST /api/v1/consultTransactions (y análisis con modelo)` — https://tilopay.com/en/developers/api/procesos-operativos/consult-transactions

Agent that analyses the transactions in a date range and returns a natural-language report: performance, trends, seasonality, approval quality, risks and actionable recommendations.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `startDate` | string | yes | Start date "YYYY-MM-DD HH:mm:ss" |
| `endDate` | string | yes | End date "YYYY-MM-DD HH:mm:ss" |
| `question` | string | — | Specific question or focus for the analysis |
| `environment` | string (production | test) | — | "production" (default) or "test" (your account's test mode) |
| `currency` | array<string> | — | Array of ISO codes, e.g. ["CRC","USD"]; empty = all |

**Returns**

`{ report, summary, trends, environmentNote }`

report is the natural-language report; summary and trends are the same ones from tilopay_sales_summary. When there are no transactions in the range it returns only a text saying so, with no structuredContent.

### Did they pay me yet? [#tilopay-find-payment]

- `tilopay_find_payment`
- Access: Read only

Checks whether a customer already paid: it reviews the Tilopay charges and, if the banking session is open, also the incoming entries of the bank account. Use it for questions like 'did Ana pay me yet?' or 'did the ₡25,000 payment come in?'.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | — | Customer name (partial match) |
| `amount` | number | — | Expected payment amount |
| `currency` | string | — | Currency of the amount, e.g. CRC or USD |
| `hours` | integer | — | Hours to look back (24 by default) |
| `reference` | string | — | Order number or reference |

**Returns**

`{ found, bank_checked, payments }`

payments = up to 5 matches with { source: "tilopay" | "baas", at, amount, currency, name, method, reference, email? }.

### List Tilopay transactions [#tilopay-list-transactions]

- `tilopay_list_transactions`
- Access: Read only
- API operation: `POST /api/v1/consultTransactions` — https://tilopay.com/en/developers/api/procesos-operativos/consult-transactions

Queries Tilopay transactions in a date range. It can filter by currency, order number, customer email and environment.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `startDate` | string | yes | Start date, e.g. "2026-08-01 00:00:00" |
| `endDate` | string | yes | End date, e.g. "2026-08-31 23:59:59" |
| `status` | string (approved | declined | all) | — | approved = only approved, declined = only declined, all = all |
| `sort` | string (newest | oldest) | — | newest = most recent first |
| `onlyAproved` | boolean | — | Compatibility: false is equivalent to status: "all" |
| `environment` | string (production | test) | — | Environment, production by default |
| `currency` | array<string> | — | Currencies, e.g. ["USD","CRC"] |
| `orderNumber` | string | — | Filter by order number |
| `email` | string | — | Filter by customer email |
| `limit` | integer | — | Maximum rows to return (100 by default, 500 maximum) |

**Returns**

`{ total, transactions[], environmentNote }`

total = rows found before applying limit; transactions = the rows returned; environmentNote warns when the queried environment returned no rows.

### Get one transaction [#tilopay-get-transaction]

- `tilopay_get_transaction`
- Access: Read only
- API operation: `POST /api/v1/consult` — https://tilopay.com/en/developers/api/procesos-operativos/consult

Gets the detail of a specific Tilopay transaction from the order number.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `orderNumber` | string | yes | Order number of the transaction |
| `merchantId` | string | — | Merchant ID (optional) |

**Returns**

`{ result }`

Raw Tilopay API response under the `result` key.

### Capture, refund or reverse [#tilopay-modify-transaction]

- `tilopay_modify_transaction`
- Access: Sensitive
- Requires confirmation: https://tilopay.com/en/developers/agentes/mcp/permisos#confirmaciones
- API operation: `POST /api/v1/processModification` — https://tilopay.com/en/developers/api/procesos-operativos/process-modification

Modifies a Tilopay transaction: capture, refund or reversal for the given amount. The amount can never exceed that of the original sale: if the user asks for more, tell them the real sale amount and ask whether to refund that amount or part of it; do not ask for confirmation of a larger amount. It only refunds approved sales, never an order that is already a refund (it starts with «Re-»). When Tilopay confirms the refund, a text receipt ready to forward to the customer is generated. Sensitive operation: it affects real money and requires a second factor. Call it first without `confirmation_code`: a 6-digit code is sent to the merchant's email and the response includes `requires_confirmation`. Repeat the same call, with the same parameters, adding `confirmation_code`. Report the result exactly as the tool returns it (state): if it is pending or not confirmed, never say the refund was already made.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `orderNumber` | string | yes | Order number of the transaction |
| `action` | string (capture | refund | reversal) | yes | Type of modification |
| `amount` | number | yes | Amount to modify, greater than zero |
| `currency` | string | — | Currency of the movement, e.g. CRC or USD |
| `client_name` | string | — | Customer name, for the receipt |
| `client_email` | string | — | Customer email, for the receipt |
| `confirmation_code` | string | — | 6-digit code received by email to authorize the operation |

**Returns**

`{ result, state, receipt_code, receipt_url, receipt_text, receipt_whatsapp_url }`

Raw Tilopay API response under the `result` key.

### Refund history [#tilopay-refunds-list]

- `tilopay_refunds_list`
- Access: Read only

The merchant's refunds. pending=true returns the refunds pending processing; otherwise, the history. Query only: to refund use tilopay_modify_transaction.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `pending` | boolean | — | Pending only |
| `page` | integer | — | Page (1 by default) |
| `limit` | integer | — | Records per page (20 by default) |
| `search` | string | — | Text to search |

**Returns**

`{ result }`

The refunds listing as Tilopay delivers it; with pending: true, only the pending ones.

### Scheduled cash close [#tilopay-cash-close]

- `tilopay_cash_close`
- Access: Write

Daily cash close (sent over WhatsApp): the day's sales per currency, declines grouped by reason and the next Tilopay settlement. Action 'get' shows the configuration; 'set' changes it (enabled, time_of_day 'HH:mm' in local time, days 0=Sunday…6=Saturday; 'Monday to Saturday' = [1,2,3,4,5,6]); 'preview' builds today's close right now. For 'turn off the close' use set with enabled=false. Only the owner can configure it.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string (get | set | preview) | yes | "get" shows the configuration, "set" changes it (owner only), "preview" builds today's close |
| `enabled` | boolean | — | Only with set: true turns it on, false turns it off. Default 20:00, Monday to Saturday |
| `time_of_day` | string | — | Local time 'HH:mm' (24 h). 8 pm = '20:00' |
| `days` | array<integer> | — | 0=Sunday … 6=Saturday |

**Returns**

Text only: the current configuration, or today's close with preview.