Build Tools to Query Your Payment Processor

Your finance team needs to look up transactions, check payment statuses, and reconcile charges. The payment processor has a dashboard, but it is slow, requires its own login, and only one person has the credentials. Every time someone needs to verify a charge or check a settlement, they ask that one person to look it up. That person has become a bottleneck.

This playbook walks you through building read-only tools that let anyone on the finance team query payment data from their AI client. You will build a transaction lookup, a search tool with multiple filters, a daily settlement summary, and you will add explicit guardrails to make sure these tools can never create, modify, or delete payment data. By the end, your finance team can ask "Show me all payments from Acme Corp this month" and get the answer without logging into anything.

Most of this workflow happens from your AI client (Claude Desktop, ChatGPT, Cursor) through the MCP connection to Assist. The one exception is credential configuration: payment API keys should be entered directly in the Assist UI under the Permissions tab of each tool so they never pass through chat.

What you need before you start

  • An Assist workspace with an MCP connection configured in your AI client
  • Your payment processor's API base URL (for example, https://api.payments.com/v1)
  • A read-only API key (if your processor supports scoped keys, generate one with only read permissions)
  • A few sample transaction IDs, customer names, or dates you can use for testing

Phase 1: Map the payment API

Start by telling the AI what you know about your payment processor's API.

"I need to build tools to query our payment processor. The API is at https://api.payments.com/v1. It uses an API key in the Authorization header as 'Bearer {key}'. The main endpoints are /transactions, /customers, /settlements, and /refunds. I want to build read-only tools -- no creating charges, no issuing refunds, no modifying anything."

Be explicit about the read-only constraint from the start. This shapes every decision the AI makes.

"The /transactions endpoint supports GET with filters: customer_id, status (succeeded, pending, failed, refunded), amount_min, amount_max, created_after, created_before, and payment_method (card, bank_transfer, ach). It returns paginated results with a default page size of 25. The /settlements endpoint supports GET with filters: date and status (pending, paid)."

If you have API documentation, share the relevant parts. Focus on the GET endpoints -- those are the only ones you need.

Phase 2: Build the transaction lookup tool

Start with looking up a single transaction by ID. This is the simplest tool and the one the finance team uses most often.

"Create a tool called 'payments_get_transaction' that takes a transaction_id string. Call GET /transactions/{transaction_id} on the payment API. Use bearer token auth from an env var called PAYMENTS_API_KEY. Return the transaction ID, amount (in dollars, not cents), currency, status, customer name, customer email, payment method, description, created date, and any metadata."

Set up credentials and test.

In the Assist UI, open this tool's Permissions tab and configure:

  • Environment Variables: add PAYMENTS_API_KEY as a custom variable. The value input is masked so the key never enters the LLM context.
  • Network Access: add api.payments.com to the allowed domains.

See Managing Permissions for the UI flow. Then test from your AI client:

"Test payments_get_transaction with transaction_id 'txn_1MqPRJ2eZvKYlo2C5T4EqPwz'."

Review the output.

"The amount is in cents. Divide by 100 and format with two decimal places. Show the currency symbol too -- so '$142.50' instead of '14250'."

"The metadata object has useful fields like invoice_number and purchase_order. Pull those out into top-level fields in the response instead of nesting them under metadata."

"Test with a transaction ID that doesn't exist. Make sure the error message is clear."

"The error says 'Request failed with status 404'. Change it to 'Transaction not found. Verify the transaction ID and try again.'"

Phase 3: Build the transaction search tool

The finance team needs to search transactions by customer, date, amount, and status. This is the workhorse tool.

"Create a tool called 'payments_search_transactions' that searches transactions. It should accept: customer_name (optional string), customer_email (optional string), status (optional, one of 'succeeded', 'pending', 'failed', 'refunded'), amount_min (optional number in dollars), amount_max (optional number in dollars), date_from (optional ISO 8601 date), date_to (optional ISO 8601 date), payment_method (optional, one of 'card', 'bank_transfer', 'ach'), and limit (optional, default 25, max 100). If customer_name or customer_email is provided, first search /customers to get the customer_id, then use that to filter /transactions. Return each transaction with ID, amount, status, customer name, payment method, date, and description."

This tool has more moving parts because it may need to look up the customer first. Test it step by step.

"Test payments_search_transactions with customer_name 'Acme Corp'."

"That works. Now test with status 'failed' and date_from '2024-03-01' to see all failed transactions in March."

"The results don't show which customer each failed transaction belongs to. Add the customer name and email to each result."

"Test with amount_min 1000 and amount_max 5000 to see mid-range transactions."

Watch out for the amount conversion.

"I passed amount_min as 1000 meaning $1,000 but the API expects cents. Convert the dollar amounts to cents before sending them to the API."

"Test again. Now the filter works correctly."

Add a summary to make the results more useful.

"Add a summary at the top of the response: total number of transactions, total amount, and a breakdown by status. So if I search for 'Acme Corp' I can see at a glance that they have 15 transactions totaling $47,250 with 13 succeeded and 2 refunded."

Phase 4: Build the daily settlement summary tool

The finance team reconciles daily settlements. They need a clear view of what settled on a given date.

"Create a tool called 'payments_daily_settlement' that takes a date (ISO 8601, defaults to yesterday). Call GET /settlements?date={date} to get the settlement for that date. Then for each settlement, fetch the transactions included in it using GET /settlements/{settlement_id}/transactions. Return: the settlement date, settlement status (pending or paid), total amount, fee amount, net amount, transaction count, and a breakdown by payment method (how many card vs bank_transfer vs ach, and subtotals for each). Also list the top 5 transactions by amount."

This is a multi-step tool -- it fetches the settlement, then fetches the transactions within it, then computes summaries.

"Test payments_daily_settlement with yesterday's date."

"The settlement amount and net amount look right. But the fee breakdown is missing -- can you add a line showing the total fees charged and the effective fee rate as a percentage?"

"The top 5 transactions should show the customer name, not just the customer ID. Fetch customer details for those transactions."

"Test with a date that has no settlement (like a Sunday). Make sure it returns a clear message instead of an error."

"Good. Now test with today's date. If there's a pending settlement, it should show 'pending' status and note that the numbers may not be final."

Add comparison data to make reconciliation easier.

"Add a comparison to the previous settlement day. Show the difference in total amount, transaction count, and net amount. Something like 'vs previous: +$2,340 (+12%), +8 transactions'."

"The comparison is helpful but the percentage calculation is wrong when the previous day's amount is zero. Add a check for division by zero."

Phase 5: Add guardrails for read-only access

This is critical. You are giving the finance team direct access to payment data. You need to make absolutely sure these tools cannot accidentally (or intentionally) mutate anything.

"Review all four payment tools and confirm that none of them use POST, PUT, PATCH, or DELETE HTTP methods. Every request should be GET only. If any tool is using a non-GET method, fix it."

"Add a comment at the top of each tool's code that says: 'READ ONLY -- This tool must never create, modify, or delete payment data. All requests must use GET.' This serves as documentation for anyone who edits the tools later."

If your payment processor supports scoped API keys, use one with read-only permissions. Generate a new key in your payment processor's dashboard with only the read scope, then update it in the Assist UI:

  1. Open the tool and click the Permissions tab.
  2. In the Environment Variables section, remove the existing PAYMENTS_API_KEY entry.
  3. Add PAYMENTS_API_KEY again with the new read-only key value.

Never paste API keys into chat. The masked value input in the Permissions tab is the only safe place to enter them.

This is defense in depth. Even if someone modifies the tool code to use a POST request, the API key does not have permission to write. And even if the API key somehow had write permission, the tool code only uses GET. Both layers would have to fail for a mutation to happen.

"Add error handling to each tool that explicitly checks the HTTP method before making a request. If for any reason a non-GET request is about to be made, throw an error instead of making the call."

"Test payments_get_transaction again to make sure the guardrail didn't break anything."

Phase 6: Configure credentials for production

Make sure all tools are using the same API key and the configuration is clean. The AI can tell you which env vars each tool's code references, but the values live only in the Permissions tab of each tool.

"List the environment variables each payment tool's code expects. Confirm they all reference PAYMENTS_API_KEY."

For each tool, open the Permissions tab and verify that PAYMENTS_API_KEY is set. If your workspace has a payment processor connection configured, prefer linking to it: in the Environment Variables section, switch to the From Connection tab and link PAYMENTS_API_KEY to the "Payment Processor (Read Only)" connection. That way, rotating the key in one place updates every tool.

Verify network permissions are minimal. In each tool's Permissions tab, confirm that Network Access contains only api.payments.com and remove any other domains.

Phase 7: Test realistic workflows

Test the way the finance team will actually use these tools.

"A customer called saying they were charged twice for order INV-2024-0847. Can you find the transactions related to that invoice?"

The AI should use payments_search_transactions or payments_get_transaction to find transactions with that invoice number in the metadata. This tests whether the metadata fields you exposed earlier are actually useful.

"What was our total revenue last week?"

The AI should search for succeeded transactions from last week and sum the amounts.

"Show me yesterday's settlement and highlight any transactions over $5,000."

The AI should use payments_daily_settlement for yesterday and filter the results.

"We have a discrepancy in yesterday's reconciliation. The settlement shows $47,250 but our system shows $47,100. Can you show me all transactions in yesterday's settlement sorted by amount?"

This is a real scenario. The AI should pull up the settlement details and sort the transactions so the finance team can find the $150 difference.

If any of these workflows feel clunky, improve the tool descriptions so the AI picks the right tool.

"Update the description for payments_search_transactions to mention that it can search by invoice number and purchase order number from transaction metadata. The AI needs to know those fields are searchable."

Phase 8: Commit and publish

When everything is tested and the guardrails are in place, publish.

"Commit and publish payments_get_transaction with the message 'Read-only transaction lookup by ID with formatted amounts and metadata extraction'."

"Commit and publish payments_search_transactions with the message 'Read-only transaction search with customer, date, amount, status, and payment method filters'."

"Commit and publish payments_daily_settlement with the message 'Read-only daily settlement summary with payment method breakdown and day-over-day comparison'."

Each tool is now live in your workspace. The finance team can use them immediately.

What you built

  • payments_get_transaction -- Looks up a single transaction by ID with formatted amounts, customer details, and extracted metadata fields
  • payments_search_transactions -- Searches transactions by customer, date, amount, status, and payment method with summary statistics
  • payments_daily_settlement -- Pulls a daily settlement report with payment method breakdown, top transactions, and comparison to the previous day

All three tools are strictly read-only with multiple layers of protection: GET-only code, read-scoped API keys, and explicit method checking. Your finance team can query payment data from their AI client without the risk of accidentally modifying anything.

Related guides