礼品卡发行 API

1. 1

   打开发卡令牌标签页

   登录后进入「礼品卡与直充」页面，切到「发卡令牌」标签页，点「新建发卡令牌」。

2. 2

   填写名称和可选限制

   名称最多 60 个字符，比如「发卡平台」。IP 白名单和每日额度上限都是可选的，留空表示不限。平台不设默认值，由你自己决定。

3. 3

   立即保存令牌

   令牌以 wkt_ 开头，明文只显示这一次。丢失后只能吊销再新建。创建时会发站内通知和邮件。

Base URL

https://wokey.ai/api/issuer/v1

鉴权

每个请求都带 Authorization: Bearer wkt_…。网页登录会话不能调用这组接口，发卡令牌也不能调用其他任何接口。

请求与响应

请求体和响应都是 JSON。金额在响应里是保留两位小数的字符串（如 "10.00"），时间是 ISO 8601 UTC。

curl -X POST https://wokey.ai/api/issuer/v1/codes \
  -H "Authorization: Bearer wkt_YOUR_ISSUING_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20261017-0001" \
  -d '{ "sourceType": "provider", "amountUsd": 10, "count": 1, "label": "order-20261017-0001" }'

{
  "batch": {
    "id": "icb_…",
    "sourceType": "provider",
    "amountUsd": "10.00",
    "count": 1,
    "totalUsd": "10.00",
    "label": "order-20261017-0001",
    "createdAt": "2026-10-17T08:00:00.000Z"
  },
  "replayed": false,
  "codes": [
    {
      "id": "ic_…",
      "batchId": "icb_…",
      "kind": "code",
      "sourceType": "provider",
      "amountUsd": "10.00",
      "codeHint": "7K2M",
      "status": "active",
      "label": "order-20261017-0001",
      "createdAt": "2026-10-17T08:00:00.000Z",
      "redeemedAt": null,
      "redeemedByMaskedEmail": null,
      "voidRequestedAt": null,
      "voidEffectiveAt": null,
      "voidedAt": null,
      "frozenAt": null,
      "code": "WK-4F9Q-T3XA-8HRB-7K2M",
      "redeemUrl": "https://wokey.ai/redeem#WK-4F9Q-T3XA-8HRB-7K2M"
    }
  ]
}

code 是兑换码，redeemUrl 是兑换链接，二选一发给买家即可。买家登录 Wokey 后兑换，面值进入其 API 额度。

• 生成礼品卡和直充都必须带幂等键。推荐直接用你的订单号。
• 幂等键在整个账号内唯一，网页操作和发行 API 共用，不区分是哪把令牌发起的。
• 同一个键重复请求、参数也相同时，不会再扣款，直接返回第一次的结果，replayed 为 true；生成礼品卡的重放会再次返回同一批兑换码。
• 同一个键但参数不同（sourceType、amountUsd、count，直充还有收款人）时，返回 409 idempotency_key_conflict。
• 网络超时或返回 5xx 时，用同一个键重试即可，不会重复扣款。

• 生成礼品卡和直充：每个账号每分钟最多 60 次（网页和发行 API 合计）。
• 读取礼品卡详情（含原文）：每个账号每分钟最多 120 次。
• 每批最多 500 张；单张面值 1 到 1,000,000 USD。
• 每个账号最多同时有 20 把未吊销的发卡令牌；每把令牌的 IP 白名单最多 20 个 IP。

安全建议

• 令牌只放在服务端（发卡平台后台或你的服务器），不要写进网页前端、App 或公开仓库。
• 有固定出口 IP 的，设置 IP 白名单。白名单按单个 IP 精确匹配，不支持网段。
• 设置每日额度上限，限制令牌泄露时的损失。额度按 UTC 自然日统计，生成礼品卡和直充合计。
• 修改密码或退出所有会话后，发卡令牌仍然有效。怀疑泄露时，请在「发卡令牌」标签页手动吊销，吊销后立即失效。
• 「发卡令牌」标签页会显示每把令牌最近一次使用的时间和 IP，可以定期检查。