KOREA PAYMENT TOOLS

Kakao Pay Order API

文档导航

接入与认证

接口采用纯 CDK 模式，不需要另外申请 API Key。每次请求都在 X-CDK 请求头中携带一条龙 CDK；该 CDK 同时用于身份验证、订单归属校验和任务额度结算。

项目	值
Base URL	https://masi.cc.cd/kakao/scan/api/integration
认证请求头	X-CDK: KSCAN-...
请求格式	`application/json; charset=utf-8`
时间字段	Unix 秒级时间戳

Content-Type: application/json
X-CDK: YOUR_CDK

CDK 应仅保存在服务端。查询订单不会扣除额度；只有工人确认扫码完成后才正式扣除一次任务额度，提链失败或任务过期会释放预留额度。

1. 创建订单

POST/orders

使用 X-CDK 中的一条龙 CDK 与用户 AT 创建订单。服务端完成链接提取后进入工人扫码队列。一次成功请求创建一个新订单；当前不支持幂等键，网络超时后应先查询已获得的订单编号，避免直接重复提交。

请求体

字段	类型	必填	说明
`access_token`	string	是	完整 AT 内容或系统支持的 AT 输入格式

curl -X POST 'https://masi.cc.cd/kakao/scan/api/integration/orders' \
  -H 'Content-Type: application/json' \
  -H 'X-CDK: KSCAN-XXXX-XXXX-XXXX-XXXX' \
  -d '{
    "access_token": "YOUR_AT_CONTENT"
  }'

HTTP 201

{
  "ok": true,
  "order": {
    "order_id": "8f21ab34cd56ef78",
    "status": "extracting",
    "message": "正在进行 Kakao 链接提取。",
    "worker_name": "",
    "created_at": 1785256800,
    "updated_at": 1785256800,
    "completed_at": 0,
    "qr_expires_at": 0,
    "reward_cents": 0,
    "error": ""
  },
  "ticket": {
    "code": "KSCAN-XXXX-XXXX-XXXX-XXXX",
    "total_uses": 5,
    "used_uses": 0,
    "pending_uses": 1,
    "available_uses": 4
  }
}

2. 查询订单

GET/orders/{order_id}

只能使用创建该订单时的同一张 CDK 查询。建议在未完成时每 2–5 秒轮询一次，进入终态后停止轮询。

curl 'https://masi.cc.cd/kakao/scan/api/integration/orders/8f21ab34cd56ef78' \
  -H 'X-CDK: KSCAN-XXXX-XXXX-XXXX-XXXX'

HTTP 200

{
  "ok": true,
  "order": {
    "order_id": "8f21ab34cd56ef78",
    "status": "completed",
    "message": "扫码完成。",
    "worker_name": "worker-a",
    "created_at": 1785256800,
    "updated_at": 1785257016,
    "completed_at": 1785257016,
    "qr_expires_at": 1785257700,
    "reward_cents": 50,
    "error": "",
    "link": "https://payment.example/kakao/...",
    "account_check": {
      "ok": true,
      "status": "live_api",
      "email": "user@example.com",
      "account_plan": "plus",
      "is_plus": true,
      "is_paid": true,
      "checked_at": 1785257016,
      "message": "已通过实时账户接口检测。"
    }
  }
}

account_check 仅在订单完成后返回。AT 原文不会出现在查询响应中。

3. 查询 CDK 额度

POST/tickets/status

查询当前认证 CDK 的总额度、已用、处理中和剩余额度。查询操作不扣除任务额度。

curl -X POST 'https://masi.cc.cd/kakao/scan/api/integration/tickets/status' \
  -H 'Content-Type: application/json' \
  -H 'X-CDK: KSCAN-XXXX-XXXX-XXXX-XXXX' \
  -d '{}'

{
  "ok": true,
  "ticket": {
    "code": "KSCAN-XXXX-XXXX-XXXX-XXXX",
    "status": "available",
    "ticket_type": "all_in_one",
    "total_uses": 5,
    "used_uses": 2,
    "pending_uses": 1,
    "available_uses": 2
  }
}

订单状态与关键字段

status	是否终态	含义	额度处理
extracting	否	正在提取支付链接	额度预留
awaiting_worker	否	已提链，等待工人领取	额度预留
claimed	否	工人已领取，等待扫码	额度预留
completed	是	工人确认扫码完成	正式扣除一次
failed	是	提链或处理失败	释放预留额度
expired	是	支付链接或任务超时	释放预留额度

套餐检测状态

account_check.status	说明
post_checking	完成后正在同步套餐状态
live_api	由实时账户接口得到结果
at_claim	实时检测不可用，回退使用 AT 声明
unavailable	暂时无法确认套餐信息

HTTP 状态码与错误结构

{
  "ok": false,
  "error": "可读的错误说明"
}

HTTP	场景	处理建议
400	JSON、AT、CDK或参数无效，或CDK额度不足	修正请求或补充额度后再提交
401	请求头未提供 CDK	检查 `X-CDK` 请求头
404	订单不存在或不属于当前 CDK	检查订单编号及创建订单时使用的 CDK
429	请求频率超过网关限制	指数退避后重试
500	服务器内部错误	保存时间、订单号和错误内容后联系管理员
503	数据库或缓存暂不可用	稍后重试并检查健康接口