HitPay Product Guide and API docs.

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.

WebMCP is an experimental browser capability based on a proposed web standard. Browser support, tool availability and tool schemas can change. See Experimental capability.

Looking to connect an AI assistant to your business data instead? That’s the HitPay MCP Server. WebMCP on this page is for agents that act on behalf of a payer on a HitPay page in the browser.

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.

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.

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.

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.

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:

Discover the available tools.
Use each tool’s current definition to decide which inputs to send.
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:

{
  "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.

Getting Started

Developers

Point of Sale

Online Store

Tools

Finance

Manage Payments

Integrations

Appendix

Use WebMCP to complete HitPay payments in a browser

Supported HitPay pages

Available tools

Online store

On every storefront page

On the store’s checkout step

Checkout page

Discover tools at runtime

Confirm consequential actions

Treat merchant content as data

Errors

Experimental capability

​Supported HitPay pages

​Available tools

​Online store

​On every storefront page

​On the store’s checkout step

​Checkout page

​Discover tools at runtime

​Confirm consequential actions

​Treat merchant content as data

​Errors

​Experimental capability

Supported HitPay pages

Available tools

Online store

On every storefront page

On the store’s checkout step

Checkout page

Discover tools at runtime

Confirm consequential actions

Treat merchant content as data

Errors

Experimental capability