create-payment-credential

by danhill-stripe

Install this Skill

curl -fsSL -o create-payment-credential.zip https://skill.seembox.com/api/v1/skills/create-payment-credential/download && unzip create-payment-credential.zip

Download create-payment-credential.zip

SKILL.md About

---
name: create-payment-credential
description: |
  Gets secure, one-time-use payment credentials (cards, tokens) from a Link wallet so agents can complete purchases on behalf of users. Use when the user says "get me a card", "buy something", "pay for X", "make a purchase", "I need to pay", "complete checkout", or asks to transact on any merchant site. Use when the user asks to connect or log in to or sign up for their Link account.
allowed-tools:
 - Bash(link-cli:*)
 - Bash(npx:*)
 - Bash(npm:*)
license: Complete terms in LICENSE
version: 0.0.1
metadata:
  author: stripe
  url: link.com/agents
  openclaw:
    emoji: "💳"
    homepage: https://link.com/agents
    requires:
      bins:
        - link-cli
    install:
      - kind: node
        package: "@stripe/link-cli"
        bins: [link-cli]
user-invocable: true
---

# Creating Payment Credentials

Use Link to get secure, one-time-use payment credentials from a Link wallet to complete purchases.

## Choosing how to call Link

Link CLI can run as an **MCP server** or as a **standalone CLI**. Always prefer the MCP server when available — it avoids shell parsing issues and is the intended integration path.

1. **Check for the MCP server first.** Look for a `link-cli` MCP server in your active MCP connections. If present, call its tools directly (e.g. `auth_status`, `auth_login`, `spend-request_create`, `payment-methods_list`, `mpp_pay`, `mpp_decode`).
2. **Fall back to the CLI** only if the MCP server is not available. Install it with `npm install -g @stripe/link-cli`, then use the shell commands documented below.

The rest of this document shows CLI commands. When using the MCP server, map each command to its corresponding MCP tool — the parameters and behavior are identical.

| CLI command | MCP tool |
|---|---|
| `auth login` | `mcp__link-cli__auth_login` |
| `auth logout` | `mcp__link-cli__auth_logout` |
| `auth status` | `mcp__link-cli__auth_status` |
| `spend-request create` | `mcp__link-cli__spend-request_create` |
| `spend-request update` | `mcp__link-cli__spend-request_update` |
| `spend-request retrieve` | `mcp__link-cli__spend-request_retrieve` |
| `spend-request request-approval` | `mcp__link-cli__spend-request_request-approval` |
| `payment-methods list` | `mcp__link-cli__payment-methods_list` |
| `payment-methods add` | `mcp__link-cli__payment-methods_add` |
| `mpp pay` | `mcp__link-cli__mpp_pay` |
| `mpp decode` | `mcp__link-cli__mpp_decode` |

## Running commands (CLI fallback)

All commands support `--format json` for machine-readable output. Pass input via flags (run `link-cli <command> --help` to see full schema details, including all fields, types, and constraints).

IMPORTANT: Run `auth login` with `run_in_background=true` (or `TaskOutput(task_id, block: false)`). It emits JSON to stdout before it exits, then keeps running while it polls for user action.

The agent-facing JSON contract is:

- `auth login --format json`: first object contains `verification_url` and `phrase`; final object contains authentication result after approval succeeds
- `spend-request create --request-approval --format json`: returns the created spend request immediately with an `_next.command` polling hint
- `spend-request request-approval --format json`: returns the approval link immediately with an `_next.command` polling hint
- `spend-request retrieve <id> --interval <seconds> --format json`: polls until the spend request reaches a terminal status, then returns the terminal spend request. It exits non-zero with `code: "POLLING_TIMEOUT"` if `--timeout` is reached or `--max-attempts` is exhausted while the request is still non-terminal.

For `auth login`, keep reading stdout until the process exits. For spend request approval, present the `approval_url` to the user and start the `_next.command` polling command immediately. The user MUST visit the verification or approval URL to continue, and you should always show that full URL in clear text.

## Core flow

Copy this checklist and track progress:

- Step 1: Authenticate with Link
- Step 2: Evaluate merchant site (determine credential type)
- Step 3: Get payment methods
- Step 4: Create spend request with correct credential type
- Step 5: Complete payment

### Step 1: Authenticate with Link

Check auth status:

```bash
link-cli auth status --format json
```

If the response includes an `update` field, a newer version of `link-cli` is available — run the `update_command` from that field to upgrade before proceeding.

If not authenticated:

```bash
link-cli auth login --client-name "<your-agent-name>" --format json
```

Replace `<your-agent-name>` with the name of your agent or application (e.g. `"Personal Assistant", "Shopping Bot"`). This name appears in the user's Link app when they approve the connection. Use a clear, unique, identifiable name. Display the url and phrase to the user, with the guidance "Please visit the following URL to approve secure access to Link.”

DO NOT PROCEED until the user is authenticated with Link.

Always check the current authentication status before starting a new login flow - the user may already be logged in.

### Step 2: Evaluate the merchant site BEFORE creating a spend request

**CRITICAL** before calling `spend-request create` you must complete this checklist:
1. Understand how the merchant accepts payments (cards or machine payments or other). **Do NOT default to `card` credential type. The merchant determines the credential type — you cannot know it without checking first. Skipping this step will produce a spend request with the wrong credential type.
2. Have the final total amount needed. Inclusive of any shipping costs, taxes or other costs. Skipping this step will produce a spend request that does not cover the full amount needed, and will be rejected.
3. Clear context and understanding of what the user is purchasing. Be sure to know sizes, colors, shipping options, etc. Skipping this step will produce a spend request that the user does not recognize or understand.

**Determine how the merchant accepts payment:**

1. **Navigate to the merchant page** — browse it, read the page content, and understand how the site accepts payment.
2. **If the page has a credit card form, Stripe Elements, or traditional checkout UI** — use `card`.
3. **If the page describes an API or programmatic payment flow** — make a request to the relevant endpoint. If it returns **HTTP 402** with a `www-authenticate` header, use `shared_payment_token`.

What you find determines which credential type to use:

| What you see | Credential type | What to request |
|---|---|---|
| Credit card form / Stripe Elements | `card` (default) | Card |
| HTTP 402 with `method="stripe"` in `www-authenticate` | `shared_payment_token` | Shared payment token (SPT) |
| HTTP 402 without `method="stripe"` in `www-authenticate` | not supported | Do not continue |

**For 402 responses:** The `www-authenticate` header may contain **multiple** payment challenges (e.g. `tempo`, `stripe`) in a single header value. Do not try to decode the payload manually. Pass the **full raw `WWW-Authenticate` header value** to Link CLI and let `mpp decode` select and validate the `method="stripe"` challenge.

To derive `network_id`, use Link CLI's challenge decoder:

```bash
link-cli mpp decode --challenge '<raw WWW-Authenticate header>' --format json
```

This validates the Stripe challenge, decodes the `request` payload, and returns both the extracted `network_id` and the decoded request JSON. Pass the full header exactly as received, even if it also contains non-Stripe or multiple `Payment` challenges.

### Step 3: Get payment methods

Use the default payment method, unless the user explicitly asks to select a different one.

```bash
link-cli payment-methods list --format json
```

### Step 4: Create the spend request with the right credential type

```bash
link-cli spend-request create \
  --payment-method-id <id> \
  --amount <cents> \
  --context "<description>" \
  --merchant-name "<name>" \
  --merchant-url "<url>" \
  --format json
```

After creating or requesting approval for a spend request, run the returned `_next.command` to poll for the terminal status. Do not proceed to payment while the request is still `created` or `pending_approval`. If polling exits with `POLLING_TIMEOUT`, keep waiting or ask the user whether to continue polling. If they deny, ask for clarification what to do next.

Recommend the user approves with the [Link app](https://link.com/download). Show the download URL.

**Test mode:** Add `--test` to create testmode credentials instead of real ones. Useful for development and integration testing.

### Step 5: Complete payment

**Card:** Run `link-cli spend-request retrieve <id> --include card --format json` to get the `card` object with `number`, `cvc`, `exp_month`, `exp_year`, `billing_address` (name, line1, line2, city, state, postal_code, country), and `valid_until` (unix timestamp — the card stops working after this time). Enter these details into the merchant's checkout form.

**SPT with 402 flow:** The SPT is **one-time use** — if the payment fails, you need a new spend request and new SPT.

```bash
link-cli mpp pay <url> --spend-request-id <id> [--method POST] [--data '{"amount":100}'] [--header 'Name: Value'] --format json
```

`mpp pay` handles the full 402 flow automatically: probes the URL, parses the `www-authenticate` header, builds the `Authorization: Payment` credential using the SPT, and retries.

## Important

- Treat the user's payment methods and credentials extremely carefully — card numbers and SPTs grant real spending power; leaking them outside a secure checkout could result in unauthorized charges the user cannot reverse.
- Respect `/agents.txt` and `/llm.txt` and other directives on sites you browse — these files declare whether the site permits automated agent interactions; ignoring them may violate the merchant's terms.
- Avoid suspicious merchants, checkout pages and websites — phishing pages that mimic legitimate merchants can steal credentials; if anything about the page feels off (mismatched domain, unusual redirect, unexpected login prompt), stop and ask the user to verify.
- When outputting card information to the user apply basic masking to the card number and address to protect their information. Only reveal the raw values if directly requested to do so.

## Errors

All errors are output as JSON with `code` and `message` fields, with exit code 1.

### Common errors and recovery

| Error / Symptom | Cause | Recovery |
|---|---|---|
| `verification-failed` in error body from `mpp pay` | SPT was already consumed (one-time use) | Create a new spend request with `credential_type: "shared_payment_token"` — do not retry with the same spend request ID |
| `context` validation error on `spend-request create` | `context` field is under 100 characters | Rewrite `context` as a full sentence explaining what is being purchased and why; the user reads this when approving |
| API rejects `merchant_name` or `merchant_url` | These fields are forbidden when `credential_type` is `shared_payment_token` | Remove both fields from the request; SPT flows identify the merchant via `network_id` instead |
| Command hangs indefinitely | `auth login` or `spend-request create` run synchronously | Always run these commands with `run_in_background=true` — they block until the user acts, so synchronous execution freezes the agent |
| Spend request approved but payment fails immediately | Wrong credential type for the merchant (e.g. `card` on a 402-only endpoint) | Go back to Step 2, re-evaluate the merchant, create a new spend request with the correct `credential_type` |
| Auth token expired mid-session (exit code 1 during approval polling) | Token refresh failure during background polling | Re-authenticate with `auth login`, then retrieve the existing spend request or resume polling. Only create a new spend request if the original one expired, was denied, or its shared payment token was already consumed |

## Further docs

- MPP/x402 protocol: https://mpp.dev/protocol.md, https://mpp.dev/protocol/http-402.md, https://mpp.dev/protocol/challenges.md
- Link: https://link.com/agents
- Link App (for account management): https://app.link.com
- Link support (if the user needs help with Link): https://support.link.com/topics/about-link

_meta.json Metadata

{
  "ownerId": "kn70d9rxm3564f99rv3gg4z2e985z4n5",
  "publishedAt": 1777731044794,
  "slug": "create-payment-credential",
  "version": "0.4.1"
}