---
title: "Create an accountless prepaid wallet checkout"
method: POST
path: "/api/v1/guest-wallets"
tags: ["Guest Wallets"]
---

# Create an accountless prepaid wallet checkout

`POST /api/v1/guest-wallets`

Create a one-use hosted checkout after the user confirms $10-$250 USD. The request creates no charge. It returns a paid-read API key without an Xquik account. Idempotent replays return the same key.

## Headers

- `Idempotency-Key` string, required

## Request body

- GuestWalletPurchaseRequest — User-confirmed guest wallet checkout request.
  - `amount_minor` integer, required — USD cents accepted for this checkout.
  - `currency` 'usd', required

## Response `201`

Hosted checkout, guest API key, and API status URL.

- GuestWalletCreateResponse — Pending hosted checkout and guest wallet purchase details.
  - `account_required` false, required
  - `amount` GuestWalletAmount, required — Confirmed USD amount for a guest wallet purchase.
    - `amount_minor` integer, required — USD amount in cents. Accepted range is $10-$250.
    - `currency` 'usd', required
  - `api_key` string, password, required — Paid-read bearer credential returned only by initial creation. Store it as a secret. Never place it in a URL or log.
  - `authorization` object, required
    - `header` 'Authorization', required
    - `scheme` 'Bearer', required
  - `checkout_url` string, uri, required — Hosted checkout URL for user interaction.
  - `credits` string, required — Credits granted after verified payment.
  - `credential_notice` 'Store api_key and the Idempotency-Key securely before sharing checkout_url. No email recovery is available.', required
  - `expires_at` string, date-time, required — Time when the pending checkout expires.
  - `instructions` string, required — Hosted checkout and status polling instructions.
  - `poll_after_seconds` 2, required — Wait at least this long before polling status_url.
  - `purchase_id` string, required
  - `requires_user_interaction` true, required
  - `status` 'creating' | 'pending' | 'paid' | 'expired' | 'failed' | 'refunded' | 'disputed', required
  - `status_url` 'https://xquik.com/api/v1/guest-wallets/status', uri, required
  - `wallet_id` string, required

## Other responses

- `400` — Invalid input
- `409` — Idempotency-Key was reused with a different request.
- `410` — Checkout expired or can no longer be used.
- `413` — Request body is too large.
- `415` — Content-Type must be application/json.
- `423` — Guest wallet is unavailable.
- `429` — Guest wallet request limit exceeded.
- `503` — Guest wallet checkout is unavailable.
- `default` — Unexpected error.

## Changes

- **2026-08-12** `5d4938bb7de3` — 162 warning
  - added the new `closed` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `400`
  - added the new `closed` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `409`
  - added the new `closed` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `410`
  - added the new `closed` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `413`
  - …158 more
- **2026-08-12** `4da209b29df8` — 1 breaking, 54 warning, 1 info
  - the `instructions` response property const value `Give checkout_url to the user. They must complete payment on Stripe. Never submit payment for them. After payment, poll status_url every poll_after_seconds until latest_purchase.status is no longer pending.` was removed for the status `201`
  - added the new `coverage_cursor_gone` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `400`
  - added the new `coverage_cursor_gone` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `409`
  - added the new `coverage_cursor_gone` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `410`
  - …52 more

[Change history](https://skmtc.dev/xquik-dev/apis/xquik-api-2/changes/api/v1/guest-wallets/post.md)

---

[API](https://skmtc.dev/xquik-dev/apis/xquik-api-2.md) · [All operations](https://skmtc.dev/xquik-dev/apis/xquik-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/xquik-dev/xquik-api-2/revisions/834c16fa45e8/schema)