Skip to main content
POST https://xquik.com/api/v1/guest-wallets/topups Add credits to an existing guest wallet. The wallet keeps the same paid_reads key. This endpoint creates a one-use hosted checkout only after the user confirms the amount. It does not charge the user.
Never call this endpoint automatically after a 402. Show the available option and amount, then wait for the user to confirm.
Keep the current guest key and store the new Idempotency-Key as a secret. Give only checkout_url to the user. After payment, poll status_url every poll_after_seconds with the same key. Stop when latest_purchase.status is no longer pending. Use usable to decide whether paid reads can run.

Headers

Body

Response

This response never returns a new API key.
The response sends Cache-Control: no-store, private. An exact replay also sends Idempotent-Replayed: true.

Response examples

201 example

  • 400 { "error": "invalid_input", "message": "Invalid input. Check the request body." }
  • 401 { "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }
  • 409 { "error": "idempotency_conflict", "message": "Reuse this Idempotency-Key only with the original request." }
  • 410 { "error": "checkout_unavailable", "message": "Checkout unavailable. Retry with a new Idempotency-Key." }
  • 413 { "error": "body_too_large", "message": "Request body is too large." }
  • 415 { "error": "unsupported_media_type", "message": "Send a Content-Type header of application/json." }
  • 423 { "error": "guest_wallet_unavailable", "message": "Guest wallet unavailable. Create a new wallet or contact support." }
  • 429 { "error": "rate_limited", "message": "Try again later." }
  • 503 { "error": "guest_wallets_unavailable", "message": "Guest wallet checkout is temporarily unavailable." }