POST /v1/topup


Call	`POST /v1/topup`
Price	free
Scope	`account:manage`
Operation id	`createTopup`

What it does

Start buying a $20, $50 or $200 pack. Returns a Stripe Checkout URL for a human to pay; the balance is credited when Stripe confirms. Balance does not expire while the account is active. The call itself is free. Scope: account:manage.

Example request

Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.

curl -X POST 'https://api.askverdict.io/v1/topup' \
  -H "Authorization: Bearer $VERDICT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "pack_usd": 50
}'

Example response

201: The Checkout session.

{
  "id": "pck_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "pack_usd": 50,
  "status": "pending",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_example",
  "expires_at": "2026-11-08T14:03:00Z"
}

Parameters

Name	In	Type	Required	Description
`idempotency-key`	header	string (uuid)	yes	A UUID you generate per logical request. Required on every POST. Repeating it within 24 hours returns the stored response and bills nothing; reusing it with a different body returns 409 `idempotency_conflict`.
`x-verdict-version`	header	string	no	API version to use, a date. Defaults to the version current when the key was created. The current version is `2026-11-01`.

Request body

Schema TopupRequest. The pack.

Field	Type	Required	Description
`pack_usd`	enum: 20 or enum: 50 or enum: 200	yes	Pack to buy: 20, 50 or 200 US dollars.

Response fields (201)

Schema TopupResponse.

Field	Type	Required	Description
`id`	string	yes	The pack purchase id.
`pack_usd`	enum: 20 or enum: 50 or enum: 200	yes	Pack size.
`status`	enum: “pending”, “completed”, “expired”, “failed”	yes	Purchase status.
`checkout_url`	string (uri)	yes	Stripe Checkout URL; open it to pay. The balance is credited when Stripe confirms payment.
`expires_at`	string (date-time)	yes	When the Checkout session expires.

Errors

Errors are RFC 9457 problem details and are never billed. Branch on type. See Errors.

Status	Meaning
`400`	Invalid request: malformed JSON, an unknown field, a failed constraint or a size limit (`invalid_request`).
`401`	Missing, malformed, revoked or expired API key, or a bad webhook signature (`unauthorized`).
`403`	The key lacks the scope this operation needs (`forbidden_scope`).
`404`	The resource does not exist in this organization (`not_found`).
`409`	The `Idempotency-Key` was reused with a different request, or the first request is still running (`idempotency_conflict`).
`429`	Rate limited (`rate_limited`). Wait `Retry-After` seconds.
`500`	Unexpected server error (`internal`). Not billed; retry with the same `Idempotency-Key`.

Try it

Open the interactive reference to send this request from the browser. The full document is at /openapi.json.