Bind Link Pay Tokens to the checkout merchant

.changeset/lpt-merchant-binding.md

@@ -0,0 +1,5 @@
+---
+'@stripe/link-cli': minor
+---
+
+Add merchant-bound Link Pay Token options to spend-request creation.

CLAUDE.md

@@ -51,7 +51,7 @@ Commands: `auth login|logout|status`, `spend-request create|update|retrieve|requ
 
 The CLI also runs as an MCP server (`--mcp`) and serves skill files via `skills` subcommand, both provided by incur.
 
-**When changing commands, flags, or schema descriptions, always update all three together:** `README.md`, `skills/create-payment-credential/SKILL.md`, the schema description strings in the relevant `schema.ts` file, and `CLAUDE.md`. These can easily drift apart.
+**When changing commands, flags, or schema descriptions, always update all four together:** `README.md`, `skills/create-payment-credential/SKILL.md`, the schema description strings in the relevant `schema.ts` file, and `CLAUDE.md`. These can easily drift apart.
 
 Input is passed via flags. Define options in the command's zod schema — incur registers CLI flags automatically from the schema.
 
@@ -76,6 +76,7 @@ CLI command is `spend-request` (user-facing). Implemented in `packages/cli/src/c
 
 Key input field notes:
 - CLI input uses `payment_method_id`; mapped to `payment_details` when calling the SDK
+- `--execution-method link_pay_token` and `--merchant-account-id acct_...` are a create-only pair for Link Pay Token checkout. The agent reads the account ID from `data-stripe-merchant-account` in the AI-agent steering DOM before creating the request; Link resolves the canonical merchant identity. LPT uses `credential_type: card`, cannot use `--test` or `--network-id`, and must not accept agent-provided merchant name or URL. Never add the target fields to the update path.
 - `context` requires min 100 characters; `amount` is in cents with max 500000
 - `--metadata` (create only) is a repeatable `key:value` flag (CLI) or a `{ key: value }` object (MCP/agent), merged into a single `metadata` string→string map. Max 50 keys, key ≤ 40 chars, value ≤ 500 chars. Reuses `parseKvString` from `line-item-parser.ts`.
 - `--test` flag creates testmode credentials (real testmode SPT from test card data) instead of livemode ones

README.md

@@ -170,6 +170,36 @@ In MCP/agent mode, pass `metadata` as a structured `{ key: value }` object.
 
 By default, a spend request provisions a virtual card. For merchants that support the [Machine Payments Protocol](https://mpp.dev) (HTTP 402) and the Stripe payment method, instead pass `--credential-type "shared_payment_token"`. 
 
+#### Link Pay Token
+
+Some Stripe checkout pages expose an AI-agent steering block that supports a
+Link Pay Token (LPT). Inspect the checkout in a browser before creating the
+SpendRequest: enable the agent checkbox, then verify that both
+`input[name="link_pay_token"]` and
+`data-stripe-merchant-account="acct_..."` are present in the same Stripe
+frame.
+
+Create an LPT-bound request with the DOM-derived account ID. Do not pass
+`--merchant-name` or `--merchant-url`; Link resolves the canonical merchant
+identity from the account ID for the approval screen.
+
+```bash
+link-cli spend-request create \
+  --payment-method-id csmrpd_xxx \
+  --execution-method link_pay_token \
+  --merchant-account-id acct_... \
+  --context "Purchasing an item from the checkout the agent inspected. The user initiated this purchase through the shopping assistant." \
+  --amount 3500 \
+  --request-approval
+```
+
+LPT requests use the default `card` credential type and do not support
+`--test`, `--network-id`, or `shared_payment_token`. After approval, retrieve
+`--include link_pay_token` immediately before using it on the same checkout
+surface. Each returned LPT is valid for up to 30 minutes, or until the
+SpendRequest expires. If either DOM marker is absent, create a regular virtual
+card SpendRequest instead; do not create an LPT request.
+
 ### Execute payment
 
 The approved spend request includes a `card` object with `number`, `cvc`, `exp_month`, `exp_year`, `billing_address`, and `valid_until`. Enter these into the merchant's checkout form. 
@@ -247,7 +277,13 @@ All commands accept `--auth <path>` to store auth credentials in a specific file
 
 A spend request moves through: **create** → **request approval** → **approved** (with credentials).
 
-**Required fields for create:** `merchant_name`, `merchant_url`, `context`, `amount`. `payment_method_id` is optional — if omitted, your default payment method will be used, or the first eligible one if no default is set.
+**Required fields for a regular card create:** `merchant_name`, `merchant_url`,
+`context`, and `amount`. `payment_method_id` is optional — if omitted,
+your default payment method will be used, or the first eligible one if no
+default is set. Shared Payment Token requests instead require `network_id`;
+Link Pay Token requests require `execution_method=link_pay_token` and the
+DOM-derived `merchant_account_id`, and Link supplies their canonical merchant
+identity.
 
 **Constraints:** `context` must be at least 100 characters; `amount` must not exceed 500000 (cents); `currency` must be a 3-letter ISO code. The user has 10 minutes from when approval is requested to approve. Approved credentials (card or SPT) are valid for 12 hours from spend request creation.
 **Test mode:** Pass `--test` to create a testmode SpendRequest. A testmode SpendRequest will return test payment credentials (e.g test card `4000009990001984`) rather than a real payment credential. Testmode SpendRequests will not charge the underlying payment method of the SpendRequest. This is useful for development and integration testing without real payment methods.

packages/cli/src/__tests__/cli.test.ts

@@ -323,6 +323,152 @@ describe('production mode', () => {
       expect(request.network_id).toBe('net_prod_abc');
     });
 
+    it('sends Link Pay Token execution fields in HTTP POST body', async () => {
+      setNextResponse(200, {
+        ...BASE_REQUEST,
+        merchant_name: 'Canonical Merchant',
+        merchant_url: 'https://canonical.example',
+      });
+
+      const result = await runProdCli(
+        'spend-request',
+        'create',
+        '--payment-method-id',
+        'pd_prod_test',
+        '--execution-method',
+        'link_pay_token',
+        '--merchant-account-id',
+        'acct_lpt_target',
+        '--context',
+        VALID_CONTEXT,
+        '--amount',
+        '5000',
+        '--no-request-approval',
+        '--json',
+      );
+
+      expect(result.exitCode).toBe(0);
+      const sentBody = JSON.parse(lastRequest.body);
+      expect(sentBody).toMatchObject({
+        payment_details: 'pd_prod_test',
+        credential_type: 'card',
+        execution_method: 'link_pay_token',
+        merchant_account_id: 'acct_lpt_target',
+      });
+      expect(sentBody.merchant_name).toBeUndefined();
+      expect(sentBody.merchant_url).toBeUndefined();
+    });
+
+    const invalidLptCreateCases = [
+      {
+        name: 'merchant-account-id without execution-method',
+        args: ['--merchant-account-id', 'acct_lpt_target'],
+        message:
+          'execution-method link_pay_token is required when merchant-account-id is provided',
+      },
+      {
+        name: 'execution-method without merchant-account-id',
+        args: ['--execution-method', 'link_pay_token'],
+        message:
+          'merchant-account-id is required when execution-method is link_pay_token',
+      },
+      {
+        name: 'blank merchant-account-id',
+        args: [
+          '--execution-method',
+          'link_pay_token',
+          '--merchant-account-id',
+          '   ',
+        ],
+        message:
+          'merchant-account-id is required when execution-method is link_pay_token',
+      },
+      {
+        name: 'shared_payment_token credential type',
+        args: [
+          '--execution-method',
+          'link_pay_token',
+          '--merchant-account-id',
+          'acct_lpt_target',
+          '--credential-type',
+          'shared_payment_token',
+        ],
+        message:
+          'credential-type must be card when execution-method is link_pay_token',
+      },
+      {
+        name: 'network-id',
+        args: [
+          '--execution-method',
+          'link_pay_token',
+          '--merchant-account-id',
+          'acct_lpt_target',
+          '--network-id',
+          'net_lpt_target',
+        ],
+        message:
+          'network-id cannot be used when execution-method is link_pay_token',
+      },
+      {
+        name: 'test mode',
+        args: [
+          '--execution-method',
+          'link_pay_token',
+          '--merchant-account-id',
+          'acct_lpt_target',
+          '--test',
+        ],
+        message: 'test cannot be used when execution-method is link_pay_token',
+      },
+      {
+        name: 'delegated approval',
+        args: [
+          '--execution-method',
+          'link_pay_token',
+          '--merchant-account-id',
+          'acct_lpt_target',
+          '--approve',
+        ],
+        message:
+          'approve cannot be used when execution-method is link_pay_token; use request-approval instead',
+      },
+      {
+        name: 'agent-provided merchant identity',
+        args: [
+          '--execution-method',
+          'link_pay_token',
+          '--merchant-account-id',
+          'acct_lpt_target',
+          '--merchant-name',
+          'Agent-provided Merchant',
+        ],
+        message:
+          'merchant-name and merchant-url cannot be used when execution-method is link_pay_token',
+      },
+    ];
+
+    for (const invalidCase of invalidLptCreateCases) {
+      it(`rejects Link Pay Token requests with ${invalidCase.name}`, async () => {
+        const result = await runProdCli(
+          'spend-request',
+          'create',
+          '--payment-method-id',
+          'pd_prod_test',
+          ...invalidCase.args,
+          '--context',
+          VALID_CONTEXT,
+          '--amount',
+          '5000',
+          '--no-request-approval',
+          '--json',
+        );
+
+        expect(result.exitCode).toBe(1);
+        expect(result.stdout + result.stderr).toContain(invalidCase.message);
+        expect(requests).toHaveLength(0);
+      });
+    }
+
     it('merges repeatable --metadata flags into a metadata object in POST body', async () => {
       setNextResponse(200, BASE_REQUEST);
 

packages/cli/src/commands/spend-request/index.tsx

@@ -99,6 +99,62 @@ export function createSpendRequestCli(
       const requestApproval = !!opts.requestApproval;
       const credentialType = opts.credentialType as CredentialType | undefined;
       const networkId = opts.networkId;
+      const executionMethod = opts.executionMethod;
+      const merchantAccountId = opts.merchantAccountId?.trim();
+      const lptExecutionRequested =
+        executionMethod !== undefined || merchantAccountId !== undefined;
+
+      if (lptExecutionRequested) {
+        if (executionMethod !== 'link_pay_token') {
+          return c.error({
+            code: 'INVALID_INPUT',
+            message:
+              'execution-method link_pay_token is required when merchant-account-id is provided',
+          });
+        }
+        if (!merchantAccountId) {
+          return c.error({
+            code: 'INVALID_INPUT',
+            message:
+              'merchant-account-id is required when execution-method is link_pay_token',
+          });
+        }
+        if (credentialType !== 'card') {
+          return c.error({
+            code: 'INVALID_INPUT',
+            message:
+              'credential-type must be card when execution-method is link_pay_token',
+          });
+        }
+        if (networkId) {
+          return c.error({
+            code: 'INVALID_INPUT',
+            message:
+              'network-id cannot be used when execution-method is link_pay_token',
+          });
+        }
+        if (opts.test) {
+          return c.error({
+            code: 'INVALID_INPUT',
+            message:
+              'test cannot be used when execution-method is link_pay_token',
+          });
+        }
+        if (opts.approve) {
+          return c.error({
+            code: 'INVALID_INPUT',
+            message:
+              'approve cannot be used when execution-method is link_pay_token; use request-approval instead',
+          });
+        }
+        if (opts.merchantName || opts.merchantUrl) {
+          return c.error({
+            code: 'INVALID_INPUT',
+            message:
+              'merchant-name and merchant-url cannot be used when execution-method is link_pay_token; Link resolves the merchant identity from merchant-account-id',
+          });
+        }
+      }
 
       if (credentialType === 'shared_payment_token' && !networkId) {
         return c.error({
@@ -123,13 +179,21 @@ export function createSpendRequestCli(
             'network-id can only be used when credential-type is shared_payment_token',
         });
       }
-      if (credentialType !== 'shared_payment_token' && !opts.merchantName) {
+      if (
+        !lptExecutionRequested &&
+        credentialType !== 'shared_payment_token' &&
+        !opts.merchantName
+      ) {
         return c.error({
           code: 'INVALID_INPUT',
           message: 'merchant-name is required when credential-type is card',
         });
       }
-      if (credentialType !== 'shared_payment_token' && !opts.merchantUrl) {
+      if (
+        !lptExecutionRequested &&
+        credentialType !== 'shared_payment_token' &&
+        !opts.merchantUrl
+      ) {
         return c.error({
           code: 'INVALID_INPUT',
           message: 'merchant-url is required when credential-type is card',
@@ -174,6 +238,8 @@ export function createSpendRequestCli(
         payment_details: opts.paymentMethodId,
         credential_type: credentialType,
         network_id: networkId,
+        execution_method: executionMethod,
+        merchant_account_id: merchantAccountId,
         amount: opts.amount,
         currency: opts.currency,
         merchant_name: opts.merchantName,

packages/cli/src/commands/spend-request/schema.ts

@@ -6,14 +6,26 @@ export const createOptions = z.object({
     .enum(['shared_payment_token', 'card'])
     .default('card')
     .describe(
-      '"card" for checkout forms/Stripe Elements; "shared_payment_token" for HTTP 402/machine payment flows',
+      '"card" for checkout forms and Link Pay Token; "shared_payment_token" for HTTP 402/machine payment flows',
     ),
   networkId: z
     .string()
     .optional()
     .describe(
       'Network ID (required for shared_payment_token) — use `link-cli mpp decode` to extract',
     ),
+  executionMethod: z
+    .enum(['link_pay_token'])
+    .optional()
+    .describe(
+      'Use link_pay_token only with merchant_account_id read from the checkout AI-agent steering DOM',
+    ),
+  merchantAccountId: z
+    .string()
+    .optional()
+    .describe(
+      'Stripe account ID from data-stripe-merchant-account; required with execution_method link_pay_token',
+    ),
   amount: z.coerce
     .number()
     .int()
@@ -25,13 +37,13 @@ export const createOptions = z.object({
     .string()
     .optional()
     .describe(
-      'Merchant name (required for card; forbidden for shared_payment_token)',
+      'Merchant name (required for regular card requests; omit for link_pay_token and shared_payment_token)',
     ),
   merchantUrl: z
     .string()
     .optional()
     .describe(
-      'Merchant URL (required for card; forbidden for shared_payment_token)',
+      'Merchant URL (required for regular card requests; omit for link_pay_token and shared_payment_token)',
     ),
   context: z
     .string()