Reference · Payment requests

Create a payment request

POST/v1/payment_requests

Creates an open request for a payee your agent holds an active grant for. Returns a checkout_url and tells you whether the payer can pay natively with Apple Pay.

Body parameters

payee_idstringrequired: The payee that receives the money. Must have charges enabled.
descriptionstringrequired: Shown to the payer on the Apple Pay sheet and checkout.
line_itemsarrayrequired: 1–50 items of { name, quantity 1–999, unit_amount in cents }.
goods_typeenumrequired: physical, service or digital.
payer_emailstringoptional: Receipt address. Never required for Apple Pay.
metadataobjectoptional: Up to 50 string pairs, echoed on every event.
expires_inintegeroptional: Seconds until expiry, 1800 to 604800. Default 86400.

Headers

idempotency-keystringrequired: Up to 255 characters. Same key, same body → same request, never a second charge.

RequestcURL

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

Response · 200JSON

{
  "id": "pr_9fK2x",
  "object": "payment_request",
  "livemode": false,
  "status": "open",
  "amount": 12800,
  "application_fee_amount": 12,
  "amount_refunded": 0,
  "currency": "usd",
  "native_apple_pay_eligible": true,
  "checkout_url": "https://pay.grosso.ai/pay/pr_9fK2x",
  "expires_at": 1793211652,
  "paid_at": null
}

Error · 400JSON

{
  "_tag": "InvalidRequest",
  "code": "grant_exceeds_tier",
  "message": "Your tier allows at most …",
  "param": "line_items"
}

All endpoints

Endpoint index

Method	Path	Description
POST	/v1/payment_requests	Create a payment request
GET	/v1/payment_requests/:id	Retrieve a payment request
POST	/v1/payment_requests/:id/refunds	Refund all or part of a payment
POST	/v1/payees	Invite a payee to onboard with Stripe
POST	/v1/payee_grants	Ask a payee for spending limits
GET	/v1/ledger	Balances and fee lines
GET	/v1/disputes	Disputes raised by payers
POST	/v1/webhook_endpoints	Register a webhook endpoint
GET	/v1/events	List events, newest first