Partner API · UPI 仅提链

UPI 提链 API 对接文档

对应客户页 /open/upi · UPI 印度仅提链。仅 product=extract + channel=upi（出 UPI 支付链接）。 不经过荷兰号池 / extract_pay。面向 客户后端服务 用 API Key 对接。

Base: https://open.756257.xyz 正确域名: open.756257.xyz 对接位置: 后端服务鉴权: API Key 成功状态: link_ready 检测中…

对接方式鉴权提交轮询取消状态错误码示例注意

0. 对接方式

请在客户自己的后端服务调用本 API，例如 PHP / Java / Node / Python 服务端、定时任务或服务器脚本。

正确 Base URL 是 https://open.756257.xyz，不要使用 https://api.756257.xyz。
不建议浏览器前端直接调用。API Key 放在前端会暴露，且跨域请求需要额外 CORS 白名单。
客户前端页面应先请求客户自己的后端，再由客户后端请求本 API。
你需要提供给客户：Base URL、API Key、提交接口、查询接口和请求参数格式。

1. 鉴权

API Key 由站长在服务器配置（环境变量 OPEN_EXTRACT_API_KEY），请私下索取，不要写在公开页面。

请求头（二选一）

X-Open-Api-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

也可放在 JSON 字段 api_key（不推荐，易进日志）。

已配置

是 — 可调用 POST

限流

同一 Key 约 120 次 / 10 分钟（提交）。超限返回 429。

2. 提交提链

POST https://open.756257.xyz/api/open/v1/extract

Body（JSON）

字段	必填	说明
`cdk`	是	提链卡密；普通卡批量时一行一个；合并多次卡可一张对应多条 session
`token`	是	Session / AccessToken；支持多条
`channel`	否	`upi`（默认，可省略）。当前客户对接以 UPI 为准
`email`	否	辅助邮箱；一般可从 token 解析
`product`	忽略	接口强制为 extract；传 extract_pay 会被拒绝

成功响应（节选）

{
  "ok": true,
  "count": 1,
  "order": {
    "id": "订单ID",
    "view_key": "查询密钥（务必保存）",
    "status": "queued",
    "product": "extract",
    "channel": "upi",
    "progress": 5,
    "status_label": "排队中"
  },
  "orders": [ /* 批量时多条 */ ],
  "message": "已提交，处理中"
}

也可用 POST /api/open/redeem + 同一 API Key，但 product 必须为 extract。

3. 轮询订单

GET https://open.756257.xyz/api/open/v1/extract/order/<order_id>?k=<view_key>

等价于 GET /api/open/order/<id>?k=...。无 view_key 时只返回粗粒度状态，拿不到支付链接。

成功出链时字段

字段	说明
`status`	`link_ready` 表示提链成功
`pay_url` / `pix_url`	支付链接（UPI/PIX 通用字段名）
`pix_emv`	仅 PIX 可能有复制码
`email`	脱敏邮箱

建议间隔 2–5 秒轮询，直到 link_ready 或 failed。

取消提链 / 停止

排队中或提链处理中可取消；成功后会退回 CDK。已出链（link_ready）不可取消。

POST https://open.756257.xyz/api/open/v1/extract/order/<order_id>/cancel
Content-Type: application/json
X-Open-Api-Key: YOUR_API_KEY

{"k":"提交时返回的 view_key"}

也可用 /stop 路径，效果相同。鉴权：API Key + view_key，或 body 里提供与订单一致的 cdk。

4. 订单状态

status	含义	下一步
`queued`	排队	继续轮询
`extracting`	提链处理中	继续轮询
`link_ready`	已出链	读取 pay_url
`failed`	失败	看 message；卡密通常已退回
`pool_waiting`	号池等待	纯提链 API 不应出现（属 extract_pay）

5. 常见 HTTP 状态

HTTP	场景
200	业务成功（仍看 body.ok）
400	参数/Session/卡密格式问题
401	API Key 无效或缺失
403	通道关闭，或试图用 Key 走 extract_pay
404	订单不存在
429	提交过频
503	服务器未配置 OPEN_EXTRACT_API_KEY

其它接口（无需 Key）

POST /api/open/cdk-status — 查卡密状态 {"cdk":"..."}
GET /api/open/channels — 通道是否开放
GET /api/open/stats?product=extract&channel=upi — 成功率统计
GET /api/health — 健康检查

6. 调用示例

curl

curl -sS -X POST "https://open.756257.xyz/api/open/v1/extract" \
  -H "Content-Type: application/json" \
  -H "X-Open-Api-Key: YOUR_API_KEY" \
  -d '{"cdk":"你的提链卡密","token":"你的Session","channel":"upi"}'

# 轮询
curl -sS "https://open.756257.xyz/api/open/v1/extract/order/订单ID?k=view_key"

Python

import time, requests

BASE = "https://open.756257.xyz"
KEY = "YOUR_API_KEY"

r = requests.post(
    f"{BASE}/api/open/v1/extract",
    headers={"X-Open-Api-Key": KEY},
    json={"cdk": "你的提链卡密", "token": "你的Session", "channel": "upi"},
    timeout=30,
)
r.raise_for_status()
data = r.json()
assert data.get("ok"), data
order = data["order"]
oid, vk = order["id"], order["view_key"]

while True:
    q = requests.get(
        f"{BASE}/api/open/v1/extract/order/{oid}",
        params={"k": vk},
        timeout=20,
    ).json()
    o = q.get("order") or {}
    st = o.get("status")
    print(st, o.get("message"))
    if st == "link_ready":
        print("pay_url:", o.get("pay_url") or o.get("pix_url"))
        break
    if st == "failed":
        raise SystemExit(o.get("message") or "failed")
    time.sleep(3)

7. 注意

本 API 只做提链，不会推阿三、不进号池开通流程。
机器对接请使用客户后端服务 + API Key；不要把 API Key 写进网页前端代码。
浏览器前端跨域直连默认不可用；如确需前端直连，需要单独配置客户域名 CORS 白名单。
网页提交仍走浏览器校验（page_token）；后端 API 对接不需要 page_token。
view_key 等同订单隐私凭证，勿泄露。
普通单次 CDK 批量时 cdk 与 token 条数须一致；合并多次卡可只传一张 cdk 对应多条 Session。
Key 轮换：改服务器 .env 中 OPEN_EXTRACT_API_KEY 后重启 pix-open。

机器可读：GET /api/open/v1/extract