接口	用途
`POST /api/register`	注册并返回 `api_key`（只返回一次）
`POST /api/auth/login`	邮箱密码登录
`POST /api/dashboard/rotate`	重置 API Key（旧 Key 立即失效）

curl -X POST 'https://your-domain.example/api/register' \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"至少8位","name":"商户名"}'

注册受 IP 限流保护；注册后拿到的 api_key 用于所有 /api/v1/* 接口的 Authorization: Bearer。

查询可充值套餐

返回可用套餐的标识、名称、默认国家、默认币种与参考价格，无需请求参数。

curl 'https://your-domain.example/api/v1/plans'

响应示例 200 OK

{
  "plans": [
    {
      "id": "plus",
      "label": "Plus",
      "plan_name": "chatgptplusplan",
      "default_country": "PH",
      "default_currency": "PHP",
      "list_price": "USD 20 / 月"
    }
  ]
}

list_price 为参考价格文本；实际支付金额以任务结果中的 amount_minor 与 currency 为准。

POST/api/v1/rechargesAPI Key

提交充值任务

提交套餐、账号和卡片信息。成功接收后返回任务号，充值在后台继续处理。

HTTP 202 表示任务已接收，不代表充值成功。请保存 id，通过查询接口确认最终状态。

请求参数

字段	类型	要求	说明
`plan`	string	必填	套餐标识：plus、go、pro100、pro200 或 pro500。有优惠也不会变。
`session`	string	必填	账号 Session 内容，以字符串传入；JSON 内容需序列化。最大 128 KiB。
`card.number`	string	必填	完整卡号，去除非数字字符后须为 12–19 位。
`card.exp_month`	string	必填	有效期月份，如 09。
`card.exp_year`	string	必填	有效期年份，推荐四位，如 2028。
`card.cvc`	string	必填	3 或 4 位安全码。
`billing.region`	string	必填	充值区域：PH / CL / EG / US，决定价格地区。必须与代理出口国家一致。
`promo`	string	必填	优惠策略：none（强制原价）/ auto（有优惠打折）/ require（必须半价，没有则不充）。
`card.name`	string	选填	持卡人姓名。
`billing.country`	string	选填	不传 region 时才用；传 region 时自动取该区域国家。
`billing.*(地址)`	string	选填	账单地址由系统按美国地址自动填充，一般不用传。
`proxy`	string	选填	自带出口代理：http://user:pass@host:port、host:port、host:port:user:pass。代理出口国家必须与 billing.region 一致。
`skip_precheck`	boolean	选填	默认 false，提交前先查会员，有会员直接 409。设 true 跳过（执行阶段仍会校验）。
`Idempotency-Key`	header	选填	幂等键，放请求头；相同 Key 返回同一单，防止重复扣款。

账单地址无需填写：只传 billing.region 即可，服务端会按区域从地址池自动补全账单地址；实际使用的内容以提交响应中的 billing 为准。

避免重复创建

可选请求头 Idempotency-Key 用于标识同一笔业务请求。重试同一笔请求时复用该值；命中已有任务时返回 HTTP 200，并将 created 设为 false。

curl -X POST 'https://your-domain.example/api/v1/recharges' \
  -H 'Authorization: Bearer <你的 API Key>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-20261029-001' \
  -d '{
  "plan": "plus",
  "promo": "auto",
  "session": "{\"accessToken\":\"<账号访问令牌>\"}",
  "card": {
    "number": "4242424242424242",
    "exp_month": "09",
    "exp_year": "2028",
    "cvc": "123",
    "name": "Example User"
  },
  "billing": {
    "region": "PH"
  }
}'

卡号、姓名和地址均为演示数据；请替换为本次充值实际使用的信息。

响应示例 202 Accepted

{
  "id": "rc_example",
  "status": "queued",
  "created": true,
  "plan": "plus",
  "billing": {
    "country": "PH",
    "state": "Metro Manila",
    "city": "Manila",
    "postal_code": "1000",
    "line1": "123 Example Street",
    "name": "Example User"
  },
  "created_at": "2026-10-29T08:00:00.000Z"
}

GET/api/v1/recharges/{id}API Key

查询充值结果

将路径中的 {id} 替换为任务号。只能查询当前 API Key 对应账号的任务。

curl 'https://your-domain.example/api/v1/recharges/rc_example' \
  -H 'Authorization: Bearer <你的 API Key>'

响应示例 200 OK

{
  "id": "rc_c2c4c855d2b112f1292b3606",
  "plan": "plus",
  "status": "succeeded",
  "error_code": null,
  "error_message": "",
  "card_last4": "0640",
  "card_brand": "mastercard",
  "amount_minor": "49107",
  "currency": "PHP",
  "protocol_type": "oaics",
  "precheck_status": "free",
  "promo_policy": "require",
  "membership_status": "verified",
  "renewal_status": "cancelled",
  "renewal_error": null,
  "post_payment_error": null,
  "session_rotated": true,
  "session": "<最新 Session JSON 字符串>",
  "created_at": "2026-10-30T15:30:11.000Z",
  "started_at": "2026-10-30T15:30:12.000Z",
  "finished_at": "2026-10-30T15:30:41.000Z"
}

status任务状态：queued / running / succeeded / failed_unpaid / unknown / void。含义见下方状态说明。

error_code / error_message任务错误代码与可读说明；成功时为 null 和空字符串。取消续费、会员查询失败不会写进这里。

amount_minor / currency实际扣款金额（最小货币单位，字符串）与币种；未扣款时为 null。

promo_policy本次使用的优惠策略：none / auto / require。

membership_status会员确认结果：verified（已确认到账）/ unverified（支付成功但没查到，仍算成功）/ unknown。

renewal_status取消自动续费结果：cancelled / failed / pending / unknown。

renewal_error取消失败时的原因，如 http_status=503 error_kind=... attempts=3。

post_payment_error支付后其他步骤的错误（不影响成功状态）。

session_rotatedtrue 表示充值过程中 token 被刷新过。

session最新 Session。为 session_rotated: true 时务必用它替换本地保存的，否则下次会报 session 失效。

card_last4 / card_brand卡片后四位与品牌。

protocol_type / precheck_status协议类型（oaics / cs_live）与提交时的会员预检结论。

created_at / started_at / finished_at创建、开始、结束时间（ISO 8601），未发生时为 null。

POST/api/v1/recharges/{id}/retryAPI Key

重试失败任务

用原任务的参数（Session / 卡 / 套餐 / 地区 / 优惠策略 / 代理）重新提交一张新任务，返回新任务号。

只有明确未扣款的任务能重试。状态为 unknown 的任务可能已经扣过钱，重试会重复扣款，接口会拒绝并提示先查会员状态。

可重试的状态

原任务状态	能否重试	说明
`failed_unpaid`	✅	明确未扣款，直接重试即可
`previewed`	✅	只做了税费探测，未提交支付
`void`	✅	已作废
`unknown`	❌	可能已扣款，先查会员状态
`succeeded`	❌	已成功，无需重试
`queued` / `running`	❌	正在执行

curl -X POST 'https://your-domain.example/api/v1/recharges/rc_xxx/retry' \
  -H 'Authorization: Bearer <你的 API Key>'

响应 202 / 409

202{"id":"rc_new","status":"queued","created":true,"retry_of":"rc_old"}

not_retryable原任务状态不允许重试（unknown 表示可能已扣款，要先用同一 Session 查会员）

already_succeeded该账号在原任务之后已经充值成功过，无需再试

member_active账号已有生效会员

account_busy该账号已有进行中的任务

no_proxy该地区没有可用代理

rate_limited / merchant_busy触及限额，稍后重试

网络波动自动重试支付提交前遇到网络失败会自动重新排队重试（最多 2 次），无需调用方处理；支付提交后的网络中断不自动重试，会判成 unknown 并告警。

GET/api/v1/rechargesAPI Key

查询充值列表

按创建时间从新到旧返回当前账号的任务，可按状态筛选并使用时间游标翻页。

参数	要求	说明
`limit`	选填	每页数量，默认 50，范围 1–200，建议传入整数。
`before`	选填	ISO 8601 时间；返回创建时间早于该时间的任务。
`status`	选填	任务状态，如 `queued` 或 `succeeded`；未提供时查询全部状态。

curl --get 'https://your-domain.example/api/v1/recharges' \
  -H 'Authorization: Bearer <你的 API Key>' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'status=queued' \
  --data-urlencode 'before=2026-10-29T09:00:00.000Z'

响应示例 200 OK

{
  "items": [
    {
      "id": "rc_example",
      "plan": "plus",
      "status": "queued",
      "error_code": null,
      "error_message": "",
      "card_last4": "4242",
      "card_brand": "visa",
      "amount_minor": null,
      "currency": null,
      "protocol_type": null,
      "precheck_status": null,
      "session_rotated": false,
      "membership_status": null,
      "renewal_status": null,
      "promo_policy": "auto",
      "created_at": "2026-10-29T08:00:00.000Z",
      "finished_at": null,
      "attempts": 0
    }
  ],
  "next_before": "2026-10-29T08:00:00.000Z"
}

将响应中的 next_before 作为下一页的 before，并保持原筛选条件。列表非空时会返回游标；继续请求，直至 items 为空且 next_before 为 null。

POST/api/v1/accounts/statusAPI Key

查询账号会员状态

只读查询账号当前会员状态，不建单、不扣款、不改订阅。可用于充值前预检或批量核对账号。

请求参数

字段	类型	要求	说明
`session`	string	必填	账号 Session 内容，以字符串传入。
`country`	string	选填	两位国家代码，默认 PH。

curl -X POST 'https://your-domain.example/api/v1/accounts/status' \
  -H 'Authorization: Bearer <你的 API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"session":"<账号 Session JSON 字符串>"}'

statusactive（有会员）/ free（无会员）/ unknown（查询失败）。

plan / plan_raw套餐名与原始标识。

expires_at / renews_at到期与续费时间。

will_renew / is_delinquent是否自动续费、是否欠费。

POST/api/v1/accounts/plansAPI Key

查询账号可购买的套餐

只读查询该账号在某区域能买哪些套餐、实付价格以及可用优惠。已有会员的账号全部标记为不可购买。

请求参数

字段	类型	要求	说明
`session`	string	必填	账号 Session 内容，以字符串传入。
`region`	string	选填	价格地区 PH / CL / EG / US，默认 PH。

curl -X POST 'https://your-domain.example/api/v1/accounts/plans' \
  -H 'Authorization: Bearer <你的 API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"session":"<账号 Session JSON 字符串>","region":"PH"}'

plans[].plan套餐标识：plus / go / pro100 / pro200 / pro500。

plans[].available该账号能否购买；已有会员时全部 false。

plans[].price实付价（美国账单地址免税后，实际会扣的金额）。

plans[].price_list含税标价，仅作对比。

plans[].price_with_promo有优惠时的折后价，没有则为 null。

plans[].promo该账号对这个套餐可用的优惠活动（id / percent / title）。

has_active_membership / can_buy是否已有会员、整体能否购买。

公开版本：POST /api/web/accounts/plans（无需 API Key），参数与返回同上。

POST/api/v1/accounts/invoicesAPI Key

查询账单（交易记录 / 发票）

查询账号订阅的交易记录，含每笔扣费的状态、金额、发票页和 PDF 下载链接。只读，不建单、不扣款。

请求参数

字段	类型	要求	说明
`session`	string	必填	账号 Session 内容，以字符串传入。
`limit`	number	选填	返回条数，默认 20，范围 1–100。
`starting_after`	string	选填	上一页最后一条发票 id，用于翻页。

curl -X POST 'https://your-domain.example/api/v1/accounts/invoices' \
  -H 'Authorization: Bearer <你的 API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"session":"<账号 Session JSON 字符串>","limit":20}'

网页 /billing「账号信息查询」会并行调用 status、plans 与 invoices（无需 API Key）。

number / status发票编号与状态：paid 已支付 / open 待付款 / void 作废。

amount_due / amount_paid / currency应付、已付金额（最小货币单位）与币种。

created_at / period_start / period_end开票时间与计费周期。

hosted_invoice_url发票页（Stripe 托管），可直接打开查看。

invoice_pdf账单（发票）PDF 下载链接。

receipt_url收据 PDF 下载链接（仅已支付发票有；打开会 302 到 PDF）。

membership_status任务详情：会员确认状态，verified / unverified（支付成功但没查到，仍算成功）/ unknown。

renewal_status / renewal_error任务详情：取消自动续费的结果与失败原因。

post_payment_error任务详情：支付后其他步骤的错误（不影响成功状态）。

has_more是否还有更多记录；用最后一条 id 作为 starting_after 翻页。

代理国家必须与充值地区一致

这是上游的硬性约束，不一致会直接失败。

例如选了 region=CL（智利）但代理出口是菲律宾，上游会返回：

{"detail":"Billing country must match request country."}

billing.region	代理出口必须是
`PH`	菲律宾
`CL`	智利
`EG`	埃及
`US`	美国

自己传 proxy传什么就是什么，系统不校验国家；出口国错了要执行阶段才失败（failed_unpaid，不扣款）。

不传 proxy系统按 region 找对应国家的代理；找不到直接 409 no_proxy，不会建单。

确认出口国家用该代理访问 https://ipwho.is/，看返回的 country_code。

POST/api/v1/subscriptions/cancelAPI Key

取消订阅（关闭自动续费）

提交账号 Session，关闭其当前订阅的自动续费。订阅保留到当前账期结束，不会立即取消会员资格。接收后返回任务号，实际执行在后台完成。

HTTP 202 表示任务已接收。请保存 id，通过查询接口确认最终结果。

请求参数

字段	类型	要求	说明
`session`	string	必填	账号 Session 内容，以字符串传入。

curl -X POST 'https://your-domain.example/api/v1/subscriptions/cancel' \
  -H 'Authorization: Bearer <你的 API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"session":"<账号 Session JSON 字符串>"}'

查询结果

curl 'https://your-domain.example/api/v1/subscriptions/cancel/cc_example' \
  -H 'Authorization: Bearer <你的 API Key>'

结果字段 200 OK

statussucceeded 已关闭续费，failed 取消失败。

result.cancelled是否本次执行了关闭动作。

result.already_cancelled是否此前已关闭。

result.plan_type / active_until当前订阅套餐与账期截止时间。

同一账号同时只能有一个进行中的取消任务，重复提交返回 account_busy。

TASK STATUS

理解任务状态

以任务状态判断充值结果，避免将“已接收”误认为“已开通”。

排队中queued

任务已接收，等待处理。

执行中running

任务正在处理，请等待结果。

已开通succeeded

充值成功，会员已开通。

失败（未扣款）failed_unpaid

未完成扣款，查看错误后再提交。

待确认unknown

支付结果尚未确认，请先核对，避免重复提交。

预览通过previewed

已完成预览，尚未扣款或开通会员。

公开接口（无需 API Key）

网页充值页使用的接口。需要先登录（Cookie 鉴权），未登录调用返回 401 login_required；参数与带 API Key 的版本一致。

接口	用途
`POST /api/web/recharges`	提交充值
`POST /api/web/accounts/plans`	查询账号可买套餐与价格
`POST /api/web/accounts/status`	查询账号订阅信息
`POST /api/web/invoices`	查询账单与收据
`GET /api/web/recharges?id=`	查询单条任务结果（网页轮询用）

TASK ERROR CODE

任务错误码

任务失败时 error_code 给出确切原因。按这个表决定是否重试、换卡还是换号。

状态为 unknown 的任务一律不要自动重试：先用同一份 session 调 /api/v1/accounts/status 查会员，查到已是目标套餐按成功处理，查不到再人工核实。

error_code	任务状态	含义与处理
`CARD_REJECTED`	failed_unpaid	卡未通过 OpenAI 支付校验，换一张卡重试（同账号换卡通常可成功）
`CARD_DECLINED`	failed_unpaid	发卡行拒付，换卡
`THREE_DS_REQUIRED`	failed_unpaid	该卡需要 3DS 验证，换一张不需要 3DS 的卡
`PAYMENT_BLOCKED`	failed_unpaid	被风控拦截，换卡或换出口网络
`PLAN_ALREADY_ACTIVE`	failed_unpaid	账号已是该套餐，无需充值
`NOT_ELIGIBLE`	failed_unpaid	账号不满足购买条件，换号
`ACCOUNT_NOT_ELIGIBLE`	failed_unpaid	账号已有付费订阅或身份信息缺失，换号
`RATE_LIMITED`	failed_unpaid	上游限流，稍后重试
`CHECKOUT_EXPIRED`	failed_unpaid	结账单过期，重新提交
`AMOUNT_CHANGED`	failed_unpaid	应付金额与 expected_amount_minor 不一致，确认后重提
`TAX_NOT_ZERO`	failed_unpaid	订单含税，已在支付前停止，未扣款
`TAX_UNVERIFIED`	failed_unpaid	税费响应缺少明确税额，已在支付前停止
`PROMO_REQUIRED`	failed_unpaid	要求必须优惠但没有可用优惠，未扣款
`SESSION_INVALID`	failed_unpaid	Session 刷新失败或无效，让用户重新提供
`SENTINEL_FAILED`	failed_unpaid	上游安全校验失败，重试
`CHECKOUT_CREATE_FAILED`	failed_unpaid	建结账单失败，重试或换地区
`CHECKOUT_CONFIRM_FAILED`	failed_unpaid	结账确认失败，未产生支付单
`NETWORK_ERROR`	failed_unpaid	网络异常，未提交支付，可直接重试
`PAYMENT_CONFIRM_FAILED`	unknown	支付提交后结果不明，不要重试，先查会员状态
`PAYMENT_CONFIRMATION_PENDING`	unknown	支付后网络中断，结果未确认，先查会员状态
`PROTOCOL_INCOMPLETE`	unknown	支付已提交但结果不明，先查会员状态
`PROTOCOL_CRASH`	unknown	协议进程异常退出，查会员状态后再决定

LIMITS

调用限额

项	默认	超出时
每分钟提交数	20	`429 rate_limited`
同时进行任务数	2	`429 merchant_busy`
同账号并发	1	`409 account_busy`（响应带 `active_id`）
单任务最长耗时	5 分钟	转 `unknown` 进入人工核实

限额按商户可调，需要提高请联系管理员。

ERROR HANDLING

处理请求错误

接口拒绝请求时返回对应 HTTP 状态码和 error 字段；部分响应另含 message 或 detail。

HTTP	错误标识	建议处理
`400`	`invalid_json / invalid_request`	请求格式或字段不合法。按 detail 提示检查后再提交。
`401`	`unauthorized`	API Key 缺失、无效或对应账号已停用。
`403`	`merchant_disabled`	创建任务时发现账号已停用，请联系管理员。
`404`	`not_found`	任务不存在，或不属于当前 API Key 对应的账号。
`409`	`account_busy`	账号已有进行中任务，使用返回的 active_id 查询该任务。
`409`	`member_active`	账号已有生效中的会员，不能重复充值。
`409`	`no_proxy`	所选区域没有配置对应国家的出口代理，先在后台代理配置里添加。
`failed_unpaid`	`PROMO_REQUIRED`	任务级错误：promo=require 但账号没有可用优惠，未建单、未扣款。
`failed_unpaid`	`PROXY_COUNTRY_MISMATCH`	任务级错误：代理出口国家与充值区域不一致，未扣款。
`429`	`rate_limited / merchant_busy`	提交频率或进行中任务数达到账号上限，请稍后重试。