Sales and transactions

Destructive

What it covers#

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

Tools#

List Tilopay transactions

Read only

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

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"
`onlyAproved`	boolean	—	Approved transactions only (true by default)
`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

Read only

tilopay_get_transaction

Returns the detail of a specific transaction from its order number.

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

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.

Sales summary and trends

Read only

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

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)	—	—
`currency`	array<string>	—	—

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

Read only

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

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)	—	—
`currency`	array<string>	—	—

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.

Capture, refund or reverse

Sensitive

tilopay_modify_transaction

Modifies a transaction: capture, refund or reversal for the given amount. Sensitive operation: it moves real money.

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

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

Returns

{ result }

Raw Tilopay API response under the `result` key.

Last verified: 2026-08-29 · Owner: equipo-integraciones

View as raw Markdown