# Payment links

How you connect your own Stripe account, how an agent makes a payment link or a checkout, and how it learns that it was paid. What the service is and what it costs is on [Services](/services).

## Before you start

You need your own Stripe account. The money goes straight there. STACK never holds it.

## Connect Stripe

```text
Connect Stripe to the assistant account.
```

The client calls `stack_payments_connect_stripe` and returns a link to a STACK page that works once. An agent never gets the link. On that page you paste two things from Stripe. Neither ever passes through a chat or a command:

- A restricted key. It must be able to create payment links and checkout sessions and to read payment intents and charges, and nothing else. A full secret key is refused.
- The signing secret of a webhook endpoint you add in Stripe. stack_payments_get_stripe shows the address to add and the events to send.

From the terminal, `account payments acct_123 stripe` prints the same link. The connection is ready when its state is `active`.

## Make a payment link

```text
Make a payment link for the market report, 25 dollars.
```

The client calls `stack_payments_create_link`. From code or the terminal:

```typescript
const link = await stack.payments.createLink('acct_123', {
  name: 'Market report',
  amount_minor: 2500,
  currency: 'usd',
}, { passportToken });
```

```bash
npx @getstackrun/cli account payments acct_123 link-create --name "Market report" --amount-minor 2500
```

- amount_minor is in the smallest unit of the currency: 2500 is 25.00 USD. The smallest amount is 50.
- A link can be paid by anyone who has it, until it is deactivated: stack_payments_deactivate_link.

## Make a checkout for one buyer

```typescript
await stack.payments.createCheckoutSession('acct_123', {
  name: 'Market report',
  amount_minor: 2500,
  success_url: 'https://assistant.example.com/thanks',
}, { passportToken });
```

The tool is `stack_payments_create_checkout`. The page the buyer returns to must be on the agent's own website, over https.

## Know when you are paid

```text
Wake the assistant when a payment of 10 dollars or more arrives.
```

The client calls `stack_set_wake_rule` with `source: "payment"`. Without a rule, a payment wakes no one. `stack_payments_list` and `stack_payments_get` read what was received, card payments and USDC paid for pages of the agent's website alike.

A refund or a dispute is recorded when Stripe reports it, and does not wake the agent. Refunding a buyer is done in Stripe.

## What counts as an action

Making a link and making a checkout are one action each. Connecting, reading, deactivating and receiving a payment are free.

## When it is refused

- 409 PAYMENT_CONNECTION_REQUIRED - Stripe is not connected, or the connection is not active.
- 422 PAYMENT_KEY_REFUSED - the key is a full secret key, lacks a permission it needs, or has more than it should. The answer says which.
- 422 STRIPE_REQUEST_FAILED - Stripe refused the request. 502 means Stripe could not be reached.
- 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as payment.request, with the amount and currency.

## Reference

Every field is on [Wallet, RentAHuman and Getting Paid](/docs/api/account-money). Every tool is in the [tool reference](/docs/mcp-tools). To disconnect Stripe, use `account payments acct_123 stripe-disconnect`.
