Pay with a Link Pay Token

Use a Link Pay Token (LPT) to complete a Stripe payment form that supports Link. Instead of typing card details, the agent injects a token into the checkout page. The token also fills in billing and shipping details.

A Link Pay Token is a payment credential type. Request one by setting credential_type to link_pay_token. If the checkout page doesn’t support it, use a virtual card instead.

Complete checkout

Follow these steps to check support, request approval, and complete the purchase.

Check for Link Pay Token support

Check the WebMCP tools available on the checkout page. A checkout that supports Link Pay Tokens exposes both of these tools:

get_link_pay_token_merchant returns the seller’s Stripe account ID.
set_link_pay_token submits a Link Pay Token for the payment.

If either tool isn’t available, the checkout doesn’t support Link Pay Tokens. Use a virtual card instead.

Read the merchant account ID

Call the get_link_pay_token_merchant WebMCP tool. It returns the seller’s Stripe account ID, such as acct_YOUR_MERCHANT_ACCOUNT.

If the tool returns No merchant available, use a virtual card instead.

Create the spend request

Pass --credential-type link_pay_token and the account ID. Omit the merchant name and URL. The --context value must contain at least 100 characters explaining the purchase.

link-cli spend-request create \
  --credential-type link_pay_token \
  --merchant-account-id acct_YOUR_MERCHANT_ACCOUNT \
  --amount 3500 \
  --currency usd \
  --context "Purchasing a subscription from the checkout page the agent inspected. The customer initiated this purchase through the shopping assistant." \
  --total "type:total,display_text:Total,amount:3500"

These examples create one-time requests. Link Pay Token creation also accepts recurring terms; if the customer approves a repeating limit, set them explicitly and state the per-period limit and cadence in context.

Link Pay Tokens can’t be requested alongside Shared Payment Tokens.

Wait for approval and retrieve the token

Show the approval_url to the customer and poll until the request is approved, as described in Spend requests. Then retrieve the token right before you use it:

link-cli spend-request retrieve lsrq_abc123 --include link_pay_token --format json

The response includes the token as a top-level link_pay_token string:

{
  "id": "lsrq_abc123",
  "status": "approved",
  "link_pay_token": "..."
}

The token is valid for up to 30 minutes, or until the request expires, whichever comes first. The SDKs expose the same value as link_pay_token (TypeScript and Python) or LinkPayToken (Go) when you retrieve the request with include set to link_pay_token.

Submit the token

Call the checkout page’s set_link_pay_token WebMCP tool with the link_pay_token value from the previous step:

{
  "link_pay_token": "..."
}

The tool returns Link Pay Token submitted. when it accepts the token.

Wait for the page to show a single saved card with the customer’s email, then submit the checkout.

Use an SDK

After creating an authenticated SDK client, create a Link Pay Token request with the seller’s account ID. The examples use the same parameters as the CLI flow and create live requests:

const request = await link.spendRequests.create({
  credential_type: 'link_pay_token',
  merchant_account_id: 'acct_YOUR_MERCHANT_ACCOUNT',
  amount: 3500,
  currency: 'usd',
  context:
    'Purchasing a subscription from the checkout page the agent inspected. The customer initiated this purchase through the shopping assistant.',
  totals: [{ type: 'total', display_text: 'Total', amount: 3500 }],
})

credentialType := link.CredentialTypeLinkPayToken
merchantAccountID := "acct_YOUR_MERCHANT_ACCOUNT"
amount := int64(3500)
currency := "usd"
 
_, err := client.SpendRequests.Create(ctx, link.CreateSpendRequestParams{
	CredentialType:    &credentialType,
	MerchantAccountID: &merchantAccountID,
	Amount:            &amount,
	Currency:          &currency,
	Context:           "Purchasing a subscription from the checkout page the agent inspected. The customer initiated this purchase through the shopping assistant.",
	Totals: []link.Total{
		{Type: "total", DisplayText: "Total", Amount: 3500},
	},
})
if err != nil {
	return err
}

request = client.spend_requests.create(
    credential_type="link_pay_token",
    merchant_account_id="acct_YOUR_MERCHANT_ACCOUNT",
    amount=3500,
    currency="usd",
    context=(
        "Purchasing a subscription from the checkout page the agent inspected. "
        "The customer initiated this purchase through the shopping assistant."
    ),
    totals=[{"type": "total", "display_text": "Total", "amount": 3500}],
)

Request approval and poll for the result. Retrieve the approved request with include set to link_pay_token, then submit the token through WebMCP as described in Submit the token. Keep the token in your execution layer throughout.

Handle failures

Use the returned error or spend request status to choose the next action:

The checkout doesn’t expose the tools: If either WebMCP tool is unavailable, or get_link_pay_token_merchant returns No merchant available, cancel any request you created and use a virtual card.
The token wasn’t submitted: If set_link_pay_token returns A Link Pay Token is required., retrieve the token again and pass the returned link_pay_token value.
The token expired: Tokens last up to 30 minutes. Retrieve a new one while the request is still approved. If the request has expired, create a new one.
The request needs more from the customer: Follow the requires_action instructions as described in Spend requests.

Report the outcome

Reporting is optional, but it helps improve agent checkout reliability. See Outcome reporting.

Next steps

Use these references for lifecycle details and agent setup:

Spend requests

Review the lifecycle and all available credential types.

Use Link CLI with agents

Install the payment skill so your agent follows this flow.

CLI reference

Review commands, limits, and environment variables.