---
title: "Approve a wallet top-up with hosted checkout or a shared payment token"
method: POST
path: "/v1/agent/onboarding/headless/payments"
tags: ["Billing"]
---

# Approve a wallet top-up with hosted checkout or a shared payment token

`POST /v1/agent/onboarding/headless/payments`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/agent/onboarding/headless/payments`
- Auth: HTTP bearer

Bound to the authenticated workspace. Available to email/social customers without a phone identity. Owner approval is required before payment. Only a signed matching Stripe webhook creates purchased funds. Browser welcome credit cannot fund numbers, PSTN or SMS. The existing URL is retained for pending-payment retries; it does not provide headless signup.

## Request body

- HeadlessPayment
  - `amount_minor` integer, required: Top-up in the wallet currency's minor units; current server top-up bounds apply.
  - `currency` string, required: Exact owner-approved currency; must match the workspace wallet reported by account_overview.
  - `idempotency_key` string, required: Opaque key unique to this purchase. Retry the same key and parameters after uncertain outcomes; never include payment credentials.
  - `method` 'card_checkout' | 'shared_payment_token', required
  - `payment_approved` boolean: True only after the owner explicitly approves this amount and currency for purchased Skysay calling credit. Scope consent is not purchase approval. Optional while requesting SPT approval metadata.
  - `request_challenge` boolean: For SPT, return 402 with amount/currency/Stripe seller profile for a compatible wallet to request owner approval. This is JSON metadata, not MPP, native checkout or MCP elicitation.
  - `shared_payment_token` string: Granted spt_ token approved by the owner for this seller and amount. Omit when requesting the challenge. Never submit card numbers.

## Response `200`

Payment result; pending is not wallet credit

- HeadlessPaymentResult: Card checkout returns the standard Stripe checkout URL/amount result. SPT returns pending or paid; only a signed matching webhook makes purchased wallet credit available.
  - `amount_minor` integer
  - `checkout_url` string, uri
  - `currency` string
  - `next_action` string
  - `payment_id` string
  - `status` string
  - `wallet_credit_timing` string

## Other responses

- `400`: Invalid input or payment approval missing
- `401`: Workspace authentication required
- `402`: Owner approval challenge
- `409`: Conflicting or uncertain payment retry
- `503`: Payment method unavailable

---

[API](https://skmtc.dev/skysay/apis/skysay-api.md) · [All operations](https://skmtc.dev/skysay/apis/skysay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skysay/apis/skysay-api/revisions/95b8c66f99aa?raw)