Create a payment credential

Create a test payment credential with Link CLI. You’ll connect a Link account, request approval for a purchase, and retrieve a virtual card without charging the underlying payment method.

Before you begin

You need Node.js and npm, and a Link account in the US or Canada. You can create an account if you don’t have one.

Run Link CLI

Install Link CLI globally so the link-cli command is available throughout this guide:

npm install -g @stripe/link-cli

Run the guided setup

The onboarding flow connects your Link account, checks for payment methods, and offers test demos:

link-cli onboard

The demos use test mode and don’t create real charges. After onboarding, continue to Create a spend request. To authenticate and choose a payment method yourself, follow Set up manually instead, then return to that step.

Create a spend request

A spend request describes the purchase for the customer to approve. Provide the seller’s name and URL, the amount in the currency’s minor units, and a context of at least 100 characters explaining the purchase. This example uses --test to request a test credential. Link selects a payment method from the connected wallet.

link-cli spend-request create \
  --test \
  --merchant-name "Stripe Press" \
  --merchant-url "https://press.stripe.com" \
  --context "Purchasing 'Working in Public' from press.stripe.com. The user initiated this purchase through the shopping assistant." \
  --amount 3500 \
  --currency usd \
  --line-item "name:Working in Public,unit_amount:3500,quantity:1" \
  --total "type:total,display_text:Total,amount:3500"

Link asks the customer to approve the request on the Link website or in the Link mobile app. The app isn’t required. In an interactive command-line session, Link CLI waits for the result. In an agent or structured-output environment, show the returned approval_url to the customer and poll for approval.

Inspect status before continuing. Retrieve the credential only when the status is approved. A zero exit code doesn’t mean the customer approved the request. If polling times out or the customer must complete another action, follow Spend requests before creating another request.

Retrieve the credential

Use the request ID returned by the create command in place of lsrq_001:

link-cli spend-request retrieve lsrq_001

Card details are excluded by default. To keep full credentials out of agent transcripts, write them to a protected local file while stdout remains redacted:

link-cli spend-request retrieve lsrq_001 \
  --include card \
  --output-file "$(mktemp -d)/link-card.json" \
  --format json

The file is created with 0600 permissions. Standard output contains redacted card details and the file path. Existing files aren’t overwritten unless you explicitly pass --force. Your application can now use the test credential in a test checkout. Delete the file after use.

Make a live purchase

When you’re ready to make a real purchase, confirm the seller, amount, and context with the customer. Create a new spend request without --test, then follow the same approval and retrieval steps.

Set up manually

Use these steps instead of guided onboarding. After you connect the account and check its payment methods, return to Create a spend request.

Connect a Link account

Start the authorization flow:

link-cli auth login

The command returns a verification URL and a short phrase. Open the URL, log in to your Link account, and enter the phrase to approve the connection.

To identify the connecting agent and wait for authentication in the same process:

link-cli auth login \
  --client-name "My shopping agent" \
  --interval 5 \
  --timeout 300

Choose a payment method

List the cards and bank accounts in the connected wallet:

link-cli payment-methods list

Choose an eligible method, then pass its id with --payment-method-id when you create a spend request. If you omit it, Link chooses a payment method.

Ineligible methods include a capabilities.agentic_payments object with eligible: false and ineligibility_reasons.

If the wallet has no eligible method, open the Link wallet to add one:

link-cli payment-methods add

You can also inspect saved shipping addresses and the customer’s spend limits:

link-cli shipping-address list
link-cli user-info retrieve

Next steps

Choose how to use Link in your agent: