Browser Pay tools

These tools support card payments on merchant websites. For the complete workflow, see Browser Pay. Examples show the name and arguments of an MCP tools/call request; successful tool data is in structuredContent.

Tool	Required OAuth scopes
`get_credential`	`payment:execute`, `wallet:read`, `instruction:read`, `instruction:write`
`confirm_result`	`payment:execute`

get_credential

Get a credential for the final total on a merchant checkout page. Clink checks the wallet card and purchase authorization, returning either a credential or an Operation with next_action.

Parameters

Parameter	Required	Type	Meaning
`merchantUrl`	Yes	string	HTTPS checkout page URL on a domain name, without embedded credentials. Clink retains its origin.
`amount`	Yes	positive integer	Final total including shipping and tax, in minor currency units. USD 12.50 is `1250`.
`currency`	Yes	string	Supported three-letter ISO 4217 currency code, normalized to uppercase.
`merchantName`	No	string	Merchant name, 1–100 characters.
`merchantCountryCode`	No	string	Two-letter ISO 3166-1 country code, when known.
`paymentInstrumentId`	No	string	Card selected by the user for this checkout. Obtain it from current wallet data and check `agent_pay_support: true`. Omit to use the default card. It does not change the default.
`products`	No	array	1–50 product records; shape below.
`shippingAddress`	No	object	Delivery address; shape below.

When the user selected a card, preserve the same paymentInstrumentId on subsequent calls for this checkout. Agent Pay registration does not need to be completed separately before this call; the returned authorization flow handles it when needed. Actual card availability is determined by the wallet and tool response. Each products entry has:

Field	Required	Meaning
`productId`, `productName`	Yes	Nonempty product identifier and name.
`quantity`	Yes	Positive number.
`unitPrice`	Yes	Nonnegative price in major currency units, as a number or decimal string. Prefer a decimal string.
`currencyCode`	Yes	Three-letter currency code.
`productUrl`	No	Product URL.
`extra`	No	Additional product data as an object.

When supplying shippingAddress, include street_address, address_locality, address_region, address_country (two letters), postal_code, first_name, last_name, and phone_number. extended_address is optional. Use known customer information; omit the optional object if it is unavailable.

Request

{
  "name": "get_credential",
  "arguments": {
    "merchantUrl": "https://shop.example.com/checkout",
    "merchantName": "Example Store",
    "merchantCountryCode": "US",
    "amount": 1250,
    "currency": "USD",
    "products": [
      {
        "productId": "item-001",
        "productName": "Example item",
        "quantity": 1,
        "unitPrice": "12.50",
        "currencyCode": "USD"
      }
    ]
  }
}

Response

The response uses the Operation envelope. It may also contain:

Field	Meaning
`credential`	Present when issuance succeeds. Contains either `card` or the encrypted `key` / `payload` pair.
`credential.display`	`brand` and optional `last4` for user-facing display.
`credential.expires_at`	Estimated expiry. Prefer the decrypted validity information.
`wallet_cards`	Eligible card choices when `SETUP_REQUIRED` requests `DEFAULT_CARD`. Each entry contains `paymentInstrumentId`, optional `cardScheme` and `cardLastFour`, `isDefault`, and `agent_pay_support`.
`resources.payment_order_id`	Order identifier, when available outside the credential.
`resources.payment_execution_detail_id`	Execution detail identifier, when available outside the credential.

The examples below show structuredContent; IDs, URLs, card fields, and ciphertext are placeholders.

Response examples

Card fields
Encrypted credential
User action required

Use credential.card directly. This response only confirms issuance; it does not establish the merchant payment result.

{
  "operation_id": "op_example",
  "status": "SUCCEEDED",
  "revision": 2,
  "resources": {
    "payment_order_id": "order_example",
    "payment_execution_detail_id": "detail_example"
  },
  "messages": [
    {
      "code": "credential_issued",
      "text": "A single-use card credential was issued for this checkout. It is already decrypted: do not call decrypt_credential; fill credential.card into the checkout form, then report the merchant result with confirm_result."
    }
  ],
  "credential": {
    "orderId": "order_example",
    "paymentExecutionDetailId": "detail_example",
    "clientReferenceId": "op_example",
    "status": "COMPLETED",
    "card": {
      "number": "<tokenized card number>",
      "securityCode": "<dynamic security code>",
      "expiry": "12/30"
    },
    "display": {
      "brand": "VISA",
      "last4": "1234"
    },
    "expires_at": "2030-01-01T00:10:00Z"
  }
}

Decrypt key and payload using the credential decryption example, then use the resulting card fields.

{
  "operation_id": "op_example",
  "status": "SUCCEEDED",
  "revision": 2,
  "resources": {
    "payment_order_id": "order_example",
    "payment_execution_detail_id": "detail_example"
  },
  "messages": [
    {
      "code": "credential_issued",
      "text": "A single-use card credential was issued for this checkout. It is encrypted: call decrypt_credential with credential.key and credential.payload unchanged to get the card, fill it into the checkout form, then report the merchant result with confirm_result."
    }
  ],
  "credential": {
    "key": "<base64 wrapped key>",
    "payload": "<base64 sealed payload>",
    "display": {
      "brand": "VISA",
      "last4": "1234"
    },
    "expires_at": "2030-01-01T00:10:00Z"
  }
}

Present the returned link to the user, then read op_setup_example with get_operation. See the setup completion example.

{
  "operation_id": "op_setup_example",
  "status": "ACTION_REQUIRED",
  "revision": 1,
  "next_action": {
    "action_id": "act_example",
    "type": "REDIRECT_USER",
    "description": "Ask the buyer to activate the purchase instruction with their Passkey on their own device, then wait on this operation with get_operation maxWaitSeconds 60 in the same turn.",
    "params": {
      "redirect_url": "https://agent.example.com/authorize/pi_example?instructionId=ins_example",
      "redirect_kind": "PASSKEY",
      "actor": "USER_DEVICE_ONLY"
    },
    "expected_revision": 1
  },
  "resources": {
    "instruction_id": "ins_example"
  },
  "messages": []
}

For encrypted credentials, follow the decryption reference. For an already decrypted response, credential directly contains card, orderId, paymentExecutionDetailId, and clientReferenceId. The card fields are number, securityCode, optional expiryMonth, expiryYear, expiry, dynamicDataType, dynamicDataId, and dynamicDataExpiration (Unix epoch seconds as a string). Additional payload fields can include amount (major units), currencyCode, status, cardholderName, billingAddress, paymentExecutionId, paymentTransactionId, instructionId, and mandateId.

SUCCEEDED here confirms credential issuance, not merchant payment. A later get_operation returns the issuance state without any credential. Use confirm_result after observing the merchant outcome, or report NOT_SUBMITTED if no submission occurred.

Continuation and retries

After a user authorization or card setup link completes, repeat the checkout-facts request without the setup operationId. Follow the current next_action if setup is still pending. Before a final report, repeating the same checkout facts returns the outstanding credential. If it expired before submission, the same request can obtain a replacement for the same order. After final reporting, the same facts start a new purchase. This tool has no idempotencyKey parameter. For compatibility with an earlier response that carries CONFIRM, the schema also accepts operationId, actionId, and expectedRevision together. That form must contain no checkout fields. New integrations should use the checkout-facts flow above; if an older issuing Operation shows CONFIRM, repeat the same checkout facts to obtain the current behavior.

confirm_result

Record the Agent’s observation of a Browser Pay payment. This tool does not execute payment and does not independently verify merchant success. Do not call it for UCP Checkout or direct payments.

Parameters

Parameter	Required	Type	Meaning
`orderId`	Yes	string	Issued payload `orderId`, or `resources.payment_order_id`.
`paymentExecutionDetailId`	Yes	string	Issued payload `paymentExecutionDetailId`, or `resources.payment_execution_detail_id`.
`operationId`	Yes	string	The issuing `get_credential` response’s `operation_id`; also payload `clientReferenceId`.
`outcome`	Yes	enum	`SUCCEEDED`, `FAILED`, `NOT_SUBMITTED`, or `UNKNOWN`. See below.
`paidAmount`	No	nonnegative integer	Amount displayed by the merchant success page, in minor units. Must be paired with `currency`.
`currency`	No	string	Three-letter currency code. Must be paired with `paidAmount`.
`failureReason`	No	enum	Accepted only with `FAILED` or `NOT_SUBMITTED`.

Outcome	Required observation
`SUCCEEDED`	Merchant explicitly confirmed that payment succeeded.
`FAILED`	Merchant explicitly showed failure after submission.
`NOT_SUBMITTED`	Card was never submitted. It is valid to report before clicking Pay.
`UNKNOWN`	Card was submitted, but the result cannot be determined.

failureReason accepts CARD_DECLINED, AUTHENTICATION_REQUIRED, AMOUNT_CHANGED, CREDENTIAL_EXPIRED, CREDENTIAL_LOST, MERCHANT_ERROR, BUYER_CANCELLED, or OTHER. These are alternative reporting cases for the credential above. Report success only after the merchant explicitly confirms payment.

Report success
Report recorded
Total changed

Send the identifiers from the issuing response, not the setup operation.

{
  "name": "confirm_result",
  "arguments": {
    "orderId": "order_example",
    "paymentExecutionDetailId": "detail_example",
    "operationId": "op_example",
    "outcome": "SUCCEEDED",
    "paidAmount": 1250,
    "currency": "USD"
  }
}

This structuredContent response records the Agent’s report; it is not independent payment confirmation.

{
  "payment_order_id": "order_example",
  "payment_execution_detail_id": "detail_example",
  "status": "SUCCEEDED",
  "messages": [
    {
      "code": "agent_reported_result",
      "text": "Result reported by the agent; not confirmed by the card network."
    }
  ]
}

If the total changed before submission, report NOT_SUBMITTED instead.

{
  "name": "confirm_result",
  "arguments": {
    "orderId": "order_example",
    "paymentExecutionDetailId": "detail_example",
    "operationId": "op_example",
    "outcome": "NOT_SUBMITTED",
    "failureReason": "AMOUNT_CHANGED"
  }
}

Response and reporting rules

This tool returns a result report, not an Operation envelope:

Field	Meaning
`payment_order_id`, `payment_execution_detail_id`	Payment identifiers.
`status`	Recorded result status: `SUCCEEDED`, `FAILED`, or `PENDING`.
`report_deadline`	When returned for a pending report, the deadline for a final result.
`messages`	Explanatory messages, including `agent_reported_result`.

After UNKNOWN, inspect the existing merchant transaction and report the final outcome before report_deadline; do not pay again. Repeating the same outcome is safe, but a different final outcome after one has been recorded is refused. If messages contains paid_amount_mismatch, the reported amount differed from Clink’s record and did not overwrite it.

Errors and recovery

Browser Pay business refusals return isError: true and structuredContent.error with code and message. They do not carry next_action. Missing scopes can instead produce a text-only tool error. See common error handling.

Code	Recovery
`invalid_merchant_url`	Use the actual HTTPS checkout URL with a domain name and no embedded credentials.
`unsupported_currency`	Check the checkout currency and supported ISO 4217 code.
`card_unavailable`, `card_not_supported`	Refresh `get_account_state` and let the user select an available supported card. Do not switch cards without their choice.
`encryption_key_unavailable`	Have the platform contact Clink to complete public key configuration.
`credential_outstanding`	Resolve and report the existing checkout before starting another. The original checkout facts can recover its credential.
`issuance_incomplete`	Retry `get_credential` with exactly the same checkout facts.
`credential_unavailable`	Check whether a final report already exists. If the card was never submitted, report `NOT_SUBMITTED` with `CREDENTIAL_EXPIRED` or `CREDENTIAL_LOST`, using known identifiers. Do not treat this error as proof that a submitted payment failed.
`action_not_claimable`	Read the same Operation and follow its current `next_action`; do not replay the stale action.
`not_browser_pay_payment`, `order_not_found`	Verify the three identifiers came from the same Browser Pay issuance for this user.
`result_already_reported`	A different final result exists. Inspect the existing record instead of replacing it or paying again.
`report_window_expired`	The reporting window closed and the payment was passed to manual review.
`result_reporting_unavailable`	The report could not be confirmed. Retry the same report later; do not submit payment again.
`browser_pay_unavailable`	This deployment cannot provide Browser Pay. Check the environment and available payment capabilities.

API Documentation

Clink MCP

Checkout Session

Payment

Payment Instrument

Order

Agent Payment Session

Refund

Product

Price

Coupon

Promotion Code

Subscription

Test Clock

Customer Portal

Webhook Endpoint Management

Webhooks

get_credential

Parameters

Request

Response

Continuation and retries

confirm_result

Parameters

Response and reporting rules

Errors and recovery

​get_credential

​Parameters

​Request

​Response

​Continuation and retries

​confirm_result

​Parameters

​Response and reporting rules

​Errors and recovery

get_credential

Parameters

Request

Response

Continuation and retries

confirm_result

Parameters

Response and reporting rules

Errors and recovery