---
title: "Buy extra credits by card (subscribers only, no header auth)"
method: POST
path: "/v1/credits/topup"
tags: ["Keys & Billing"]
---

# Buy extra credits by card (subscribers only, no header auth)

`POST /v1/credits/topup`

## Request

- Base URL: `https://api.insumermodel.com`
- URL: `https://api.insumermodel.com/v1/credits/topup`
- Auth: none required

Creates a one-time Stripe payment for 100–50,000 additional verification credits at the subscriber's tier rate ($0.029/credit Pro, $0.02/credit Enterprise). Free-tier keys get 403 — top-ups require a Pro or Enterprise subscription; free and crypto keys buy credits on-chain via POST /v1/credits/buy instead. **Response envelope note**: standalone endpoint — flat `{success, url}`.

## Request body

- object
  - `keyHash` string, required: 64-hex identifier from /v1/keys/lookup.
  - `credits` integer, required

## Response `200`

Hosted payment session created

- object
  - `success` boolean
  - `url` string: Stripe Checkout URL for the one-time payment.

## Other responses

- `400`: Invalid credits amount or keyHash
- `403`: Free-tier key — top-ups require a subscription
- `404`: Key not found or inactive
- `405`: Method not allowed (only POST supported)
- `500`: Unexpected server error. Safe to retry; no credits are charged on a 500. Router endpoints return the standard error envelope; standalone endpoints (the ones whose 200 is a flat object) return a flat {"error": "..."} object.

---

[API](https://skmtc.dev/insumermodel/apis/insumerapi.md) · [All operations](https://skmtc.dev/insumermodel/apis/insumerapi/llms.txt) · [OpenAPI document](https://skmtc.dev/insumermodel/apis/insumerapi/revisions/91f56fe9e3d8?raw)