Sales and transactions

tilopay_sales_summary

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.

API operation: POST /api/v1/consultTransactions (y cálculo local) — see the operation page

Parameters

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.

tilopay_analyze_sales

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

API operation: POST /api/v1/consultTransactions (y análisis con modelo) — see the operation page

Parameters

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.

tilopay_find_payment

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

Returns

{ found, bank_checked, payments }

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

tilopay_list_transactions

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

API operation: POST /api/v1/consultTransactions — see the operation page

Parameters

Returns

{ total, transactions[], environmentNote }

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

tilopay_get_transaction

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

API operation: POST /api/v1/consult — see the operation page

Parameters

Returns

{ result }

Raw Tilopay API response under the `result` key.

tilopay_modify_transaction

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.

Requires confirmation: Confirmations Tilopay requires

API operation: POST /api/v1/processModification — see the operation page

Parameters

Returns

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

Raw Tilopay API response under the `result` key.

tilopay_refunds_list

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

Parameters

Returns

{ result }

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

tilopay_cash_close

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

Returns

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