Docs · Get started

Quickstart

Ask a human to pay, from your agent: get a key, create a request, send it, listen for the webhook.

Everything here runs in test mode

Keys that start with gk_test_ never move money. Switch to a gk_live_ key once your account is verified and enabled for live.

Step 1 — Get a test key

Get a test key

Sign up with POST /v1/signup, then confirm the emailed code with POST /v1/signup/verify — it returns a gk_test_ key. Keep it server-side. Your agent also needs an active payee grant — the payee owner approves its spending limits once.

.envENV

GROSSO_API_KEY=gk_test_51Hc…2f9a

Step 2 — Create a request

Create a payment request

Amounts are in cents. Send an idempotency-key so a retried tool call never charges twice.

POST /v1/payment_requestscURL

curl https://pay.grosso.ai/v1/payment_requests \
  -H "Authorization: Bearer $GROSSO_API_KEY" \
  -H "idempotency-key: order_4417" \
  -d '{
    "payee_id": "payee_7Qk2",
    "description": "Dinner for two at Lupa",
    "goods_type": "service",
    "line_items": [
      { "name": "Tasting menu", "quantity": 2, "unit_amount": 6400 }
    ],
    "expires_in": 3600
  }'

Step 3 — Send it

Send it to the payer

If native_apple_pay_eligible is true, the payer gets an Apple Pay sheet in iMessage. Otherwise, send checkout_url in your agent’s reply.

Response · 200JSON

{
  "id": "pr_9fK2x",
  "status": "open",
  "amount": 12800,
  "application_fee_amount": 12,
  "currency": "usd",
  "native_apple_pay_eligible": true,
  "checkout_url": "https://pay.grosso.ai/pay/pr_9fK2x",
  "expires_at": 1793129252
}

Step 4 — Listen

Listen for payment_request.paid

webhook.tsTypeScript

import { Effect } from "effect";
import { verifyWebhookSignature } from "grosso/sdk";

const ok = await Effect.runPromise(
  verifyWebhookSignature({
    payload: await req.text(),
    header: req.headers.get("grosso-signature") ?? "",
    secret: process.env.GROSSO_WEBHOOK_SECRET,
  }),
);

Step 5 — Go live

Go live

Finish Stripe onboarding for your payee, create a gk_live_ key, and point a live webhook endpoint at production.