API 文档

Nerver 全部接口 — AC 资格预检 · 订阅查询 · 支付链接 · PIX · UPI · GoPay · GCash · PH Link · 测试通道 · PayPal · Outlook 邮箱 · 统计

认证状态加载中...

POST /api/v1/check · AC 资格预检

POST/api/v1/check

首页那个接口：验证 ChatGPT accessToken 是否仍有效（401 / JWT 过期），并根据 promoId 判定是否符合优惠活动资格。
主看 token_ok / eligible。
可选 check_gcash_pm=true 时才会附带 GCash 硬查字段；纯 GCash 资格请用 /api/v1/gcash-check。

请求	类型	说明
Authorization	header?	Bearer `AUTH_TOKEN`（未配置 AUTH_TOKEN 时可不鉴权）。附带 GCash 硬查时也可用 GCash 服务/商务 TOKEN / CDK
token	string	单条 AC Token（与 tokens 二选一；eyJ 开头 JWT，或整段 /api/auth/session JSON）
tokens	string[]?	批量 AC Token（与 token 二选一）
promoId	string?	优惠活动 id（默认 `plus-1-month-free`）
check_gcash_pm	bool?	可选；true 时附带 GCash 硬查（需管理员鉴权走后台代理，或 body.proxy）
proxy	string?	可选；仅 check_gcash_pm 用户代理模式

响应（主字段）	含义
token_ok	AC 是否仍有效（false = 401 / 吊销 / JWT 过期）
eligible	是否符合优惠资格（token_ok 且 coupon 可用）
reason	empty-token / jwt-expired / token-401 / eligible / not-eligible / invalid-token-format / …
coupon_state	上游 coupon state（eligible / not_eligible / …）
email / account_id / plan_type	JWT 解析出的账号信息
gcash_pm_eligible	仅 check_gcash_pm 时有意义；未请求时多为 null / not-requested

# 首页同款：只查 AC + 优惠资格
curl -X POST https://YOUR_HOST/api/v1/check \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","promoId":"plus-1-month-free"}'

# 可选：附带 GCash 硬查（需鉴权或 proxy）
curl -X POST https://YOUR_HOST/api/v1/check \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer AUTH_OR_GCASH_TOKEN' \
  -d '{"token":"eyJ...","promoId":"plus-1-month-free","check_gcash_pm":true}'

POST /api/v1/subscription

POST/api/v1/subscription

查询订阅状态。支持 token / session 两种输入：只传 token 时走老逻辑；同时传了 session（sessionToken / cookie / 整段 session JSON 三选一）时，token 失效会自动调 /api/v1/session/refresh 拿新 AT 再查一次，把新订阅 + 最新 session 一起回传给调用方。传 channel=kakao|gcash 时改查本站 Finalize 凭证，不打 OpenAI。

请求	类型	说明
token	string?	AC token；token 与 session 至少提供一个。可以省略 token 只传 session——我们会先 refresh 拿 AT 再查
sessionToken	string?	可选。ChatGPT Web `__Secure-next-auth.session-token` 值。token 失效时用它自动刷新
cookie	string?	可选。完整 Cookie 头（含 chunked `.0 / .1` 也行）。三选一
session	object?	可选。`https://chatgpt.com/api/auth/session?refresh=true` 返回的整段 JSON。三选一
channel	string?	可选 `kakao` / `gcash`；命中本站 Finalize 凭证即视为已开通

响应	类型	说明
ok / reason	bool/string	ok \| token-invalidated \| jwt-expired \| session-refresh-failed \| no-activated-dump \| http-error \| fetch-error \| no-account \| unknown-channel \| invalid-channel
message	string?	面向终端用户的中文提示（失败/需注意时给）
session_refreshed	bool	本次是否触发了 session 刷新。true 时 API 调用方应更新本地存储
session_rotated	bool	sessionToken 是否被官方轮换。true 时旧的必须替换掉
session	object?	刷新过时给——可整段覆盖本地存储：`{accessToken, sessionToken, expires, user, account, authProvider}`
accessToken / sessionToken	string?	便捷字段，等价 `session.accessToken` / `session.sessionToken`
plan_type / subscription_plan	string	free/plus/pro/team；chatgptplusplan 等
has_active_subscription	bool	是否有活跃订阅
expires_at / renews_at / days_left	string/number	时间线
will_renew / is_delinquent	bool	续费/欠费
purchase_origin_platform	string	chatgpt_web / chatgpt_ios / kakao_pay / gcash / ...
applied_discounts / eligible_offers	array	已应用优惠 / 可购买套餐
channel_verified / kr_finalize	bool/object?	渠道核验模式下的额外字段

# 1) 只传 token（token 有效时最简）
curl -X POST -H 'content-type: application/json' \
  -d '{"token":"eyJ..."}' https://YOUR_HOST/api/v1/subscription

# 2) 传 token + session（token 失效时自动 refresh 再查, 返回最新 session）
curl -X POST -H 'content-type: application/json' -d '{
  "token":"eyJ...(可能失效)",
  "sessionToken":"eyJ...next-auth session-token"
}' https://YOUR_HOST/api/v1/subscription

# 3) 只传 session（先 refresh 再查）
curl -X POST -H 'content-type: application/json' -d '{
  "session": { "sessionToken":"eyJ...", "user":{"email":"..."} }
}' https://YOUR_HOST/api/v1/subscription

# 关键: 当返回 session_refreshed=true 或 session_rotated=true 时,
# 一定要用返回的 session 整段覆盖本地存储 (旧 sessionToken 可能已失效)

POST /api/v1/session/refresh

POST/api/v1/session/refresh

一句话：传旧 Session → 回传新 Session + 账户 + 套餐。开通 Plus 后旧 AT 失效时用这个刷。
成功请用返回的 session（或 accessToken + sessionToken）覆盖本地；Session 可能轮换。

请求（三选一）	说明
sessionToken	cookie `__Secure-next-auth.session-token` 的值
整段 Session JSON	浏览器 `/api/auth/session` 整段直接 POST
cookie	完整 Cookie 头（自动抽取 sessionToken）

成功回传（看这些就够）	说明
session	可整段回写的 Session：含 `accessToken`、`sessionToken`、`expires`、`account`、`user`
accessToken / sessionToken	新 AT / 新 Session（可能已轮换）
planType	套餐：free / plus / pro …
email / account_id	账户邮箱 / 账户 id
session_rotated	`true` 时旧 Session 已废，必须用新值

鉴权：后台未配 token 时可不鉴权；配了则带 Bearer（service/business/CDK）。失败只看 ok=false 和 reason。

curl -X POST -H 'content-type: application/json' \
  -d '{"sessionToken":"eyJhbGciOiJkaXIi..."}' \
  https://cha.nerver.cc/api/v1/session/refresh

# 成功重点字段:
# { ok, session:{accessToken,sessionToken,expires,account,user}, planType, email, account_id, session_rotated }

POST /api/v1/checkout

POST/api/v1/checkout

生成 ChatGPT Plus 优惠支付链接 (pay.openai.com)。

请求	类型	说明
token	string	AC token (必填)
promoId	string?	默认 plus-1-month-free
country	string?	ISO 国家码, 默认 ID
currency	string?	默认 IDR。支持: USD AUD CAD GBP EUR CLP JPY INR IDR PKR THB MYR TWD VND PHP NGN ZAR KZT TZS EGP BRL SEK CZK PLN DKK NOK KRW COP MXN PEN
planName	string?	默认 chatgptplusplan

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| token-401 \| coupon-not-eligible \| coupon-check-failed \| checkout-failed \| no-url \| fetch-error
message	string?	面向终端用户的中文友好提示 (失败时附带)
url	string?	pay.openai.com 支付链接 (仅 ok=true)
coupon_state / email / account_id	string?	附加信息

curl -X POST -H 'content-type: application/json' -d '{"token":"eyJ...","country":"US","currency":"USD"}' https://YOUR_HOST/api/v1/checkout

POST /api/v1/pix · PIX 巴西 (长链)

POST/api/v1/pix

巴西 PIX 即时支付 — 长链接模式: 输入 AC token → 自动生成 checkout → Stripe 短/长跳转链接, ~25s。
需要直接拿真实二维码请用 /api/v1/pix-short (PIX 内部支付)。

请求	类型	说明
token	string	AC token (必填)
promoId	string?	默认 plus-1-month-free

响应	类型	说明
ok / reason	bool/string	ok \| hosted-fallback \| empty-token \| jwt-expired \| checkout-failed \| coupon-not-eligible \| no-cs-id \| snapshot-failed \| approve-failed \| no-qr \| pix-protocol-error
mode	string	"short_emv" \| "long_link" — 标识本次响应来自哪种模式
message	string?	面向终端用户的中文友好提示 (失败时附带)
pix_qr_data	string	PIX EMV payload (内部支付模式有值; 长连接模式为空)
pix_qr_image_url	string	Stripe 托管 QR PNG 图片 URL (内部支付模式有值)
pix_hosted_url	string	Stripe 支付指引页面 (内部支付模式有值)
stripe_hosted_url	string	Stripe Checkout 长跳转链接 (两种模式都尽量填充, 兜底跳转用)
pix_expires_at	number	过期时间戳 (秒), 约 11 小时有效
pix_expires_iso	string	过期 ISO 时间
setup_intent_id / pm_id / session_id	string	Stripe 内部 ID
persona	object	自动生成的巴西身份 {name, cpf, city, state, ...}
email / account_id	string?	JWT 解出

curl -X POST -H 'content-type: application/json' -d '{"token":"eyJ..."}' https://YOUR_HOST/api/v1/pix

示例响应 (截断, pix_qr_data 就是页面 QR 下方那串可复制的 EMV 文本):

{
  "ok": true,
  "reason": "ok",
  "pix_qr_data": "00020126180014br.gov.bcb.pix5204000053039865802BR5911Ebanx LTDA.6008CURITIBA62070503***80720014br.gov.bcb.pix2550pix.ebanx.com/rec/A0239E59E6F9A9FDF7DD8F6A4BA8BC9163043B23",
  "pix_qr_image_url": "https://files.stripe.com/.../pix.png",
  "pix_hosted_url":   "https://pay.openai.com/c/.../pix_instructions",
  "pix_expires_at":   1780300800,
  "pix_expires_iso":  "2026-06-02T03:00:00.000Z",
  "session_id":  "cs_live_a1qxAW...",
  "pm_id":       "pm_1TdUeGC6...",
  "setup_intent_id": "seti_1TdUelC6...",
  "email": "user@example.com",
  "persona": { "name": "Pedro Ferreira", "cpf": "414.225.021-39", "city": "Curitiba", "state": "PR" }
}

# 提取 EMV 码 (jq):
curl -s -X POST .../api/v1/pix -d '{"token":"eyJ..."}' | jq -r .pix_qr_data

POST /api/v1/pix-short · PIX 内部支付

POST/api/v1/pix-short

巴西 PIX 内部支付模式 — 直接返回 QR 字符串(pix_qr_data)、QR 图片、托管页。完整 7 步协议, 含自动换 IP 重试(approve blocked / 网络失败时按重试次数换代理 SID 重试)。
独立鉴权 — 与全局 AUTH_TOKEN 解耦, 在 后台 → 运行配置 → 内部支付鉴权 token 配置(留空=不鉴权)。

鉴权	说明
Authorization: Bearer <token>	推荐, 与 `pix_short_service_token` 比对(timing-safe)
?key=<token>	等效, query 传参

请求	类型	说明
token	string	AC token (必填)
promoId	string?	默认 plus-1-month-free

响应	类型	说明
ok / reason	bool/string	失败时见下方「错误码与重试策略」 4 个分类模块
mode	string	固定 "short_emv"
pix_qr_data	string	PIX EMV payload (短码字符串, 直接渲染二维码)
pix_qr_image_url	string	Stripe 托管 QR PNG 图片 URL
pix_hosted_url	string	Stripe 支付指引页面
pix_expires_at / pix_expires_iso	number/string	过期时间
setup_intent_id / session_id	string	Stripe 内部 ID
persona / email / account_id	object/string	自动生成巴西身份 / JWT 解出
attempts	number	实际尝试次数 (1 = 首试就成功)
attempts_log	array	每次尝试的 {attempt, reason, session_id, proxyUrl(脱敏), error}

curl -X POST \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer YOUR_PIX_SHORT_TOKEN' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/pix-short

提示: 后台代理 URL 字段同时支持标准 http://user:pass@host:port 和购买面板原生 host:port:user:pass 格式(自动转换)。$RAND 占位符每次重试会替换为 8 位随机 hex, 用于 IPWEB 等按 SID 切换出口 IP 的代理。

📑 错误码与重试策略

服务端已在内部按 pix_short_retry_count 配置自动换 IP 重试。客户端再次重试前请参考下表:

✅ 业务成功 (1 个)HTTP 200

服务端返回 ok:true 且 pix_qr_data 非空, 直接渲染 QR 码即可。

reason	含义	动作
ok	成功生成 PIX EMV QR	✓ 完成

🔄 可重试 — 临时性错误 (5 个)HTTP 429 / 503 / 500

服务端因瞬时拥塞 / 限流 / 网络抖动失败, 同 token 重发即可, 但请遵守退避建议避免雪崩。

reason	HTTP	含义 / 出现场景	建议动作
rate-limited	429	客户端 IP 触发 `rate_rpm_pix_short` 上限 (默认 120/min)。响应头带 `retry-after` 秒数	读 retry-after 后重试
concurrency-busy	503	服务端 `pix_short_concurrency` 并发槽位用尽	立即重试 (随机退避 0.5-2s)
server-error	500	未捕获异常 / 内部 throw	退避 1-5s 重试; 持续触发请反馈
fetch-error	200	代理 / 上游网络失败 (cycletls connect/timeout)	退避 2-5s 重试 (服务端已换 IP 重试 N 次仍败)
pix-protocol-error	200	Stripe / OpenAI 协议非预期响应 (字段缺失等)	退避 3-10s 重试; 持续 3+ 次反馈

⚠️ 服务端已重试 — 客户端可换 IP 再试 1-2 次 (6 个)HTTP 200

这些失败服务端内部已经按 pix_short_retry_count (默认 6) 轮换 IP 重试过仍然失败, 客户端允许再试 1-2 次(同 token 换出口 IP 仍有概率成功):

低频客户: 等 30-60s 让代理池冷却后再试
同账号连续 3+ 次失败: 该账号事实上不可用, 停止重试以免被进一步打标
高频客户: 同时切换 token / 账号避免雪崩

reason	含义 / 触发场景	建议动作
checkout-failed	OpenAI POST /payments/checkout 非 200, 通常是 CF 403 / 出口被识别	换 IP 再试 1-2 次, 仍败则换 token
snapshot-failed	OpenAI POST /snapshot 落盘失败, 通常是 token 中途失效	换 IP 再试 1 次, 仍败则换 token
approve-failed	OpenAI /approve 返 blocked, 通常是账号风险 + 出口 IP 联合触发	换 IP/换 token 重试 1-2 次
no-qr	所有步骤成功但 polling 30s 内没拿到 pix QR / next_action	直接重试 (代理不稳)
risk-blocked	OpenAI 在某次调用层面识别为风险 (代理特征+账号叠加), 不一定是账号永久黑名单	换 IP 重试 1-2 次, 持续触发则换账号
coupon-not-eligible	优惠资格校验失败, 可能是出口 IP 区域识别 / 临时风控	换 IP 重试 1-2 次, 持续触发则换账号

🛑 永久失败 — 重试无意义, 必须换 token / 换账号 (7 个)HTTP 200 / 401 / 503

这些不要重试, 重试也是同样结果。客户端应直接切换 token / 提示用户更换账号 / 联系运营。

reason	HTTP	含义	建议动作
unauthorized	401	商务鉴权 token 缺失或错误	检查 Authorization 头
empty-token	200	请求体 `token` 字段为空	入参修复
invalid-token-format	400	token 不符合 JWT 形态 (非 eyJ 开头三段)	入参修复
jwt-expired	200	JWT exp 已过	让用户重新获取 token
token-invalidated	200	token 被 OpenAI 主动作废 (已退出登录 / 已撤销)	必须换 token
already-paid	200	账号已存在有效订阅, 不能再创建	无需重试, 提示用户「已支付」
feature-disabled	503	后台 `pix_short_enabled=0` 已禁用此端点	联系运营开启

POST /api/v1/pix-short/stream · PIX 内部支付 SSE 实时进度

POST/api/v1/pix-short/stream

与 /api/v1/pix-short 鉴权与请求体完全一致, 但响应为 text/event-stream SSE 流, 实时推送每次 attempt 与每个内部 step 进度, 适合前端展示等待界面。

事件	data 字段	含义
hello	{retry_count, max_attempts}	连接成功, 返回最大尝试次数
progress	{type:"attempt-start", attempt, max}	开始第 N 次尝试
progress	{type:"step", attempt, step}	step ∈ checkout / init / region / snapshot / confirm / approve / polling
progress	{type:"attempt-end", attempt, ok, reason, error}	第 N 次尝试结果(失败可重试)
done	同 /pix-short 的 200 响应体	整体完成 (ok 或失败终态), 之后服务端 close

curl -N -X POST \
  -H 'content-type: application/json' \
  -H 'accept: text/event-stream' \
  -H 'Authorization: Bearer YOUR_PIX_SHORT_TOKEN' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/pix-short/stream

POST /api/v1/upi

POST/api/v1/upi

印度 UPI 支付: 输入 AC token → checkout (IN/INR) → Stripe UPI 协议 → 返回授权链接或二维码。

请求	类型	说明
Authorization	header?	Bearer <upi_service_token \| upi_business_token>。后台两个 token 任一匹配即可放行,全空 = 不鉴权。
token	string	AC token (必填, JWT 格式)
promoId	string?	默认 plus-1-month-free
poolKeep	int?	并发参数 1~50 (默认后台配置)
poolMax	int?	尝试上限 1~2000 (默认后台配置)

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| invalid-token-format \| token-invalidated \| already-paid \| risk-blocked \| checkout-failed \| region-failed \| pm-unavailable \| snapshot-failed \| confirm-error \| confirm-failed \| approve-blocked \| no-next-action \| account-not-phone \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| cdk-busy \| bad-request \| server-error
retryable	bool	失败时附带。false = 不可重试(拿不到连接的终态 `approve-blocked` / `no-next-action`, 以及 token/账号类永久失败 `already-paid` / `token-invalidated` / `jwt-expired` / `unauthorized` / `account-not-phone` 等); true = 可重试(临时性错误 `concurrency-busy` / `rate-limited` / `server-error` / 网络类)。approve-blocked / no-next-action 表示已跑完整流程仍拿不到 UPI 连接, 重试同 token 也是同结果, 应换 token/账号; account-not-phone 表示后台开启「UPI 只接受手机号账户」开关而该 token 为邮箱注册, 应换手机号注册账户
message	string?	面向终端用户的中文友好提示 (失败时附带)
next_action_type	string	redirect_to_url \| upi_handle_redirect_or_display_qr_code \| display_upi_qr_code
upi_redirect_url	string	UPI 授权跳转链接
upi_qr_data	string	UPI deep-link payload (部分地区返回)
upi_qr_image_url	string	UPI 二维码图片 URL
upi_hosted_url	string	Stripe 托管支付指引页
request_id / duration_ms	string/int	请求追踪 id / 总耗时毫秒
⚠ 超时提示	POOL 枪数跑满可能耗时 ~3-5 分钟, HTTP 客户端超时请设为 ≥ 300秒。如需实时反馈, 推荐调 SSE 端点 /api/v1/upi/stream

curl -X POST \
  -H 'Authorization: Bearer YOUR_UPI_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","poolKeep":50,"poolMax":2000}' \
  https://YOUR_HOST/api/v1/upi

POST /api/v1/upi/stream

POST/api/v1/upi/stream

UPI 支付 SSE 实时进度流。鉴权 / 请求体同 /api/v1/upi。

SSE 事件	负载字段
event: hello	{request_id, pool_keep, pool_max, queue_length, inflight, capacity}
event: progress · attempt-start	{type:"attempt-start", pool_keep, pool_max}
event: progress · step	{type:"step", step:"<枚举>"} — step 枚举: `warmup` \| `sentinel` \| `checkout` \| `warmup-account` \| `region` \| `snapshot` \| `confirm` \| `approve` \| `polling`
event: progress · approve-tick	{type:"approve-tick", slot, max, blocked, exception, other, elapsed_ms} — 每 50 枪采样一次
event: progress · approve-hit	{type:"approve-hit", slot} — 某一枪命中, 后面仅有 polling 步骤
event: progress · attempt-end	{type:"attempt-end", ok, reason, error}
event: done	精简响应体 — 与 POST /api/v1/upi 同样结构
: ping (注释行)	每 15s 一个 keep-alive, 供越过代理/CDN 空闲超时

curl -N -X POST \
  -H 'Authorization: Bearer YOUR_UPI_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/upi/stream

POST /api/v1/gopay

POST/api/v1/gopay

印尼 GoPay：AC token → checkout (ID/IDR) → 若后台配置 gopay_update_proxy_url 则 JP/BR/VN checkout/update 挂促并要求 due=0 → Stripe confirm(gopay) → approve POOL → Midtrans Snap。与 Kakao 不同（无 NicePay / finalize）；清空 update 代理 = 正价。历史：Midtrans 对 due=0 可能 si-declined。body 传 proxy 覆盖后台线路；CDK + 自带代理只有出码成功才扣次数。

请求	类型	说明
Authorization	header?	Bearer <gopay_service_token \| gopay_business_token> 或 CDK scope=`gopay`。全空 = 不鉴权。
token	string	AC token (必填, JWT 格式)
poolKeep	int?	approve 并发槽 1~50 (默认后台)
poolMax	int?	approve 枪数上限 1~2000 (默认后台)
retryCount / setupRetry	int?	建单/confirm/approve/代理失败后换隧道整链再跑 N 次（0=失败即停；默认后台，现默认 1=共 2 轮）。资格不符/已付费/token 过期不重试。POOL keep/max 只是每一轮 approve 枪数
proxy	string?	调用方自带 IPWEB 代理：`gate3.ipweb.cc:7778:B_87916_ID___30_$RAND:pass` / `user:pass@host:port` / URL。有值则整链走这条，覆盖后台。配合 CDK 时只有出码成功才扣次数

响应	类型	说明
ok / reason	bool/string	成功或失败原因
retryable	bool	失败时附带。`promo-not-supported` / `si-declined` / `pm-unavailable` / `approve-blocked` / `no-redirect` 等为 false
gopay_redirect_url	string	主字段：`https://app.midtrans.com/snap/v4/redirection/<uuid>`
midtrans_snap_url	string	同 gopay_redirect_url
gopay_qr_data / gopay_qr_image_url	string?	能从 Snap txn 抽到才有
billing_country / currency	string	固定 `ID` / `IDR`
amount_total	int?	挂促成功为 0；正价约 34900000
promo_applied	bool	是否走了挂促且 due=0
request_id / duration_ms	string/int	追踪 id / 耗时

curl -X POST \
  -H 'Authorization: Bearer YOUR_GOPAY_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","proxy":"gate3.ipweb.cc:7778:B_87916_ID___30_$RAND:pass"}' \
  https://YOUR_HOST/api/v1/gopay

POST /api/v1/gopay/stream

POST/api/v1/gopay/stream

GoPay SSE 实时进度流。鉴权 / 请求体同 /api/v1/gopay。

SSE 事件	负载字段
event: hello	{request_id, pool_keep, pool_max, queue_length, inflight, capacity}
event: progress · step	step: warmup\|sentinel\|checkout\|region\|snapshot\|confirm\|approve\|polling\|chain-retry
event: progress · approve-tick / approve-hit	POOL 进度采样 / 命中
event: done	同 POST /api/v1/gopay

curl -N -X POST \
  -H 'Authorization: Bearer YOUR_GOPAY_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/gopay/stream

GET /api/v1/gopay/qr.png

GET/api/v1/gopay/qr.png

无状态 PNG（query d=base64url(qr payload)）。

POST /api/v1/gcash-check · GCash 资格硬查

POST/api/v1/gcash-check

只查 GCash 行不行（不挂促、不出码）。看 has_gcash / gcash_pm_eligible。
限速：AUTH_TOKEN / 服务·商务 token / CDK 走 RPM + 并发配额（无 30s 冷却）；仅未鉴权自带 proxy 同一 IP 30 秒 1 次。与 /api/v1/check 硬查共用规则。

字段名	说明
Authorization	Bearer 管理 AUTH_TOKEN，或 gcash_service / business / CDK
token	账号 AC Token
proxy	可选；用户自带 IPWEB（无管理鉴权时常用）

curl -X POST https://YOUR_HOST/api/v1/gcash-check \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -d '{"token":"eyJ..."}'

POST /api/v1/gcash · GCash 出码

POST/api/v1/gcash

标准入参：API 鉴权 + 完整 Session。 Session = 浏览器 https://chatgpt.com/api/auth/session 返回的整段 JSON，必须同时含 accessToken + sessionToken。服务端自行拆字段，用于出码与付款后 continue / 刷 AT。本接口在出码成功后立即返回，后台再轮询付款并激活。同步出码超时建议 ≥ 240 秒。演示页 /gcash。
挂促/建单出口由后台 gcash_same_ip 或请求体 sameIp 决定：0=JP 建单 + PH 出码；1=全程 PH 同隧道（check_coupon + 建单内嵌促销）。后半段 taxes/confirm/cpm 不变。

字段名	说明
Authorization	Header `Bearer`：`gcash_service_token` / `gcash_business_token` / CDK（scope=gcash）任一即可。也支持 `?key=`。两个业务 token 都空 = 不鉴权
session	必填。完整 Session JSON（须含 `accessToken` + `sessionToken`）。示例：`{"session":{...}}`。也可把该对象整段直接当 body
sameIp	可选。覆盖后台 `gcash_same_ip`（`true/false` 或 `0/1`）

仅传 AT（eyJ）会被拒，reason=missing-session-token，不会出码。不要再只丢 accessToken。

成功	说明
ok = true	出码成功（不等于已开通 Plus）
gcash_qr_image_url	二维码图片
gcash_qr_data	二维码内容（GCSHLNK…）
gcash_qr_ok	是否抽到合法 GCSHLNK
gcash_redirect_url	跳转链接
session_id	checkout session id（oaics_…）
promo_applied	是否已挂上 0 元优惠
finalize_started	后台是否已开始等付款 / 激活
finalize_wait_sec	后台最多等付款秒数（默认跟随后台，常见 1200）

失败	说明
ok = false	失败，看 `reason` + retryable
retryable = false	不要重试（换号或停）
retryable = true	可稍后重试

不要重试 reason	含义
missing-session-token	缺 sessionToken，未出码
pm-unavailable / coupon-not-eligible	没 GCash 资格 / 优惠不可用（换号）
account-not-phone / email-not-whitelisted	账号不符合
already-paid / risk-blocked	已付 / 风控
jwt-expired / token-401 / token-invalidated / empty-token / invalid-token-format	token 问题
unauthorized / feature-disabled	鉴权/开关
approve-blocked / confirm-blocked / no-redirect	终态失败
cdk-busy / checkout-failed	按代码不可重试

可以重试 reason	含义
concurrency-busy / rate-limited	忙 / 限流
promo-not-applied / taxes-failed / proxy-error / confirm-failed	暂失败
server-error	服务异常

拿不准就看返回里的 retryable。

# 标准：Authorization + body.session
curl -X POST https://cha.nerver.cc/api/v1/gcash \
  -H 'Authorization: Bearer YOUR_GCASH_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"session":{"accessToken":"eyJ...","sessionToken":"eyJ...","user":{},"account":{}}}'

# 或：/api/auth/session 整段 JSON 直接当 body（等价）
curl -X POST https://cha.nerver.cc/api/v1/gcash \
  -H 'Authorization: Bearer YOUR_GCASH_TOKEN' \
  -H 'content-type: application/json' \
  -d @session.json

POST /api/v1/gcash/stream

POST/api/v1/gcash/stream

SSE 进度流。请求同 /api/v1/gcash（鉴权 + 完整 Session）。
顺序：hello → progress（出码步骤）→ done（出码成功，字段同同步接口）→ 若 finalize_started，连接不会立刻关，继续推 progress（type=finalize / finalize-end，例如「开通成功」）→ 然后才断开。
不要在 done 后立刻断开。 若要等到开通成功，客户端超时请按 finalize_wait_sec 预留（默认 1200 秒）。

curl -N --max-time 1300 -X POST https://cha.nerver.cc/api/v1/gcash/stream \
  -H 'Authorization: Bearer YOUR_GCASH_TOKEN' \
  -H 'content-type: application/json' \
  -H 'accept: text/event-stream' \
  -d @session.json

POST /api/v1/ph-link · PH Link 菲律宾提链

POST/api/v1/ph-link

菲律宾直卡提链。PH/PHP 建单（出口 PH）。未传 plan 时挂促并强制 0 元；传了 plan 时跳过挂促出正价链。
挂促出口由后台 ph_link_same_ip 或请求体 sameIp 决定：1 = 与建单同一 IP（域名邮箱版：check_coupon + 建单内嵌 promo_campaign，应付已是 0 则不再 update）；0 = PH 建单后再走另一条代理 checkout/update。
processor_entity 优先用上游返回（域名邮箱抓包为 openai_llc）。演示页 /ph-link。

请求	类型	说明
Authorization	header?	Bearer <ph_link_service_token \| ph_link_business_token>。后台两个 token 任一匹配即可放行；全空 = 不鉴权。也支持 `?key=<token>`。
token	string	AC token (必填, JWT / eyJ 开头)
plan	string?	套餐 id。有值=正价不挂促：`chatgptplusplan` \| `chatgptprolite` \| `chatgptpro`。不传=Plus 0 元促销
promoId	string?	仅促销模式；默认 plus-1-month-free
sameIp	bool?	挂促与建单是否同一出口。不传=跟随后台 `ph_link_same_ip`
country	—	已忽略；固定 PH

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| invalid-token-format \| token-invalidated \| already-paid \| risk-blocked \| checkout-failed \| update-failed \| promo-not-applied \| coupon-not-eligible \| unsupported-plan \| proxy-missing \| proxy-country-mismatch \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| aborted \| bad-request \| server-error
retryable	bool	失败时附带
message	string?	面向终端用户的中文提示
pm	string	固定 `"ph_link"`
checkout_url	string	★ ChatGPT checkout 短链
session_id	string	`oaics_...` 或 `cs_...`
processor_entity	string	上游返回优先，缺省 `openai_ie`
billing_country / currency	string	固定 `PH` / `PHP`
plan_name	string	实际建单套餐 id
amount_total	int\|null	促销：0 或 null；正价通常 null
amount_verification	string	`verified_zero` \| `pending` \| `skipped_paid_plan`
promo_applied	bool	是否走了挂促
request_id / duration_ms	string/int	追踪 id / 耗时毫秒
⚠ 超时提示	通常 15~90s。HTTP 客户端建议超时 ≥ 120s。实时进度见 /api/v1/ph-link/stream

curl -X POST \
  -H 'Authorization: Bearer YOUR_PH_LINK_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/ph-link

# 正价 Pro（不挂促）:
# -d '{"token":"eyJ...","plan":"chatgptpro"}'

# 成功响应示例（促销）:
# {
#   "ok": true,
#   "pm": "ph_link",
#   "checkout_url": "https://chatgpt.com/checkout/openai_ie/oaics_...",
#   "billing_country": "PH",
#   "currency": "PHP",
#   "amount_total": 0,
#   "amount_verification": "verified_zero",
#   "promo_applied": true
# }

POST /api/v1/ph-link/stream

POST/api/v1/ph-link/stream

PH Link SSE 实时进度流。鉴权 / 请求体同 /api/v1/ph-link。

SSE 事件	负载字段
event: hello	{request_id, queue_length, inflight, capacity, country:"PH", plan, promo}
event: progress · step	{type:"step", step, attempt?, try?, status?, due?, success?, error?} — step: `proxy-preflight` \| `warmup` \| `checkout` \| `update` \| `verify-amount` \| `done`
event: done	与 POST /api/v1/ph-link 同样结构的终态 JSON
: ping (注释行)	每 15s keep-alive

curl -N -X POST \
  -H 'Authorization: Bearer YOUR_PH_LINK_TOKEN' \
  -H 'content-type: application/json' \
  -H 'accept: text/event-stream' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/ph-link/stream

POST /api/v1/ideal · 测试通道

POST/api/v1/ideal

测试通道授权链接生成: 输入 AC token → 上游协议 → 返回 iDEAL 原生 QR 内容 / 服务端 PNG / 授权跳转 URL。支持 POOL 抢风控, 内部账单地址按后台开关切换 (NL/JP/随机)。
★ 字段命名跟 /api/v1/kakao-pay 对齐: pm / ideal_qr_data / ideal_qr_image_url — 跨渠道调用方代码可以共用。

请求	类型	说明
Authorization	header?	Bearer <ideal_service_token \| ideal_business_token>。后台两个 token 任一匹配即可放行,全空 = 不鉴权。
token	string	AC token (必填, JWT 格式)
promoId	string?	默认 plus-1-month-free
poolKeep	int?	并发参数 1~50 (默认后台配置)
poolMax	int?	尝试上限 1~2000 (默认后台配置)

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| invalid-token-format \| token-invalidated \| already-paid \| risk-blocked \| checkout-failed \| region-failed \| pm-unavailable \| snapshot-failed \| confirm-error \| confirm-failed \| approve-blocked \| no-next-action \| aborted \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| email-not-whitelisted \| bad-request \| server-error
retryable	bool	★ 失败时附带. `false` = 不可重试 (同 token 重试也是同结果, 请换 token/账号). `true` = 可重试 (临时错: `concurrency-busy` / `rate-limited` / `server-error` / 网络类). `email-not-whitelisted` 表示后台开启「iDEAL 邮箱白名单」而该账户邮箱不在允许列表, 应换账户或联系运营添加
message	string?	面向终端用户的中文友好提示 (失败时附带)
pm	string	★ 渠道标识, 固定 `"ideal"` (跟 KakaoPay/PIX/UPI `pm` 字段对齐)
next_action_type	string	redirect_to_url
ideal_qr_data	string	★ 主字段: QR 字符串内容 — `https://tx.ideal.nl/2/<TX_ID>?sig=<SIG>`. 把它编码进二维码, 用户手机相机扫码 → 唤起银行 App / iDEAL App 直接付款 (跟 `kakao_qr_data` 同语义)
ideal_qr_image_url	string	★ 主字段: 服务端生成的 PNG 图 URL — 调用方一次 GET 拿图 (/api/v1/ideal/qr.png). 跟 `kakao_qr_image_url` / `pix_qr_image_url` 同语义
ideal_qr_url	string	[兼容] 与 `ideal_qr_data` 同值, 老调用方继续可用; 新接入建议用 `ideal_qr_data`
ideal_redirect_url	string	Stripe 原始 redirect URL (`pm-redirects.stripe.com/...`) — 浏览器跟跳到 ideal.nl 选银行页
ideal_hosted_url	string	iDEAL 托管支付页 URL (`pay.ideal.nl/transactions/...?sig=...`) — 浏览器直接打开
ideal_payload_uri	string	URL-encoded 交易 URI (`https%3A%2F%2Ftx.ideal.nl%2F2%2F...`) — 高级集成用
ideal_creditor	string	收款方名称 (例如 `"OpenAI Ireland Limited"`)
ideal_amount	int?	金额 (单位: cent, 例如 `1` = €0.01)
ideal_issuers_count	int	支持的荷兰银行数量 (例如 18)
billing_locale / billing_country	string	账单地址国家配置 / 实际生成持卡人国家
request_id / duration_ms	string/int	请求追踪 id / 总耗时毫秒
⚠ 超时提示	POOL 枪数跑满可能耗时 ~3-5 分钟, HTTP 客户端超时请设为 ≥ 300秒。如需实时反馈, 推荐调 SSE 端点 /api/v1/ideal/stream

curl -X POST \
  -H 'Authorization: Bearer YOUR_IDEAL_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","poolKeep":50,"poolMax":2000}' \
  https://YOUR_HOST/api/v1/ideal

# 成功响应示例:
# {
#   "ok": true,
#   "pm": "ideal",
#   "ideal_qr_data": "https://tx.ideal.nl/2/ADBC...?sig=CGBC...",
#   "ideal_qr_image_url": "https://YOUR_HOST/api/v1/ideal/qr.png?d=aHR0cHM6...",
#   "ideal_qr_url": "https://tx.ideal.nl/2/ADBC...?sig=CGBC...",
#   "ideal_redirect_url": "https://pm-redirects.stripe.com/...",
#   "ideal_hosted_url": "https://pay.ideal.nl/transactions/...?sig=...",
#   "ideal_creditor": "OpenAI Ireland Limited",
#   "ideal_amount": 1,
#   "ideal_issuers_count": 18,
#   "billing_country": "NL",
#   "request_id": "req_xxxx",
#   "duration_ms": 62000
# }

POST /api/v1/ideal/stream

POST/api/v1/ideal/stream

测试通道 SSE 实时进度流。鉴权 / 请求体同 /api/v1/ideal。

SSE 事件	负载字段
event: hello	{request_id, pool_keep, pool_max, queue_length, inflight, capacity}
event: progress · attempt-start	{type:"attempt-start", pool_keep, pool_max}
event: progress · step	{type:"step", step:"<枚举>"} — step 枚举: `warmup` \| `sentinel` \| `checkout` \| `warmup-account` \| `region` \| `snapshot` \| `confirm` \| `approve` \| `polling` \| `follow-redirect` \| `ideal-initiate`
event: progress · approve-tick	{type:"approve-tick", slot, max, blocked, exception, other, elapsed_ms} — 每 50 枪采样一次
event: progress · approve-hit	{type:"approve-hit", slot} — 某一枪命中, 后面仅有 polling/follow-redirect 步骤
event: progress · redirect-result	{final_qr_url, followed_to_ideal_nl, got_real_qr_code_url, qr_source, hops} — follow stripe 跳转 + 拆 / 调 initiate 的结果摘要
event: progress · attempt-end	{type:"attempt-end", ok, reason, error}
event: done	精简响应体 — 与 POST /api/v1/ideal 同样结构
: ping (注释行)	每 15s 一个 keep-alive, 供越过代理/CDN 空闲超时

curl -N -X POST \
  -H 'Authorization: Bearer YOUR_IDEAL_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/ideal/stream

GET /api/v1/ideal/qr.png · iDEAL QR 图片

GET/api/v1/ideal/qr.png?d=<base64url>

服务端 PNG 图片端点 — 跟 /api/v1/kakao-pay/qr.png 同款。
调用方拿到响应里的 ideal_qr_image_url 字段, 一次 GET 即可拿 PNG (480x480, ~2-3KB)。无状态生成, 不存数据库, 无鉴权 (公开图片链接, 含 base64url 编码的 QR 字符串作为输入参数)。可缓存 5 分钟。

请求	类型	说明
d	query string	QR 字符串内容的 base64url 编码 (一般直接用响应里 `ideal_qr_image_url`, 不需自己构造)

响应	说明
200	image/png — 480x480 PNG, 错误纠正等级 M, 边距 2
400	缺少/超长/无效 base64url

# 通常不需要手动调, 拿响应里 ideal_qr_image_url 字段直接用
curl -o ideal-qr.png 'https://YOUR_HOST/api/v1/ideal/qr.png?d=aHR0cHM6Ly90eC5pZGVhbC5ubC8yLy4uLg'

POST /api/v1/blik · BLIK 波兰支付

POST/api/v1/blik

波兰 BLIK 内部支付 — 输入 ChatGPT AC token + 从手机银行 App 拿的 BLIK 6 位授权码 (2 分钟有效), 服务端完成 checkout/snapshot/confirm/PI-confirm/approve POOL 全流程。
setup 阶段 sticky IP: warmup→snapshot 五步共用一个 PL ipweb 出口 (避免 CF 风控同 token 多 IP 误判). pay 阶段才走 $RAND 旋出口.
性能: setup 阶段 sentinel 4 个 chatgpt 请求 + warmup-account/elements 三路全并发 (~22-24s 到 confirm; 之前 ~32s).
鉴权: blik_service_token / blik_business_token 任一区配合 (都空=不鉴权). 并发: blik_concurrency (入站) + blik_pool_keep/blik_pool_max (approve 抢风控).

请求	类型	说明
token	string	必填 — ChatGPT AC token (eyJ JWT)
blikCode	string	必填 — BLIK 6 位授权码 (仅数字, 可带空格/划线, 服务端会 normalize)
poolKeep	number?	approve 并发槽数覆盖 (默认读 settings.blik_pool_keep=50, 上限 50)
poolMax	number?	approve 累计枪数覆盖 (默认读 settings.blik_pool_max=2000, 上限 2000)
promoId	string?	优惠 ID (默认 plus-1-month-free)
⚠ 超时提示	POOL 枪数跑满可能耗时 ~3-5 分钟, HTTP 客户端超时请设为 ≥ 300 秒. 实时反馈请调 /api/v1/blik/stream

响应	说明
ok	true / false
reason	ok / empty-token / invalid-token-format / jwt-expired / missing-blik-code / invalid-blik-code / token-invalidated / already-paid / risk-blocked / checkout-failed / region-failed / pm-unavailable / snapshot-failed / confirm-error / confirm-failed / pi-confirm-failed / approve-blocked / no-next-action / concurrency-busy / feature-disabled / cdk-busy / unauthorized / rate-limited / server-error
retryable	true=业务侧可重试; false=终态 (重试也是同结果)
next_action_type	blik_authorize 等 stripe 返回类型
blik_redirect_url / blik_hosted_url	BLIK 授权跳转链接 (如有)
setup_intent_id	Stripe PI/SI id (approve 通过后可见; pi-confirm 阶段提交 BLIK code 时用到)
request_id / duration_ms	请求 ID 与耗时

curl -X POST -H 'content-type: application/json' \
  -H 'authorization: Bearer YOUR_SERVICE_TOKEN' \
  -d '{"token":"eyJ...","blikCode":"123456"}' \
  https://YOUR_HOST/api/v1/blik

POST /api/v1/blik/stream

POST/api/v1/blik/stream

BLIK 波兰支付 SSE 实时进度流。鉴权 / 请求体同 /api/v1/blik。
step 事件顺序: warmup → sentinel → checkout → warmup-account → region → snapshot → confirm → cfbody-dumped (调试模式) → approve → approve-body-dumped (调试模式) → approve-body-info → pi-confirm (有 PI 信息时) → pi-confirm-ok / pi-confirm-skipped → polling

SSE 事件	说明
event: hello	连接建立 {request_id, pool_keep, pool_max, queue_length, inflight, capacity}
event: progress	进度: step / approve-tick / approve-hit / attempt-start / attempt-end
event: done	精简响应体 — 与 POST /api/v1/blik 同样结构

curl -N -X POST -H 'content-type: application/json' \
  -H 'accept: text/event-stream' \
  -d '{"token":"eyJ...","blikCode":"123456"}' \
  https://YOUR_HOST/api/v1/blik/stream

POST /api/v1/sp-pay · SP 支付

POST/api/v1/sp-pay

SP 支付：AC token + 授权手机号 → SetupIntent client_secret（无 QR / 无 redirect URL）。成功后在手机端完成授权确认。演示页 /sp。

请求	类型	说明
Authorization	header?	Bearer <sp_service_token \| sp_business_token>。后台两个 token 任一匹配即可放行,全空 = 不鉴权。
token	string	AC token (必填, JWT 格式)
phone	string	必填。授权手机号（E.164 或本地号，服务端会规范化）
promoId	string?	默认 plus-1-month-free；update 代理为空时走正价
poolKeep	int?	approve POOL 持续并发槽数 1~50 (默认后台)
poolMax	int?	approve POOL 累计尝试上限 1~2000 (默认后台)
retryCount	int?	整轮失败重试次数 0~5 (默认后台)

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| invalid-token-format \| invalid-phone \| feature-disabled \| unauthorized \| rate-limited \| concurrency-busy \| approve-blocked \| pm-unavailable \| checkout-failed \| confirm-failed \| aborted \| server-error
pm	string	固定 `sp`
phone	string	规范化后的手机号
sp_setup_intent_id	string	SetupIntent id (`seti_...`)
sp_client_secret	string	对接 Stripe.js 用的 client_secret
sp_publishable_key	string	pk_live_... / pk_test_...
sp_status	string	通常 `requires_action`
next_action	string	通常 `await_authorization`
session_id / due	string/number	Stripe Checkout session 与应付金额

curl -X POST -H 'content-type: application/json' \
  -H 'Authorization: Bearer <sp_token>' \
  -d '{"token":"eyJ...","phone":"+34123456789"}' \
  https://YOUR_HOST/api/v1/sp-pay

POST /api/v1/sp-pay/stream

POST/api/v1/sp-pay/stream

SP 支付 SSE 实时进度流。鉴权 / 请求体同 /api/v1/sp-pay。

事件	说明
event: hello	连接建立
event: progress	阶段进度
event: done	精简响应体 — 与 POST /api/v1/sp-pay 同样结构

curl -N -X POST -H 'content-type: application/json' \
  -H 'accept: text/event-stream' \
  -H 'Authorization: Bearer <sp_token>' \
  -d '{"token":"eyJ...","phone":"+34123456789"}' \
  https://YOUR_HOST/api/v1/sp-pay/stream

POST /api/v1/paypal · PayPal 授权链接（通用引擎）

POST/api/v1/paypal通用 CS+OS · 代理组合 · 智能账单

传入 AC token，返回最终 PayPal 授权链接 approve_url（无二维码）。默认通用引擎：建单是 oaics_ 走 OS/v3 pool，是 cs_live_ 自动切 CS/v1 approve pool，调用方不用选协议。也可后台强制仅 OS / 仅 CS。账单国决定会话国家与货币（DE→EUR）；建单 / 出口代理只改 IP，不必等于账单国。超时建议 ≥ 180s。演示页 /paypal。

两种鉴权方式（二选一）
① 传 Authorization: Bearer <服务Token / 商务Token / CDK> → 无需传代理，走后台线路。要换组合就在 body 里传 proxyCombo / checkoutProxyCountry + exitProxyCountry（后台 IPWEB 国家段自动改写）
② 自带 proxy 单代理（IPWEB 或任意 SOCKS5/HTTP 代理）→ 无需传鉴权 Token。组合字段同样能改写你传入的代理国家段

请求
字段	类型	说明
token	string	必填，AC token JWT（`eyJ...`）
Authorization	header?	内部鉴权 Token / CDK。传了即可不传代理
billingCountry	string?	账单国 ISO 2 位大写，默认 `GB`。决定 checkout 会话国家、persona 与货币（DE→EUR），不绑定代理 IP。支持 44 国。传其它值返回 `invalid-billing-country`。smartBilling=true 时此字段被忽略。
proxyCombo	string?	★ 代理组合简写（只改出口 IP）。`BR-BR` / `BR_BR` / `BR -> US` / `BRBR`。等价于同时传 checkout+exit。走后台线路时按国家段改写 IPWEB，不必传 proxy。可与账单国不同，例如 `BR-BR` + `billingCountry=DE`
checkoutProxyCountry	string?	建单代理出口国（warmup/checkout/taxes）。鉴权时改写后台 setup/promo 代理；可与账单国不同
exitProxyCountry	string?	最终出口代理国（confirm/pool）。鉴权时改写后台 pay 代理；空=同建单代理
checkoutCurrency	string?	可选 ISO 4217 覆盖货币。空=跟随账单国（DE→EUR）。页面不再传此字段，一般不必手填
usePromo	bool?	是否挂促（默认后台配置）。挂促场景 chatgpt 若识别账户有 `plus-1-month-free` 资格则收 0 元
promoCountries	string[]?	挂促候选国池（依次尝试），默认后台 `paypal_promo_countries`（如 `["TR","BR","JP"]`）。仅 `usePromo=true` 生效
smartBilling	bool?	★ 智能账单模式。true = 后端并行探测 `smartBillingCountries[]`，首个出 `oaics_` 的账单国进入 POOL 撞击。与 usePromo/promoCountries 正交可同时勾。默认 `false`
smartBillingCountries	string[]?	★ 智能账单候选国。仅 `smartBilling=true` 生效。默认 `["US","FR","GB","DE","CA","AU"]`。每国跑一次并行 checkout 探测，首个 `oaics_` 获胜；全 `cs_live_` 则报 `cs-not-oaics`
proxy	string?	自带单代理（覆盖后台代理）。格式：`host:port:user:pass` / `user:pass@host:port` / URL。建议含 `$RAND`（v3 撞击时自动换 SID）。有鉴权 Token 时可省
promoId	string?	促销 ID，默认后台（通常 `plus-1-month-free`）

成功响应
字段	类型	说明
ok	true	成功
pm	"paypal"	支付方式标识
approve_url	string	★ 最终授权链接（`https://www.paypal.com/agreements/approve?ba_token=BA-xxx`，给用户打开即可）
ba_token	string	PayPal Billing Agreement token（`BA-xxx`），拆自 `approve_url`
stripe_redirect_url	string	Stripe 中转 URL（内部诊断用）
billing_country	string	命中的账单国（智能账单模式下 = 获胜国）
currency	string	实际计价货币（默认跟随账单国）
checkout_currency	string	同 `currency`（未覆盖时等于账单国货币）
proxy_combo	string	实际代理组合，如 `BR -> BR`
checkout_proxy_country / exit_proxy_country	string	建单代理国 / 出口代理国
use_promo	bool	是否挂促
promo_country	string?	挂促国（若 use_promo=true）
smart_billing	bool	是否智能账单模式
engine / protocol	string	实际命中：`v3`+`os` 或 `v1`+`cs`（通用模式自动选）
tried_countries	string[]	本次尝试过的所有国家（智能账单模式下按顺序列出）
attempts	number	attempt 次数
expected_amount	number	checkout 应收金额（0 = 挂促成功）
session_id	string	`oaics_xxx` 或 `cs_live_xxx`（视命中协议）
setup_intent_id	string	Stripe `seti_xxx`
request_id	string	追踪 id
duration_ms	number	本次耗时（毫秒）

失败响应 / 错误码
字段	类型	说明
ok	false	失败
reason	string	错误码（见下表）
message	string	中文用户友好提示
error	string	底层错误详情（截断到 400 字符）
retryable	bool	是否可重试
smart_billing	bool	是否智能账单模式
tried_countries	string[]	尝试过的所有国家
attempts	number	已尝试次数

reason	含义	建议
unauthorized	既无鉴权也无自带代理	传 Token/CDK 或传 proxy
invalid-token-format / empty-token / jwt-expired / token-invalidated	AC 无效或过期	换 token
invalid-billing-country	账单国不在 44 国白名单	校对 ISO 码
cs-not-oaics	账号建单返回 `cs_live_`。通用引擎会自动切 v1；仅当后台锁死 v3、或智能账单各国都未出链时才会作为最终失败	默认不用处理。强制仅 OS 时换号，或改回 `paypal_engine=auto`
already-paid	已付过订阅	换号
risk-blocked	checkout 被 CF/风控拦	换号 / 换代理
pm-unavailable	无 PayPal 资格	换号或换账单国（智能账单模式自动尝试）
promo-not-applied / promo-ineligible	挂促失败	换未试用号，或 `usePromo=false`
checkout-failed	建 cs 失败（非 401）	看 error 详情，检查代理
taxes-failed	taxes 请求失败	换 IP 重试
ctoken-failed	Stripe `/v1/confirmation_tokens` 失败（多为账号被 Stripe 风控）	换号或换代理
confirm-failed	chatgpt `/checkout/confirm` 拒绝（pool 换 IP 撞多次仍失败）	换号或换代理
no-next-action	confirm 200 但 Stripe 未返回 setup_intent（chatgpt 后端 `status: blocked`）	换号或换 IP
seti-no-redirect	seti confirm 失败，未拿 PayPal 跳转	换号或换 IP
ba-token-missing	拿到 Stripe 跳转但未解析出 BA-token	检查代理链路
cs-consumed	checkout session 已被消费	自动新建重试
captcha-required	Stripe 要求 hCaptcha 挑战	后台需接入 hCaptcha 求解
all-retries-failed	全候选国跑完仍未命中（含智能账单模式）	看 `message` 里列出尝试过的国；换更好账号/代理
proxy-invalid	代理格式错	检查 `host:port:user:pass`
rate-limited / server-busy / server-error	限流或临时错	稍后重试（`retryable=true`）
feature-disabled	通道后台禁用	联系管理员

# ① ★ 外部鉴权 + 自选代理组合（不传 proxy，走后台线路改写国家段）
#    例: BR→BR 代理 IP + 德国账单（货币自动 EUR，不必传 checkoutCurrency）
curl -X POST https://YOUR_HOST/api/v1/paypal \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <服务Token或CDK>' \
  -d '{
    "token":"eyJ...",
    "billingCountry":"DE",
    "proxyCombo":"BR-BR"
  }'
# 等价写法:
#   "checkoutProxyCountry":"BR","exitProxyCountry":"BR"
# 其它组合: "TR-TR" / "JP-JP" / "TR-US" / "BR -> DE"

# ①b 基础用法：内部鉴权 + 单账单国 + 挂促
curl -X POST https://YOUR_HOST/api/v1/paypal \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <服务Token或CDK>' \
  -d '{"token":"eyJ...","billingCountry":"GB","usePromo":true,"promoCountries":["TR","BR"]}'

# ② ★ 智能账单模式 (推荐)：并行探测 6 国, 首个 oaics_ 获胜
curl -X POST https://YOUR_HOST/api/v1/paypal \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <服务Token或CDK>' \
  -d '{
    "token":"eyJ...",
    "smartBilling": true,
    "smartBillingCountries": ["US","FR","GB","DE","CA","AU"],
    "usePromo": true,
    "promoCountries": ["TR","BR"]
  }'

# ③ 自带代理 —— 不传鉴权
curl -X POST https://YOUR_HOST/api/v1/paypal \
  -H 'content-type: application/json' \
  -d '{
    "token":"eyJ...",
    "smartBilling": true,
    "smartBillingCountries": ["US","FR","GB","DE","CA","AU"],
    "proxy": "gate3.ipweb.cc:7778:B_87916_$COUNTRY___30_$RAND:pass"
  }'
# 注: 指定 proxyCombo 时代理国家段按组合改写, 不跟账单国; 未指定组合且智能账单时, IPWEB 国家段会按账单国改写

# 成功响应示例:
# {"ok":true,"pm":"paypal","approve_url":"https://www.paypal.com/agreements/approve?ba_token=BA-...",
#  "ba_token":"BA-...","billing_country":"GB","currency":"GBP","smart_billing":true,
#  "tried_countries":["US","FR","GB","DE","CA","AU"],"attempts":6,"expected_amount":0,
#  "session_id":"oaics_...","request_id":"req_...","duration_ms":24800}

# 智能账单模式失败示例 (账号全 cs_live_):
# {"ok":false,"reason":"cs-not-oaics","message":"智能账单模式已尝试 6 个账单国 [US, FR, GB, DE, CA, AU], 全部未命中 PayPal 链接...",
#  "smart_billing":true,"tried_countries":["US","FR","GB","DE","CA","AU"],"attempts":6}

需要实时进度可调 POST /api/v1/paypal/stream（SSE，请求体相同）。事件流：open → progress（含 smart-probe-start / probe-step / smart-probe-end / attempt-start / step / attempt-end）→ result → done。智能账单模式会额外发 smart-probe-start（含候选国）和 smart-probe-end（含 winner + 统计）。

POST /api/v1/paypal-vip · PayPal VIP 🇹🇷 土耳其专用高成功率通道

POST/api/v1/paypal-vipv1 引擎 · TR/USD · old approve pool

土耳其 cs_live_ 老协议专用高成功率通道。底层使用 v1 引擎（老 approve pool，端点 POST /backend-api/payments/checkout/approve），强制 TR 建单 + TR 挂促 + USD 计价 + PayPal，抓包对齐 土耳其PP全流程_20260814。独立代理池 / 独立并发信号量 / 独立 CDK 配额，不占用普通 /paypal 通道资源。演示页 /paypalvip。

两种鉴权方式（二选一）
① 传 Authorization: Bearer <paypalvip_service_token / paypalvip_business_token / CDK> → 无需传代理，走后台 VIP 线路
② 自带 proxy（必须 TR 出口 IP）→ 无需传鉴权 Token

请求
字段	类型	说明
token	string	必填，AC token JWT（`eyJ...`）
Authorization	header?	内部 `paypalvip_service_token` / 商务 `paypalvip_business_token` / CDK
proxy	string?	自带单代理（TR 出口）。格式：`host:port:user:pass` / URL；建议含 `$RAND` 让 approve pool 每次换 SID。有鉴权 Token 时可省
promoId	string?	促销 ID，默认 `plus-1-month-free`

成功响应
字段	类型	说明
ok	true	成功
pm	"paypal-vip"	支付方式标识
channel	"vip-tr"	通道标签
approve_url	string	★ 最终 PayPal 授权链接（`https://www.paypal.com/agreements/approve?ba_token=BA-xxx`）
ba_token	string	PayPal BA-token（`BA-xxx`）
stripe_redirect_url	string	Stripe 中转 URL（内部用）
billing_country	"TR"	固定 TR
currency	"USD"	固定 USD
use_promo	true	固定挂促
promo_country	"TR"	固定 TR
session_id	string	`cs_live_...` checkout session id
setup_intent_id	string	Stripe 内部 id
attempts	number	attempt 次数
request_id / duration_ms	string/number	追踪 id 和耗时

失败响应 / 错误码
字段	类型	说明
ok	false	失败
reason	string	错误码（见下表）
message	string	中文用户提示
retryable	bool	是否可重试

reason	含义	建议
unauthorized	既无鉴权也无自带代理	传 Token/CDK 或 proxy
invalid-token-format / empty-token / jwt-expired / token-invalidated	AC 无效或过期	换 token
already-paid	已订阅	换号
risk-blocked	风控拦截	换号 / 换代理
pm-unavailable	无 PayPal 资格	换号
promo-not-applied / promo-ineligible	TR 挂促 0 元失败	换未试用号
approve-blocked	approve pool 全拒（累计撞完 pool_max 仍未命中）	换号 / 稍后重试
no-redirect / no-ba-token	未拿到跳转/BA-token	换号或换代理
cdk-busy	CDK 已有请求在处理或全局 CDK 配额已满	等待或换 CDK
proxy-invalid	代理格式错	检查 `host:port:user:pass`
rate-limited / server-busy	限流/并发已满	稍后重试（`retryable=true`）
feature-disabled	VIP 通道后台已禁用	联系管理员

# ① 内部鉴权（无需代理）
curl -X POST https://YOUR_HOST/api/v1/paypal-vip \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <paypalvip_service_token 或 CDK>' \
  -d '{"token":"eyJ..."}'

# ② 自带 TR 代理（免鉴权）
curl -X POST https://YOUR_HOST/api/v1/paypal-vip \
  -H 'content-type: application/json' \
  -d '{
    "token":"eyJ...",
    "proxy":"gate3.ipweb.cc:7778:B_87916_TR___30_$RAND:pass"
  }'

# 成功响应示例（拿 approve_url 让用户打开即可完成 PayPal 授权）:
# {"ok":true,"pm":"paypal-vip","channel":"vip-tr",
#  "approve_url":"https://www.paypal.com/agreements/approve?ba_token=BA-...",
#  "ba_token":"BA-...","billing_country":"TR","currency":"USD",
#  "use_promo":true,"promo_country":"TR","session_id":"cs_live_...",
#  "attempts":1,"request_id":"req_...","duration_ms":38000}

需要实时进度可调 POST /api/v1/paypal-vip/stream（SSE，请求体相同）。事件流：open → progress（含 attempt-start / step (warmup/sentinel/checkout/init/taxes/snapshot/confirm/approve/ba-token-ready) / approve-tick / approve-hit / attempt-end）→ result → done。

POST /api/v1/paypal-uk · PayPal UK 🇬🇧 英国定向提链

POST/api/v1/paypal-ukv1 引擎 · GB/GBP · old approve pool · 停在 /pay

英国 cs_live_ 定向提链。底层复用 v1 引擎（老 approve pool），强制 GB 建单 + GB 挂促 + GBP + PayPal，抓包对齐 英国PP全流程_20260822。成功停在 https://www.paypal.com/pay?ssrt=...&token=BA-...&ul=1，不跟后续登录。独立代理 / 独立并发 / 独立 CDK，不占用 /paypal 与 /paypal-vip。演示页 /paypaluk。

两种鉴权方式（二选一）
① 传 Authorization: Bearer <paypaluk_service_token / paypaluk_business_token / CDK> → 无需传代理，走后台 UK 线路
② 自带 proxy（会改写为 GB 出口）→ 无需传鉴权 Token

请求
字段	类型	说明
token	string	必填，AC token JWT（`eyJ...`）
Authorization	header?	内部 `paypaluk_service_token` / 商务 `paypaluk_business_token` / CDK（scope=`paypal-uk` 或 `*`）
proxy	string?	自带单代理。格式：`host:port:user:pass` / URL；建议含 `$RAND`。有鉴权 Token 时可省
promoId	string?	促销 ID，默认 `plus-1-month-free`

成功响应
字段	类型	说明
ok	true	成功
pm	"paypal-uk"	支付方式标识
channel	"uk-gb"	通道标签
pay_url	string	★ 提取链接（`https://www.paypal.com/pay?ssrt=...&token=BA-xxx&ul=1`）
approve_url / qr_url	string	同 `pay_url`
ba_token	string	PayPal BA-token
billing_country	"GB"	固定 GB
currency	"GBP"	固定 GBP
session_id	string	`cs_live_...`
request_id / duration_ms	string/number	追踪 id 和耗时

# ① 内部鉴权（无需代理）
curl -X POST https://YOUR_HOST/api/v1/paypal-uk \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <paypaluk_service_token 或 CDK>' \
  -d '{"token":"eyJ..."}'

# ② 自带代理（免鉴权，出口会改写成 GB）
curl -X POST https://YOUR_HOST/api/v1/paypal-uk \
  -H 'content-type: application/json' \
  -d '{
    "token":"eyJ...",
    "proxy":"gate3.ipweb.cc:7778:B_87916_GB___30_$RAND:pass"
  }'

# 成功:
# {"ok":true,"pm":"paypal-uk","channel":"uk-gb",
#  "pay_url":"https://www.paypal.com/pay?ssrt=...&token=BA-...&ul=1",
#  "ba_token":"BA-...","billing_country":"GB","currency":"GBP"}

实时进度：POST /api/v1/paypal-uk/stream。

POST /api/v1/kakao-pay · 韩国 KakaoPay (二维码)

POST/api/v1/kakao-pay

韩国 KakaoPay 支付：输入 AC token → checkout (KR/KRW) → approve POOL 抢风控 → 跟 NicePay 8 hop → 拿到 KakaoPay bridge + tid + 真正可扫的 QR URL。详见 /docs/kakao-pay.md。

请求	类型	说明
Authorization	header?	Bearer <kr_service_token \| kr_business_token>。后台两个 token 任一匹配即可放行,全空 = 不鉴权。
token	string	AC token (必填, JWT 格式)
promoId	string?	默认 plus-1-month-free
poolKeep	int?	approve POOL 持续并发槽数 1~50 (默认后台 50)
poolMax	int?	approve POOL 累计尝试上限 1~2000 (默认后台 2000)
retryCount	int?	整轮失败重试次数 0~5 (默认后台 1)

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| invalid-token-format \| invalid-pm \| token-invalidated \| already-paid \| risk-blocked \| checkout-failed \| region-failed \| pm-unavailable \| snapshot-failed \| confirm-error \| confirm-failed \| approve-blocked \| no-redirect \| redirect-chain-failed \| payment-timeout \| aborted \| dump-only \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| bad-request \| server-error
retryable	bool	★ 失败时附带. `false` = 不可重试(同 token 重试也是同结果, 请换 token/账号或停止重试). `true` = 可重试(临时错: `concurrency-busy` / `rate-limited` / `server-error` / 网络类). 不可重试组: `already-paid` / `token-invalidated` / `jwt-expired` / `invalid-token-format` / `invalid-pm` / `unauthorized` / `feature-disabled` / `pm-unavailable` / `cdk-busy` / `approve-blocked`(2000 枪未过) / `no-redirect` / `redirect-chain-failed` / `risk-blocked` / `payment-timeout`(用户未付) / `aborted`(客户端断开) / `dump-only`(后台调试模式)
message	string?	面向终端用户的中文友好提示 (失败时附带)
kakao_qr_data	string	★ QR 字符串 — `https://online-payment.kakaopay.com/bridge/mobile-pc/reseller/subscription/issue/{hash}`. 用 KakaoTalk app 扫码会被识别为付款请求, 自动唤起流程. 跟 `pix_qr_data` / `upi_qr_data` 字段语义对齐
kakao_qr_image_url	string	★ QR PNG 图片 URL — 直接 `<img src="...">` 渲染. 跟 `pix_qr_image_url` / `upi_qr_image_url` 对齐. 内部走 GET /api/v1/kakao-pay/qr.png?d=<base64url> 无状态生成
qr_url	string	[兼容字段] 与 `kakao_qr_data` 同值, 老调用方继续可用. 新接入请用 `kakao_qr_data`
qr_https_url	string	iOS Safari fallback (`online-pay.kakaopay.com/pay/r1/{hash}`), 从 `ios_app_url` 解出。仅手机点击唤起 KakaoTalk, 不适合 PC 二维码
ios_app_url	string	移动端深链接 `kakaotalk://kakaopay/pg?...&url=...` — 移动浏览器内点击直接唤起 KakaoTalk
aos_app_url	string	Android Intent `intent://...#Intent;scheme=kakaotalk;...;end`
bridge_page_url	string	KakaoPay PC bridge 页面 URL (路径 `/bridge/pc/`, 浏览器打开看到 QR 图) — 不是扫码内容
kakaopay_bridge_url	string	同 bridge_page_url, 向后兼容字段
stripe_redirect_url	string	Stripe pm-redirects 中间链 (最保鲜, 备用)
kakao_tid	string	KakaoPay 交易 ID, 后续对账用
expired_at / expired_iso	int / string	QR 过期时间 (UTC 秒 / ISO), 通常 ~20 分钟有效
request_id / duration_ms	string / int	请求追踪 id / 总耗时毫秒
⚠ 超时提示	approve POOL 跑满可能耗时 ~3-5 分钟, HTTP 客户端超时请设为 ≥ 300秒。如需实时反馈, 推荐调 SSE 端点 /api/v1/kakao-pay/stream

curl -X POST \
  -H 'Authorization: Bearer YOUR_KR_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","poolKeep":50,"poolMax":2000}' \
  https://YOUR_HOST/api/v1/kakao-pay

POST /api/v1/kakao-pay/stream

POST/api/v1/kakao-pay/stream

KakaoPay 支付 SSE 实时进度流。鉴权 / 请求体同 /api/v1/kakao-pay。

SSE 事件	负载字段
event: hello	{request_id, pool_keep, pool_max, retry_count, queue_length, inflight, capacity}
event: progress · attempt-start	{type:"attempt-start", attempt, max}
event: progress · step	{type:"step", step:"<枚举>"} — step 枚举: `warmup` \| `sentinel` \| `checkout` \| `warmup-account` \| `region` \| `snapshot` \| `confirm` \| `approve` \| `polling` \| `redirect-chain` \| `bridge`
event: progress · approve-tick	{type:"approve-tick", slot, max, blocked, exception, other, elapsed_ms} — 每 50 枪采样一次
event: progress · approve-hit	{type:"approve-hit", slot} — 某一枪命中
event: progress · attempt-end	{type:"attempt-end", attempt, ok, reason, error}
event: done	精简响应体 — 与 POST /api/v1/kakao-pay 同样结构
: ping (注释行)	每 15s 一个 keep-alive, 越过代理/CDN 空闲超时

curl -N -X POST \
  -H 'Authorization: Bearer YOUR_KR_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/kakao-pay/stream

POST /api/v1/naver-pay · 韩国 NaverPay

POST/api/v1/naver-pay

韩国 NaverPay 支付：输入 AC token → checkout (KR/KRW) → approve POOL 抢风控 → 跟 NicePay 8 hop → 拿到 NaverPay 启动页 + Stripe redirect。详见 /docs/naver-pay.md。

请求	类型	说明
Authorization	header?	Bearer <kr_service_token \| kr_business_token>。跟 KakaoPay 共用 token, 任一匹配即可。
token	string	AC token (必填, JWT 格式)
funding	string?	NaverPay 资金源 `card` \| `points` (默认 card; 也接受旧字段名 `naverFunding`)
promoId	string?	默认 plus-1-month-free
poolKeep / poolMax / retryCount	int?	同 /kakao-pay

响应	类型	说明
ok / reason	bool/string	ok \| empty-token \| jwt-expired \| invalid-token-format \| token-invalidated \| already-paid \| risk-blocked \| checkout-failed \| region-failed \| pm-unavailable \| snapshot-failed \| confirm-error \| confirm-failed \| approve-blocked \| no-redirect \| redirect-chain-failed \| invalid-funding \| payment-timeout \| aborted \| concurrency-busy \| feature-disabled \| unauthorized \| rate-limited \| bad-request \| server-error
retryable	bool	★ 失败时附带. `false` = 不可重试(同 token 重试也是同结果). `true` = 可重试(临时错). 字段语义同 KakaoPay (见上方)
funding	string	实际使用的资金源 (card / points)
naverpay_bridge_url	string	★ NaverPay 启动页 URL — 用浏览器跳转或手机点击都能进入 NaverPay app/网页支付
stripe_redirect_url	string	Stripe pm-redirects 中间链 (最保鲜, 备选)
nicepay_url	string	NicePay 启动页 (PC 浏览器完整跳转)
qr_url	string	兼容字段, NaverPay 当前 = naverpay_bridge_url
request_id / duration_ms	string / int	请求追踪 id / 耗时毫秒

curl -X POST \
  -H 'Authorization: Bearer YOUR_KR_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","funding":"card"}' \
  https://YOUR_HOST/api/v1/naver-pay

POST /api/v1/naver-pay/stream

POST/api/v1/naver-pay/stream

NaverPay 支付 SSE 实时进度流。鉴权 / 请求体同 /api/v1/naver-pay。

SSE 事件	负载字段
event: hello	{request_id, funding, pool_keep, pool_max, retry_count, queue_length, inflight, capacity}
event: progress · attempt-start / step / approve-tick / approve-hit / attempt-end	同 /kakao-pay/stream (枚举一致)
event: done	精简响应体 — 与 POST /api/v1/naver-pay 同样结构

curl -N -X POST \
  -H 'Authorization: Bearer YOUR_KR_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ...","funding":"card"}' \
  https://YOUR_HOST/api/v1/naver-pay/stream

POST /api/v1/kr-checkout · [兼容] 旧统一 KR 端点

POST/api/v1/kr-checkout

已拆分为 /api/v1/kakao-pay 与 /api/v1/naver-pay。仍可用以兼容旧调用 — 通过 body.pm 切换。新接入请使用拆分后的端点。

请求	类型	说明
token	string	AC token
pm	string?	`kakao_pay` \| `naver_pay` (默认 kakao_pay)
naverFunding	string?	NaverPay 资金源 (仅 pm=naver_pay)
其他	—	poolKeep / poolMax / retryCount / promoId 同上

响应字段是 KakaoPay + NaverPay 字段并集; 同步 + SSE (/api/v1/kr-checkout/stream) 都保留。

POST /api/v1/inbox

POST/api/v1/inbox

IMAP+OAuth2 连接 Outlook,拉取邮件列表 (所有邮件)。

请求	类型	说明
line	string?	单行: email----password----refresh_token----client_id
email / password / refreshToken / clientId	string?	分字段模式
folder	string?	默认 INBOX
limit	number?	默认 50, 上限 200

响应	类型	说明
ok / reason	bool/string	ok \| missing-email \| connect-failed \| fetch-failed
email / folder / total	string/number	元信息
messages	array	[{uid, subject, from, to, date, snippet}]

curl -X POST -H 'content-type: application/json' -d '{"line":"user@hotmail.com----pwd----rt----cid","limit":20}' https://YOUR_HOST/api/v1/inbox

POST /api/v1/inbox/message

POST/api/v1/inbox/message

获取单封邮件完整内容。

请求	类型	说明
凭据	-	同 /api/v1/inbox
folder	string?	默认 INBOX
uid	number	邮件 UID (必填)

响应	类型	说明
ok / subject / from / to / date	-	邮件元信息
text	string	纯文本正文
html	string	HTML 正文
attachments	array	[{filename, contentType, size}]

POST /api/v1/inbox/folders

POST/api/v1/inbox/folders

列出邮箱所有文件夹。

请求	说明
凭据	同 /api/v1/inbox

响应	说明
folders	[{path, name, specialUse, flags}]

POST /api/v1/totp/enable · ChatGPT 2FA 开通

POST/api/v1/totp/enable

用 ChatGPT accessToken + 同会话 sessionToken 自动调 OpenAI mfa/enroll → activate_enrollment → mfa_info 三步, 为账号开通 TOTP 二步验证, 返回原始 Base32 secret 与 otpauth URI。
★ 默认会把成功开通的 (email, secret) 持久化到 totp_secrets 表 (PK = email, 重复开通会覆盖), 供 /lookup 按邮箱查实时 OTP。可在 admin 后台 settings.totp_store_enabled=0 关闭落库。
★ 调用前需确保账号已设密码 (OAuth 注册账号默认无密码 — 先去 ChatGPT 设置加密码, 否则即使开 2FA 下次登录仍要邮箱接码)。
★ OpenAI 安全策略 recent_auth_required: 必须在「最近一次密码登录后 5~10 分钟内」操作, 否则返回 reason=recent-auth-required。

请求	类型	说明
token	string	必填 — `chatgpt.com/api/auth/session` 返回的 `accessToken` (eyJ 开头 JWT)
sessionToken	string?	推荐 — 同接口返回的 `sessionToken` (next-auth JWE), 服务端会自动拼成 `__Secure-next-auth.session-token=...` cookie
cookie	string?	高级 — 直接传完整 cookie 头, 优先级高于 `sessionToken`
deviceId	string?	可选 — `oai-device-id` 头, 不传则自动生成 UUID

响应	说明
ok	true / false
reason	ok / already-enabled / empty-token / invalid-token-format / jwt-expired / token-401 / recent-auth-required / enroll-failed / mfa-not-enabled / fetch-error / http-error
alreadyEnabled	true = 账号已绑 2FA (不重置), 仅返回 factor_id
secret	Base32 原始密钥 (新开通才返回)
otpauthUrl	`otpauth://totp/...` URI, 可生成二维码
factorId / sessionId	OpenAI 内部 ID
email / account_id / plan_type	从 JWT 解出的账号信息
persisted	true = 已落库 totp_secrets 表

curl -X POST -H 'content-type: application/json' \
  -d '{"token":"eyJhbGciOi...","sessionToken":"eyJhbGciOiJkaXIi..."}' \
  https://YOUR_HOST/api/v1/totp/enable

POST /api/v1/totp/code · 本地 OTP 生成

POST/api/v1/totp/code

纯本地 RFC 6238 计算 (HMAC-SHA1, 30s 周期, 6 位), 输入 Base32 secret 返回当前 OTP 与剩余秒数。不发任何外网请求, 不查询/落库任何数据。也支持 GET /api/v1/totp/code?secret=...。

请求	类型	说明
secret	string	Base32 密钥 (A-Z 2-7, 可带空格 / 小写, 服务端自动 normalize)

响应	说明
code	6 位 OTP
secondsRemaining	当前 OTP 还能用几秒
period / digits / algorithm / epoch	固定 30 / 6 / sha1 / unix 秒
secretMasked / otpauthUrl	用于显示 / 二维码

curl -X POST -H 'content-type: application/json' \
  -d '{"secret":"JBSWY3DPEHPK3PXP"}' \
  https://YOUR_HOST/api/v1/totp/code

POST /api/v1/totp/lookup · 按邮箱查实时 OTP

POST/api/v1/totp/lookup

默认开放查询 (仅 IP 限速保护), 输入邮箱即可拿到该账号当前 OTP。
★ 仅能查通过 /enable 在本站开通过 2FA 的账号 (secret 必须先落库)。
★ admin 后台可配 settings.totp_lookup_token 切换为强保护模式 — 配了之后必须传 key 才能查。
★ IP 级 RPM 限速 (默认 20 RPM/IP), 超出返回 HTTP 429 + reason=rate-limited。在 admin 后台 settings.rate_rpm_totp_lookup 调整 (-1 = 不限, 0 = 继承全局)。

请求	类型	说明
email	string	必填 — 已开通过 2FA 的账号邮箱 (大小写不敏感)
key	string?	查询密钥; 仅在 admin 配了 `totp_lookup_token` 时必填

响应	说明
ok	true / false
reason	ok / not-found / unauthorized / invalid-email / invalid-stored-secret / totp-fail / rate-limited / server-error
code	当前 6 位 OTP
secondsRemaining	OTP 剩余可用秒数
secret / secretMasked / otpauthUrl	原始密钥 / 打码版 / 二维码 URI
email / account_id / plan_type / factor_id	账号信息
created_at / updated_at	首次开通 / 最近一次更新时间

# 默认开放模式
curl -X POST -H 'content-type: application/json' \
  -d '{"email":"user@example.com"}' \
  https://YOUR_HOST/api/v1/totp/lookup

# 强保护模式 (admin 配了 totp_lookup_token)
curl -X POST -H 'content-type: application/json' \
  -d '{"email":"user@example.com","key":"tlt_xxxx"}' \
  https://YOUR_HOST/api/v1/totp/lookup

POST /api/v1/passkey/enable · Passkey 开通

POST/api/v1/passkey/enable

给 ChatGPT 账号开通 WebAuthn Passkey 2FA。输入 access_token → 服务端调 ChatGPT MFA API 完成 enrollment → 返回完整凭据 (credential_id / privateJwk / ...). 成功后自动落库 (passkey_store_enabled=1)。

请求	类型	说明
token	string	ChatGPT access_token (JWT, 必填). 要求 pwd_auth_time 在 24h 内
sessionToken	string?	可选, __Secure-next-auth.session-token 值 (自动拼 cookie)
cookie	string?	可选, 完整 cookie 头 (优先于 sessionToken)
deviceId	string?	可选, oai-device-id (UUID)

响应	类型	说明
ok / reason	bool/string	ok \| mfa-token-failed \| mfa-token-empty \| enrollment-start-failed \| enrollment-start-empty \| enrollment-finish-failed \| empty-token \| invalid-token-format \| unauthorized \| rate-limited \| server-error
credentialId	string	base64url 凭据 ID (32 bytes random)
factorId	string	OpenAI mfa_factor_id (hex 32)
rpId	string	固定 "openai.com"
userHandle	string	原始明文 "user-XXX"
privateJwk	object	ES256 私钥 JWK {kty, crv, x, y, d} (仅 API 返回, lookup 不暴露)
publicKeyCose	string	COSE 公钥 (base64url CBOR)
persisted	bool	是否已落库
email / account_id / plan_type	string?	JWT 解出

curl -X POST -H 'content-type: application/json' \
  -d '{"token":"eyJ..."}' \
  https://YOUR_HOST/api/v1/passkey/enable

POST/api/v1/passkey/login

用已开通的 Passkey 凭据登录 chatgpt.com, 返回干净的 access_token (T2) + 完整 session cookies. 自动从 DB 查凭据 (也可手动传入). 全链路 8 步: csrf → signin → authorize → passkey challenge → 签名 → verify → callback → session.

请求	类型	说明
email	string	账号邮箱 (必填, 自动从 DB 查 passkey 凭据)
deviceId	string?	可选, oai-device-id; 留空自动生成 UUID
credentialId	string?	可选, 手动传入 (跳过 DB 查询)
privateJwk	object?	可选, 手动传入时必填
rpId / userHandle / signCount / alg	各类型	可选, 手动传入时的附加字段

响应	类型	说明
ok / reason	bool/string	ok \| missing-email \| missing-credential \| credential-not-found \| csrf-failed \| csrf-rejected \| signin-failed \| authorize-failed \| challenge-not-found \| verify-failed \| verify-no-callback \| session-failed \| session-empty \| rate-limited \| server-error
accessToken	string	T2 真 OAuth JWT (可用于 /backend-api/*)
cookies	object	完整 session cookies (键值对, 可导入浏览器)
email	string	账号邮箱
signCount	int	更新后的签名计数

# 自动从 DB 查凭据
curl -X POST -H 'content-type: application/json' \
  -d '{"email":"user@example.com"}' \
  https://YOUR_HOST/api/v1/passkey/login

# 手动传入凭据
curl -X POST -H 'content-type: application/json' \
  -d '{"email":"user@example.com","credentialId":"YDnF...","privateJwk":{"kty":"EC","crv":"P-256","x":"...","y":"...","d":"..."}}' \
  https://YOUR_HOST/api/v1/passkey/login

POST /api/v1/passkey/lookup · 按邮箱查 Passkey

POST/api/v1/passkey/lookup

查询已开通的 Passkey 凭据信息 (不含私钥). 默认开放查询 (仅 IP 限速), admin 可配 passkey_lookup_token 启用强保护.

请求	类型	说明
email	string	邮箱 (必填)
key	string?	查询密钥 (仅当 admin 配了 passkey_lookup_token 时必填)

响应	类型	说明
ok / reason	bool/string	ok \| not-found \| unauthorized \| invalid-email \| rate-limited \| server-error
credential_id	string	凭据 ID
factor_id	string?	MFA factor ID
rp_id	string	RP ID (openai.com)
user_handle	string	用户句柄
sign_count	int	签名计数
email / account_id / plan_type	string?	账号信息
created_at / updated_at	string	时间戳

curl -X POST -H 'content-type: application/json' \
  -d '{"email":"user@example.com"}' \
  https://YOUR_HOST/api/v1/passkey/lookup

POST /api/v1/rights/preview · 维权申诉预览 (账户状态查询)

POST/api/v1/rights/preview(旧别名 /api/v1/deactivate/preview)

给定 ChatGPT access_token，返回账户 email / plan / 订阅状态 / 是否已注销 / JWT 过期时间。不产生任何状态变更，仅用于二次确认。内部实现：本地解 JWT + 调 ChatGPT /backend-api/accounts/check/v4-2023-04-27。

鉴权	说明
Authorization: Bearer <VALUE>	三选一：CDK（走 quota / daily / expires / scope=deactivate，成功业务后扣 1 次；失败可退次数） / deactivate_service_token（内部页面调用） / deactivate_business_token（外部商务对接）
三者都为空	后台若未配置任一 token，则接口开放（仍受限速 / 功能开关 / 手机号 / 邮箱白名单约束）

请求	类型	说明
token	string	ChatGPT accessToken JWT，必填，`eyJ...` 开头
cookie	string?	可选 `chatgpt.com` Cookie 头（例如 `__Secure-next-auth.session-token=xxx`）
sessionToken	string?	可选 next-auth session token；未提供 cookie 时会自动拼装成 Cookie 头
deviceId	string?	可选 `oai-device-id`；未提供则自动生成 UUID

响应	类型	说明
ok	bool	业务是否成功（含 already-deactivated 也是 true）
reason	string	ok \| already-deactivated \| empty-token \| invalid-token-format \| jwt-expired \| token-401 \| http-error \| fetch-error \| bad-request \| server-error \| unauthorized \| feature-disabled \| rate-limited \| cdk-busy \| quota-exhausted \| daily-exhausted \| expired \| disabled \| scope-denied \| not-yet-started \| account-not-phone \| email-not-whitelisted
message	string?	面向终端用户的中文提示（失败时附带）
email / account_id / plan_type	string?	账号信息（本地 JWT 解出 + `/accounts/check` 兜底）
has_active_subscription	bool?	是否有活跃订阅
subscription_expires_at	string?	订阅到期时间 (ISO)
already_deactivated	bool	该账户是否已经处于注销状态（此时无需再发起 execute）
jwt_exp_ms / jwt_exp_in_sec	number	JWT 过期时间戳 (ms) / 剩余秒数（负数=已过期）
status	number?	OpenAI 返回的原始 HTTP 状态码（无返回时 null）
error	string?	失败时的底层错误信息（截断到 500 字节）
request_id / duration_ms	string/number	请求追踪 ID 和耗时

curl -X POST https://YOUR_HOST/api/v1/rights/preview \
  -H 'authorization: Bearer <CDK 或 SERVICE_TOKEN 或 BUSINESS_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ..."}'

POST /api/v1/rights/execute · 维权申诉正式提交 (账户注销)

POST/api/v1/rights/execute(旧别名 /api/v1/deactivate/execute)

正式提交维权申诉，调 ChatGPT /backend-api/accounts/deactivate。不可撤回，会立即使账号进入注销状态。内部含 500 兜底验证：OpenAI 常返 500 但账户实际已删，服务端会回读 /accounts/check 获取 401 / is_deactivated 兜底判定；最长约 20 秒（受后台 verify_attempts × verify_interval 影响）。

鉴权	说明
Authorization	同 `/api/v1/rights/preview`；CDK 若命中会占用一次并发锁（同一 CDK 不允许并行），业务成功扣次数、失败按 `cdk_strict_mode` 决定是否退回

请求	类型	说明
token	string	ChatGPT accessToken JWT，必填
cookie	string?	可选，同 preview
sessionToken	string?	可选，同 preview
deviceId	string?	可选，同 preview

响应	类型	说明
ok	bool	业务是否成功（含 already-deactivated 也是 true）
reason	string	ok \| already-deactivated \| empty-token \| invalid-token-format \| jwt-expired \| token-401 \| account-id-missing \| deactivate-failed \| verify-still-active \| fetch-error \| http-error \| server-error \| bad-request \| rate-limited \| unauthorized \| feature-disabled \| cdk-busy \| quota-exhausted \| daily-exhausted \| expired \| disabled \| scope-denied \| not-yet-started \| account-not-phone \| email-not-whitelisted
message	string?	面向终端用户的中文提示（失败时附带）
email / account_id / plan_type	string?	账号信息
http_status	number?	OpenAI `/deactivate` 返回的原始 HTTP 状态码
verification	string	`success`（HTTP 2xx 直接成功） / `deactivated`（回读账户已注销） / `auth_expired`（回读返回 401 = 账户已注销 + token 已吊销） / `still_active`（回读仍然活跃 = 提交失败） / 空串（未走到验证阶段）
error	string?	失败时的底层错误信息
request_id / duration_ms	string/number	请求追踪 ID 和耗时（含兜底验证）

⚠ 操作不可撤回：一旦返回 ok:true（含 verification=success / deactivated / auth_expired），账户即已进入 OpenAI 注销流程，无法回滚。建议前端在正式提交前进行明确的二次确认。

curl -X POST https://YOUR_HOST/api/v1/rights/execute \
  -H 'authorization: Bearer <CDK 或 SERVICE_TOKEN 或 BUSINESS_TOKEN>' \
  -H 'content-type: application/json' \
  --max-time 60 \
  -d '{"token":"eyJ..."}'

GET /api/v1/channels

GET/api/v1/channels

渠道存活榜单 (公开只读, 匿名可访问)。返回各渠道账号的订阅存活状态。严格脱敏 — 不含任何 token / refresh_token / client_id / account_id / email。数据由后台定时刷新。

响应	类型	说明
ok	bool	是否成功
last_refreshed_at	string?	最后一次刷新时间 (ISO)
channels	array	渠道列表 (见下)
channels[].label	string	渠道备注名
channels[].status	string	alive_paid \| alive_free \| expiring \| dead \| error \| pending
channels[].plan_type	string?	套餐 (free/plus/pro/team)
channels[].active_start / expires_at	string?	开通 / 截止时间
channels[].days_left	number?	剩余天数
channels[].will_renew / is_delinquent	bool	是否续费 / 是否欠费
channels[].purchase_origin_platform	string?	渠道来源 (chatgpt_web/ios/android)

curl https://YOUR_HOST/api/v1/channels

POST /api/v1/email-rebind · 换绑邮箱

POST/api/v1/email-rebind

密码 + TOTP 重登后换绑 ChatGPT 邮箱。页面 /email-rebind。导入支持 账户----密码----2FA 或空格分隔。代理留空=本机直连。

请求	类型	说明
email / password / totp	string	旧邮箱、密码、2FA secret 或 6 位码
newEmail	string	新邮箱
line	string?	整行导入，可带第四列新邮箱
code	string?	已有新邮箱验证码则一次做完；否则返回 `awaiting_code`
proxy	string?	空=直连

curl -X POST https://YOUR_HOST/api/v1/email-rebind -H "Content-Type: application/json" -d "{\"email\":\"old@x.com\",\"password\":\"***\",\"totp\":\"BASE32SECRET\",\"newEmail\":\"new@x.com\"}"

SSE：POST /api/v1/email-rebind/stream，收到 need_code 后 POST /api/v1/email-rebind/code {request_id,code}。

GET /api/v1/stats

GET/api/v1/stats

全局统计 (需鉴权)。

响应	说明
total / eligible / not_eligible / ac_invalid / errors	累计计数
success_rate	0~1
uptime_sec / since_sec	运行/统计时长

GET /healthz

GET/healthz

探活,无需鉴权。

{"ok":true,"service":"ac-checker","brand":"Nerver","time":1780024498,"promo_id":"plus-1-month-free","stats":{"total":1234,"eligible":800}}

通用说明

鉴权	设置 AUTH_TOKEN 后, /api/v1/* 需带 Authorization: Bearer xxx 或 ?key=xxx
限流	单 IP 60 次/分钟, 超限 429 + retry-after
CORS	默认 *, 可通过 CORS_ORIGIN 限制
超时	OpenAI 30s, IMAP 60s
批量上限	/api/v1/check 最多 50 token
错误格式	{"ok":false,"reason":"...","error":"...","message":"..."}
message 字段	失败响应附带的中文友好提示 (面向终端用户)。客户端建议优先显示 `message`, 回退到 `reason`。`reason` 字段不变, 完全向后兼容。
机器可读	GET /api/v1/docs 返回完整 JSON 契约

API 文档

POST /api/v1/check · AC 资格预检

POST /api/v1/subscription

POST /api/v1/session/refresh

POST /api/v1/checkout

POST /api/v1/pix · PIX 巴西 (长链)

POST /api/v1/pix-short · PIX 内部支付

📑 错误码与重试策略

POST /api/v1/pix-short/stream · PIX 内部支付 SSE 实时进度

POST /api/v1/upi

POST /api/v1/upi/stream

POST /api/v1/gopay

POST /api/v1/gopay/stream

GET /api/v1/gopay/qr.png

POST /api/v1/gcash-check · GCash 资格硬查

POST /api/v1/gcash · GCash 出码

POST /api/v1/gcash/stream

POST /api/v1/ph-link · PH Link 菲律宾提链

POST /api/v1/ph-link/stream

POST /api/v1/ideal · 测试通道

POST /api/v1/ideal/stream

GET /api/v1/ideal/qr.png · iDEAL QR 图片

POST /api/v1/blik · BLIK 波兰支付

POST /api/v1/blik/stream

POST /api/v1/sp-pay · SP 支付

POST /api/v1/sp-pay/stream

POST /api/v1/paypal · PayPal 授权链接（通用引擎）

POST /api/v1/paypal-vip · PayPal VIP 🇹🇷 土耳其专用高成功率通道

POST /api/v1/paypal-uk · PayPal UK 🇬🇧 英国定向提链

POST /api/v1/kakao-pay · 韩国 KakaoPay (二维码)

POST /api/v1/kakao-pay/stream

POST /api/v1/naver-pay · 韩国 NaverPay

POST /api/v1/naver-pay/stream

POST /api/v1/kr-checkout · [兼容] 旧统一 KR 端点

POST /api/v1/inbox

POST /api/v1/inbox/message

POST /api/v1/inbox/folders

POST /api/v1/totp/enable · ChatGPT 2FA 开通

POST /api/v1/totp/code · 本地 OTP 生成

POST /api/v1/totp/lookup · 按邮箱查实时 OTP

POST /api/v1/passkey/enable · Passkey 开通

POST /api/v1/passkey/login · Passkey 登录取 Cookies

POST /api/v1/passkey/lookup · 按邮箱查 Passkey

POST /api/v1/rights/preview · 维权申诉预览 (账户状态查询)

POST /api/v1/rights/execute · 维权申诉正式提交 (账户注销)

GET /api/v1/channels

POST /api/v1/email-rebind · 换绑邮箱

GET /api/v1/stats

GET /healthz

通用说明