STACK
MENU
DOCS / THE ACCOUNT / PAYMENT LINKS

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.

Before you start

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

Connect Stripe

prompt
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.

prompt
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.

prompt
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. Every tool is in the tool reference. To disconnect Stripe, use account payments acct_123 stripe-disconnect.

Payment links | Docs