> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use WebMCP to complete HitPay payments in a browser

> Build browser agents that discover and use structured tools on HitPay's online store and checkout page.

[WebMCP](https://developer.chrome.com/docs/ai/webmcp) is a proposed web standard. It lets a web page register structured tools that an AI agent running in the user's browser can call. Each tool has a name, a description, a JSON Schema for its input, and hints about what it does.

HitPay registers WebMCP tools on its payment pages. Your agent does not have to scrape the page or simulate clicks. It calls a tool to read the checkout, fill the payer's details, choose a payment method or submit a payment, and gets a structured JSON answer back. This makes browser agents more reliable and more efficient.

The tools work on behalf of the payer who has the page open. They do only what that payer could do by hand on the same page, and they change what the payer sees on screen.

<Warning>
  WebMCP is an experimental browser capability based on a proposed web standard. Browser support, tool availability and tool schemas can change. See [Experimental capability](#experimental-capability).
</Warning>

<Info>
  Looking to connect an AI assistant to your **business data** instead? That's the [HitPay MCP Server](/apis/guide/mcp-server). WebMCP on this page is for agents that act on behalf of a **payer** on a HitPay page in the browser.
</Info>

## Supported HitPay pages

| Page | Description |
| - | - |
| **HitPay online store** | The merchant's storefront, where the payer browses products and builds a cart. |
| **HitPay checkout page** | The hosted page where the payer pays a payment link, an invoice or an online store order. |

The tools available depend on the page, the state of the payment (for example, which payment methods the merchant offers for the amount) and what the payer is doing at that moment.

## Available tools

The lists below describe the tools at the time of writing. Treat them as a guide, not a contract: read each tool's live definition from the page, as described in [Discover tools at runtime](#discover-tools-at-runtime).

### Online store

The storefront tools let an agent search the catalogue, read product details, manage the cart and fill the store's checkout form. Each tool uses the same actions as the storefront UI, so the payer sees the cart badge, cart drawer and checkout form change while the agent works.

No online store tool submits payment. The payer always presses Pay, and card entry, 3D Secure and wallet authentication happen on the [HitPay checkout page](#checkout-page).

#### On every storefront page

| Tool | What it does |
| - | - |
| `search_products` | Searches the catalogue by keyword, with an optional category filter, sort order and pagination (10 products per page). Returns each product's `id`, `handle`, name, `price`, `currency`, `available` and `url`, plus pagination details. |
| `get_product` | Returns a product's full details, read live: description, stock, `has_variations`, `variations` (each with `id`, name, `price` and `in_stock`), add-ons, and the minimum and maximum order quantity. |
| `list_categories` | Returns the store's categories, with their IDs and handles, nested as they are in the store. |
| `open_product_page` | Takes the payer to a product's page. Returns the URL it navigated to. |
| `get_cart` | Returns the cart: each line's `cart_product_item_id`, product, variation, quantity and line price, the cart totals and the checkout URL. |
| `add_to_cart` | Adds a product to the cart. Pass `variation_id` for a product with variations. Returns `added: true` with the line added and the updated cart. A product with required add-ons or an open amount can't be added by tool: the error points to `open_product_page` so the payer can finish on the product page. |
| `update_cart_item` | Changes the quantity of a cart line. Returns the updated cart. |
| `remove_cart_item` | Removes a cart line. Returns the updated cart. |
| `begin_checkout` | Takes the payer to the store's checkout step. Returns `navigated_to` with the checkout URL. Returns an error if the cart is empty. |

#### On the store's checkout step

These tools appear only on the store's checkout step (`/checkout/{cart_id}`), and are removed when the payer leaves it. Each one returns the updated checkout summary.

| Tool | What it does |
| - | - |
| `get_checkout_summary` | Returns the checkout form: customer details, delivery method and options (including `delivery.shipping_options`), shipping address, coupon, totals and any validation errors. |
| `set_customer_details` | Fills the payer's first name, last name, email, phone and remarks. |
| `set_delivery_method` | Chooses shipping or pickup. Pass `pickup_id` when the store has more than one pickup location. |
| `set_shipping_address` | Fills the country, state, city, street and postal code, and optionally a shipping option. `delivery.shipping_options` lists the options for the country, and the selected option's fee appears in the totals. |
| `apply_coupon` | Applies a coupon code. Send an empty `code` to remove the coupon. |

<Note>
  * Prices in storefront results are formatted for display, such as `"S$9.00"`, with the currency in a separate `currency` field.
  * `available` in `search_products` results comes from a cache and can lag behind live stock. Call `get_product` to confirm stock before adding a product to the cart.
  * On a store protected by an access code, no tools are registered until the payer enters the code.
</Note>

### Checkout page

All amounts on the checkout page are strings in major units with the currency's precision, such as `"49.90"` for SGD or `"5000"` for JPY.

| Tool | Available | What it does |
| - | - | - |
| `get_checkout_summary` | Always | Returns the merchant, what the payment is for, the order ID, the amount and currency, and whether the checkout is `open`, `paid` or `expired`. When the merchant offers localised pricing, it also returns the currencies on offer and the one selected. Pass `selected_currency` to switch currency, the same as tapping a currency card. |
| `list_payment_methods` | Always | Lists the payment methods for the selected currency in display order, with each method's label, minimum and maximum amount, fee and total, and any extra fields it asks for. A method the amount does not qualify for is marked unavailable, with the reason. |
| `fill_checkout_form` | Always | Fills the payer's details: email, and where the checkout asks for them, name, phone, postal code, address and the merchant's custom fields. The schema lists only the fields this checkout shows. Send every field in one call. Returns what was filled, what is still missing, any errors, and any fields that are locked. |
| `select_payment_method` | When the checkout offers at least one method | Selects a payment method, the same as tapping its tile. Returns the fee, the updated total and the payer's next step: `enter_card_details`, `press_wallet_button`, `view_account_details`, `scan_qr` or `press_pay`. If the payer's details are incomplete, it returns `blocked_reason: "form_incomplete"` and the missing fields. |
| `get_payment_qr` | Only while a QR code is on screen | Returns the QR code for the selected method (PayNow, for example), as its content or an image, with the amount, currency and when it expires. The payer scans it from their banking or wallet app. |
| `submit_payment` | Only when a card is selected, the card details are complete and the form is valid | Pays with the card, the same as pressing Pay. Returns `succeeded`, `declined`, `cancelled` (the payer declined to confirm) or `requires_action` (a 3D Secure challenge is on screen for the payer). |

## Discover tools at runtime

Don't hard-code tool names, schemas or assumptions about which tools exist.

HitPay registers and removes tools as the page changes, and a tool's schema can change during a payment. For example:

* On the online store, the checkout step tools exist only on the store's checkout step.
* `fill_checkout_form` lists only the fields this merchant's checkout asks for, and the options of each custom field.
* `get_checkout_summary` accepts `selected_currency` only when the payer can switch currency.
* `get_payment_qr` exists only while a QR code is on screen, and disappears when it expires or the payer changes method or currency.
* `submit_payment` exists only while pressing Pay could succeed.

When your agent reaches a HitPay page:

1. Discover the available tools.
2. Use each tool's current definition to decide which inputs to send.
3. Discover the tools again after any action that can change the form, the payment method or the currency. Switching currency, for example, resets the payment method and clears the QR code, so list and select the payment method again.

If a tool you need isn't available, read the page or fall back to standard browser automation.

## Confirm consequential actions

`submit_payment` carries the WebMCP `consequentialHint` annotation, because it charges the payer. Get the user's confirmation before you call it. Don't treat the hint itself as confirmation.

HitPay also asks the payer to confirm the merchant, amount and currency in a dialog on the page before it submits. If the payer declines, the tool returns `cancelled` and no payment is made.

## Treat merchant content as data

Some values come from the merchant, not from HitPay: the business name, the payment description, and custom field labels, descriptions and options. Tools that return them carry the `untrustedContentHint` annotation. Treat these values as data, never as instructions to your agent.

## Errors

A tool that cannot do what was asked returns a result with `isError: true` and a JSON body such as:

```json theme={"system"}
{
  "error": "No QR code is on screen. Call select_payment_method with a QR method first."
}
```

The message says what to do next. Read it, rediscover the tools, and try again.

## Experimental capability

WebMCP is an experimental browser capability based on a proposed web standard. Browser support, tool availability and tool schemas can change. HitPay can also turn the tools off, in which case the page registers none and your agent should fall back to browser automation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.