How an agent starts the posterly free trial through Stripe-hosted Checkout: a card is required, one-time cards must not be used, and the person adds their own card.

start_signup (or POST /api/v1/signup) starts a 7-day free trial of posterly with API and MCP access. A card is required: Stripe Checkout collects and verifies it, nothing is charged today, and the card is charged on day 8, unless the person starts the paid plan sooner. API and MCP are limited during the trial. The response always includes a payment object that describes the Stripe-hosted Checkout page, and checkout_redirect_url is the link that starts the trial.

Password setup, social account connect, and publish approval still happen with a human in the browser.

The safe default: hand the link to the person

Send the person checkout_redirect_url and let them add their own card in Stripe Checkout. This is the path that always works, and it puts a card on file that can be charged on day 8 and every month after.

Do not use a one-time or single-use virtual card

During the trial the card the person enters is saved as the card on file. A one-time or single-use virtual card (for example a Link agent wallet card that is valid for one spend request) cannot be charged again, so the day 8 charge fails, the account goes past due, and access stops until a working card is added. Do not complete the trial Checkout with a one-time credential.

You may complete the page yourself only with a reusable card that the person has explicitly authorized for recurring posterly charges. If you are not sure the credential is reusable, send checkout_redirect_url instead.

What the agent gets back

Every checkout_required response, and every poll while checkout is still open, includes payment:

{
  "amount": null,
  "currency": "usd",
  "amount_display": null,
  "billing": "monthly_subscription",
  "description": "posterly Starter plan + API access, billed monthly, with a 7-day free trial (card required, charged on day 8)",
  "trial_period_days": 7,
  "charged_today": false,
  "merchant_name": "posterly",
  "merchant_url": "https://www.poster.ly",
  "checkout_redirect_url": "https://www.poster.ly/agents/signup/checkout?session_id=cs_live_123",
  "pay_with": "stripe_hosted_checkout",
  "agent_wallet": {
    "supported": true,
    "how": "...",
    "spend_request": {
      "merchant_name": "posterly",
      "merchant_url": "https://www.poster.ly",
      "amount": null,
      "currency": "usd",
      "context": "7-day free trial of posterly Starter plan + API access, charged on day 8"
    }
  }
}

amount is null because nothing is due today, so there is no amount to put in a spend request. payment is null once the card is saved or checkout has expired. An account that already had a trial is charged at checkout instead: trial_period_days is null, charged_today is true, and amount is the amount due.

If the agent has a wallet

A spend request is how an agent wallet (for example a Link agent wallet, currently available to US Link accounts, with spend requests capped at $500 and a 12-hour approval window) asks the person to approve a payment to a merchant. It fits a one-off charge for a known amount, which is not what the trial is, so most of the time you should not create one here. If the person has authorized a reusable card in the wallet and wants you to use it:

Tell the person what the Checkout does: the 7-day trial, that a card is required, that nothing is charged today, and that the card is charged on day 8 unless they start the paid plan sooner.
Get their explicit approval in the wallet for the reusable card.
Complete checkout_redirect_url with that card. Never ask the user to type card details into chat, and never send card numbers to posterly.
Poll get_signup_session (or GET /api/v1/signup/sessions/{id}) until the status moves past checkout_pending.
Tell the user to open the posterly password setup email. After they set a password, continue connect and first-post onboarding in the same chat.

If the agent has no suitable credential, or the credential is declined, send the user checkout_redirect_url.

What the user should be told

This starts a recurring subscription, not a one-time purchase:

The trial is free for 7 days. A valid card is required to start it.
The card is charged on day 8 and then every period, unless the person starts the paid plan sooner or cancels first.
API and MCP are limited during the trial.
The user can cancel any time from the dashboard.

Tell the user this before they enter or approve a card, not after.

What stays with the human

Entering or approving the card
Password setup
Social OAuth connect
Publish approval for live posts

The agent must not ask for a posterly password, social passwords, or OAuth codes.

Direct PaymentIntent confirmation

Some responses may also include agent_pay: a Stripe PaymentIntent an agent can confirm directly with a payment method id, bypassing the hosted Checkout page. This is not currently enabled. Ignore agent_pay when it is null.

Browser fallback

If the agent has no payment credential, the credential is declined, confirmation fails, or the user prefers the website, send checkout_redirect_url. That is the same hosted Checkout handoff posterly already uses for agent signup.

Stripe WebMCP on hosted Checkout

Agents that pay via checkout_redirect_url (Stripe-hosted Checkout) may get structured page tools, WebMCP, for free when their browser agent supports WebMCP. posterly does not register those tools. Stripe registers them on Checkout.

WebMCP is optional efficiency on the same Checkout URL we already return. It is not a new posterly API, and it does not replace payment.agent_wallet or the human handoff.

If the agent browser exposes a WebMCP consumer API:

Discover the tools on the Checkout page.
Re-list or rediscover tools after each state change. Selecting a payment method can change the fill schema, and a submit tool may only appear when the form is valid.
Do not hard-code tool names, and do not assume submit_payment is always present.

If the browser has no WebMCP consumer API, which is common today, fall back to filling the form with a reusable card the person authorized, or send the user checkout_redirect_url as today.

Stripe's agent guide is Use WebMCP to complete Stripe payments in a browser.

Pay for posterly from an agent