---
title: "Purchase Payg"
method: POST
path: "/api/v1/payg/purchase"
tags: ["payg"]
---

# Purchase Payg

`POST /api/v1/payg/purchase`

## Request

- Base URL: `https://qcode.cc` (the document declares no server; this is the origin it was published from)
- URL: `https://qcode.cc/api/v1/payg/purchase`
- Auth: none declared

首购 / 续买 / 复活。HTTP 200 + success + code；钱路径整个在线程池里跑。

currency 大小写不敏感（cny 也行）；不是 CNY / USD ⇒ HTTP 200 + code=invalid_currency（不是 422，与其它业务拒绝
同一约定）。成功后的 Telegram 通知与 60 秒复核在后台跑，不拖慢响应。

## Request body

- PaygPurchaseRequest
  - `pack_id` string, required: week / month / bimonth / quarter
  - `currency` string, required: CNY 或 USD，大小写不敏感；其它值返回 HTTP 200 + code=invalid_currency
  - `language` string, nullable: 界面语言，缺省用请求语言
  - `request_token` string, nullable: 客户端幂等键（同一次购买重试用同一个）

## Response `200`

Successful Response

- PaygPurchaseResponse
  - `success` boolean, required
  - `code` string, required
  - `message` string, required
  - `kind` string, nullable
  - `api_key_value` string, nullable
  - `limit_after` integer, nullable
  - `remaining_usd` number, nullable
  - `expires_at` string, nullable
  - `expires_at_iso` string, nullable
  - `amount_charged` number, nullable
  - `currency` string, nullable
  - `new_balance` number, nullable
  - `renew` PaygRenewInfo: payg_renew_usage_low：本期额度已用百分比、需要的百分比、还差多少美元（不含任何库存信息）。
    - `locked` boolean, required
    - `used_pct` integer, nullable
    - `need_pct` integer, nullable
    - `need_usd` number, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-21** `2175943cc01f`: 2 warning, 1 info
  - removed the optional property `api_key_id` from the response with the `200` status
  - removed the optional property `payg_purchase_id` from the response with the `200` status
  - added the optional property `renew` to the response with the `200` status
- **2026-10-15** `badb73432a70`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/qcode/apis/qcode-web/changes/api/v1/payg/purchase/post.md)

---

[API](https://skmtc.dev/qcode/apis/qcode-web.md) - [All operations](https://skmtc.dev/qcode/apis/qcode-web/llms.txt) - [OpenAPI document](https://skmtc.dev/qcode/apis/qcode-web/revisions/9632b29aa008?raw)