JDH API

鉴权

所有 /ext/p2c/* 接口（除 /ext/p2c/health 外）均须在请求头携带 API Key。Gateway 校验 Key 有效性、代理商状态及 IP 访问策略。

• 每个 API Key 与唯一代理商编号（agentCode）绑定，Gateway 自动识别调用方身份。
• 请求体中的 agentCode 应填写该 Key 所属代理商编号。
• 代理商被禁用或风控暂停时，对应 Key 自动失效。

获取与管理 API Key

正式 Key 格式为 atp_ 前缀 + 64 位十六进制字符（示例：atp_a1b2c3d4...f0e1）。

环境地址

响应格式

无论成功或失败，HTTP 状态码均为 200。请根据 JSON 中的 code 判断业务结果。

{
  "code": "0",
  "message": "success",
  "data": { }
}

充值流程

玩家发起充值后，系统优先匹配提款池中的待提款单；若无匹配则路由至代理商银行卡收款。

• 同一玩家同时只能有一笔进行中的充值单。
• 成功时返回收款账户信息（提款方或银行卡）。
• 上传水单后图片 Base64 直接存入管理后台数据库，并触发 凭证验真服务 验真（可配置模拟模式）。
• 验单异步处理；凭证拒绝或需重传时，平台会向代理商配置的 callbackUrl 推送事件（见事件回调）。
• 可通过 deposit-active 查询进行中订单，deposit-cancel 取消。

提现进池流程

玩家提现申请进入代理商提款池，等待充值方匹配。

• 创建提款单时会冻结代理商池子对应额度。
• 充值方 deposit-match 匹配成功时推送 withdraw_matched；关联充值验单到账后推送 withdraw_settled（部分）或 withdraw_completed（全部）。
• 总等待时间到期未完全匹配时，系统将过期并释放冻结额度，推送 withdraw_timeout。
• 后台人工释放或重新排队时推送 withdraw_released / withdraw_requeued（见事件回调）。

P2C 存款流程（AutoPeer 兼容）

适用于传统 P2C 存款场景，订单由 Gateway 本地管理，与充值为独立流程。

充值接口

提现接口

水单上传接口

P2C 存款接口

通用接口

事件回调（callbackUrl）

平台在特定业务节点向代理商配置的 回调 URL 主动发起 HTTP 请求。 方向为 平台 → 代理商，与 Gateway 对外 API 相反。 请在管理后台「代理商」编辑页填写 callbackUrl（HTTPS 推荐）。

• 请求方式：POST，Content-Type: application/json
• 所有 payload 顶层均含 event 字段，用于区分事件类型
• 未配置或留空 callbackUrl 时静默跳过，不发送
• 每次回调写入管理后台 agent_callback_logs，便于排查
• 接入方应返回 HTTP 2xx 表示接收成功；非 2xx 会记为失败但仍保留业务结果

事件一览

充值回调公共字段

所有充值相关回调 payload 均包含以下字段（部分可选）：

提现回调公共字段

所有提现相关回调 payload 均包含以下字段（部分可选）：

{
  "event": "withdraw_timeout",
  "orderNo": "W202605260001",
  "playerId": "P10001",
  "agentCode": "AG001",
  "totalAmount": 5000,
  "remainingAmount": 2000,
  "matchedAmount": 3000,
  "status": "expired",
  "expiredAt": "2026-05-26T10:30:00Z",
  "matches": [
    {
      "depositOrderNo": "D202605260010",
      "amount": 3000,
      "matchedAt": "2026-05-26T10:15:00Z"
    }
  ]
}

{
  "event": "deposit_voucher_rejected",
  "orderNo": "D202605260001",
  "playerId": "P10001",
  "agentCode": "AG001",
  "amount": 1000,
  "issueType": "account_mismatch",
  "message": "收款账号与订单不一致",
  "status": "rejected"
}

{
  "event": "deposit_voucher_reupload_required",
  "orderNo": "D202605260001",
  "playerId": "P10001",
  "agentCode": "AG001",
  "amount": 1000,
  "message": "凭证 OCR 识别失败，请重新上传清晰凭证",
  "status": "waiting_payment",
  "voucherStatus": "not_uploaded"
}

接入建议

• 回调接口应幂等：同一订单可能因重试收到重复通知，请按 event + orderNo 去重。
• 收到 deposit_voucher_completed 或 deposit_voucher_amount_mismatch 后，按 amount 给玩家加款。
• 收到 deposit_voucher_reupload_required 或 deposit_voucher_service_unavailable 后，H5 应保留当前充值单并重新打开上传入口，无需重新 deposit-match。
• 收到 deposit_voucher_rejected、deposit_cancelled 或 deposit_expired 后，充值单已关闭，玩家需重新发起充值。
• 收到 deposit_voucher_manual_review 后，订单等待后台人工处理，完成后会再推送 deposit_voucher_completed 或 deposit_voucher_rejected。
• 收到 withdraw_matched 后，表示已有充值方接单，提现玩家等待对方转账。
• 收到 withdraw_settled 或 withdraw_completed 后，按到账进度更新 H5 展示。
• 收到 withdraw_timeout 或 withdraw_released 后，提现单已关闭，玩家需重新发起。
• 收到 withdraw_requeued 后，提现单已重新进入匹配池，可继续等待撮合。

常见错误码

调用示例

以下示例使用本地开发 Key dev-atp-key-change-me（代理商 AG001）。生产环境请替换为管理后台获取的 atp_... Key。

充值

curl -s -X POST http://localhost:8080/ext/p2c/deposit-match \
  -H 'Content-Type: application/json' \
  -H 'x-atp-key: dev-atp-key-change-me' \
  -d '{
    "agentCode": "AG001",
    "memberId": "P10001",
    "amount": 1000,
    "bankCode": "SCB"
  }'

# 或使用 Bearer 方式
# -H 'Authorization: Bearer dev-atp-key-change-me'

上传水单并提交验单

curl -s -X POST http://localhost:8080/ext/p2c/submit-voucher \
  -H 'Content-Type: application/json' \
  -H 'x-atp-key: dev-atp-key-change-me' \
  -d '{
    "ref": "D202605260001",
    "base64Data": "<BASE64>",
    "contentType": "image/jpeg"
  }'

玩家提现进池

curl -s -X POST http://localhost:8080/ext/p2c/withdraw-request \
  -H 'Content-Type: application/json' \
  -H 'x-atp-key: dev-atp-key-change-me' \
  -d '{
    "agentCode": "AG001",
    "memberId": "P10001",
    "amount": 5000,
    "bankCode": "SCB",
    "accountNo": "1234567890",
    "accountName": "Somchai S"
  }'

银行列表

curl -s http://localhost:8080/ext/p2c/bank-list \
  -H 'x-atp-key: dev-atp-key-change-me'