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.
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
- 201 Created
- 400 Invalid input
- 401 Unauthenticated
- 409 Idempotency conflict
- 413 Request too large
- 415 Unsupported media type
- 429 Rate limited
Cache-Control: no-store, private. An exact replay also sends Idempotent-Replayed: true.Related. Guest wallet guide · Create guest wallet · Get guest wallet status
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." }