餐饮 / 超市 / 新零售 · 多租户 SaaS

点点够商家 SaaS 聚合支付开放平台

为线下商户提供一站式门店经营、商品/菜单管理、订单履约与好支付渠道（星驿付）收单，用统一 API 支撑点餐、收银、会员与结算链路。

生产域名：https://pay.ddg.org.cn · API 前缀：/api/v1 · 联系：cly@tapgo.cn

多租户模型

  • Tenant（品牌）> Merchant（门店）> Store/Terminal
  • 支持多行业扩展模板（餐饮、零售、生鲜）
  • 账号体系兼容企业总部与门店员工

支付集成

  • 星驿付（好支付）聚合通道
  • 支持 NATIVE / JSAPI / H5 / 聚合码
  • 统一回调：/payment|/merchant|/withdraw/…

认证机制

  • Header X-DDG-Key & X-DDG-Timestamp
  • 请求体 UTF-8 JSON，SHA256 + RSA2048 签名
  • 白名单 IP：139.9.61.199

1. 核心业务域

面向商家 SaaS 的六大领域接口，均可独立授权/灰度。

Overview

Tenant & Merchant

品牌入驻、门店进件、终端绑定，自动同步星驿付主体。

  • POST /api/v1/tenants → 创建 SaaS 租户
  • POST /api/v1/merchants/apply → 门店进件
  • POST /api/v1/terminals/bind → 终端与门店绑定

Catalog & POS

菜品/商品、套餐、库存，供 POS、线上商城复用。

  • POST /api/v1/catalog/products
  • PATCH /api/v1/catalog/products/{id}
  • GET /api/v1/catalog/inventory?storeId=

Order & Payment

统一订单中心，支付使用好支付通道，提供状态查询与退款。

  • POST /api/v1/orders
  • POST /api/v1/payments/native | jsapi
  • GET /api/v1/payments/{outTradeNo}

Settlement & Account

支持 D0 提现、对账文件、余额预警，兼容总部/门店视角。

  • GET /api/v1/account/balance
  • POST /api/v1/settlements/withdraw
  • GET /api/v1/reconciliation/files

2. 请求签名

签名串包含所有参与签名的非空字段，按 ASCII 升序排列，key=value 之间用 & 连接，最终用平台颁发的 RSA 私钥对 SHA256 结果签名。

StringToSign = "amount=220&agetId=61000000195737&body=固定金额收款&custId=60000011494700&outTradeNo=202512021045010001&timeStamp=1764662701&version=1.0.0"
sha256       = "6c3e5f48e735d84f49d8e4a2c79c7ab8bf..."
signature    = Base64( RSA2048-Sign( sha256 ) )

3. API 目录

Sample 请求返回统一为 { code, message, data }。分页参数使用 ?page=1&pageSize=20。
模块 Method & Path 说明
租户管理 POST /api/v1/tenants 创建 SaaS 租户（品牌/总部），返回 tenantId 与默认管理员。
门店进件 POST /api/v1/merchants/apply 提交主体、门店、结算信息；同步至星驿付，异步通知 /merchant/registration/callback。
门店查询 GET /api/v1/merchants/{merchantId} 查看审核状态、费率、绑定终端列表。
终端绑定 POST /api/v1/terminals/bind 绑定 SN 与门店；解绑使用 DELETE /api/v1/terminals/{sn}。
商品/菜单 POST /api/v1/catalog/products 创建商品/菜品，支持多规格、多行业模板。
库存同步 PATCH /api/v1/catalog/inventory 批量调整库存；用于超市、便利店实时扣减。
订单创建 POST /api/v1/orders 创建 SaaS 平台订单（点餐/零售），生成 outTradeNo。
支付下单 POST /api/v1/payments/native | jsapi | h5 调用星驿付 unifiedOrder，支付结果回调 /payment/success/callback。
订单查询 GET /api/v1/payments/{outTradeNo} 返回支付状态、渠道流水（tradeNo）、实收金额。
退款 POST /api/v1/payments/{outTradeNo}/refund 发起部分/全额退款；查询接口 GET /api/v1/refunds/{refundNo}。
账户余额 GET /api/v1/account/balance 总部/门店可分别查看余额；阈值触发 /account/balance/callback。
实时提现 POST /api/v1/settlements/withdraw D0 提现请求；结果回调 /withdraw/success/callback。
对账文件 GET /api/v1/reconciliation/files?date=YYYY-MM-DD 返回交易/提现对账下载链接；支持中文/英文格式。

示例 · 门店进件

POST /api/v1/merchants/apply

{
  "tenantId": "T20250101001",
  "store": {
    "name": "点点够·湖里万达店",
    "industry": "RESTAURANT",
    "province": "福建省",
    "city": "厦门市",
    "address": "湖里区万达广场 1F"
  },
  "license": {
    "name": "厦门点点够餐饮有限公司",
    "creditCode": "91350211MA347LWG6D",
    "expireDate": "2035-12-31"
  },
  "settlement": {
    "bankName": "中国银行",
    "accountNo": "6216660099999999",
    "accountName": "厦门点点够餐饮有限公司",
    "bankBranch": "中国银行厦门分行"
  },
  "contact": {
    "name": "陈来意",
    "phone": "13800000000",
    "email": "ops@tapgo.cn"
  },
  "timeStamp": 1764665400,
  "sign": "BASE64_RSA_SIGNATURE"
}

示例 · NATIVE 支付

POST /api/v1/payments/native

{
  "tenantId": "T20250101001",
  "merchantId": "60000011494700",
  "outTradeNo": "DDG20251202110300123",
  "amount": 220,
  "currency": "CNY",
  "body": "堂食 · 2.2 元",
  "notifyUrl": "https://pay.ddg.org.cn/payment/success/callback",
  "attach": {
    "channel": "STORE_POS",
    "tableNo": "A03"
  },
  "timeStamp": 1764665490,
  "sign": "BASE64_RSA_SIGNATURE"
}

4. 异步通知映射

事件 回调 URL 描述
交易成功 /payment/success/callback 支付宝/微信/银联成功返回；日志写入 logs/callbacks/payment-success-YYYYMMDD.log。
商户进件 /merchant/registration/callback 星驿付审核完成；通知 SaaS 更新门店状态。
终端绑定/解绑 /device/bind/callback · /device/unbind/callback POS/台卡等绑解绑回执。
账户余额 /account/balance/callback 余额阈值、日终对账告警。
实时提现 /withdraw/success/callback D0 提现结果。
D0 申诉 /d0/dispute/callback 提前批/日切特殊流程反馈。
商户状态 /merchant/status/callback 数币开通、风控冻结等状态变更。
微信活动报名 /wechat/activity/callback 营销活动报名结果。
特殊业务 /special/service/callback 日切、批量导入等自定义告警。

5. 错误码

code 说明 处理建议
0000 成功 业务处理完成
1001 签名不合法/已过期 检查 X-DDG-Timestamp、签名串及时钟偏差
2004 商户状态异常 调用商户查询接口确认状态，或等待进件审核
3002 交易已存在 使用订单查询获取最新状态，避免重复下单
4001 库存不足 提示运营调整库存，或改下单门店
5000 渠道返回失败 查看 data.channelMessage，并联系好支付/运营