四海通 下游代理商 API 文档

版本：v1.4

更新：2026-03-18

Base URL：https://mama.best

---

一、接入说明

1.1 获取凭证

联系平台管理员开通代理商账户，获取：

• api_key：公开标识，每次请求必须携带
• api_secret：私钥，用于签名，创建时一次性返回，之后不可再查，请妥善保存

1.2 Sandbox 测试环境

平台提供 Sandbox 测试账号，用于开发联调。测试账号的所有接口返回模拟数据，不调用真实上游、不消耗真实资金，接口格式与生产环境完全一致。

Sandbox 特征：

• 卡 BIN 以 SB 开头（如 SB000001）
• virtualCardId 以 SB 开头（如 SB260319...）
• 持卡人 ID 以 SB_HOLDER_ 开头
• 余额正常扣减/退回，验证资金流转逻辑
• 无需真实身份证信息，持卡人随意填写即可通过

⚠️ 联调完成后，将 API Key / Secret 替换为正式账号凭证即可上生产，代码无需其他改动。

Sandbox Webhook 测试

联调 Webhook 时，先告知平台配置你的 webhookUrl，然后调用以下接口，平台会主动向你的地址推送一条模拟事件：

POST /api/v1/sandbox/trigger-webhook

响应中 data.httpStatus 是你的 Webhook 端点返回的 HTTP 状态码，data.response 是你端点的响应体，可用于确认接收是否正常。

此接口仅 Sandbox 账号可调用，生产账号调用返回 4003 错误。

1.3 请求规范

• 请求方式：HTTPS
• 数据格式：application/json
• 字符编码：UTF-8
• 单次金额上限：$1,000,000

1.4 请求头（所有接口必填）

---

二、签名规则

2.1 签名算法

复制signature = HMAC-SHA256(api_secret, METHOD + PATH + TIMESTAMP + BODY)

签名结果取 hex 编码（小写）。

⚠️ 重要：签名使用 pathname，不含 query string。

例如请求 /api/v1/cards?page=1&externalRef=user_123，签名时使用 /api/v1/cards。

⚠️ POST body 签名注意： 使用 JSON.stringify 的原始字符串，不要格式化（不能有多余空格/换行）。签名时的 body 字符串必须与实际发送的 HTTP body 完全一致。

2.2 时间戳有效期

时间戳必须在当前时间 ±5 分钟 内，超时返回 401。

2.3 签名验证方式

服务端使用 timing-safe 比较（crypto.timingSafeEqual），防止时序攻击。

2.4 签名示例（Node.js）

复制const crypto = require('crypto');

function sign(secret, method, path, timestamp, body = '') {
  // ⚠️ 取 pathname，去掉 query string
  const pathname = path.split('?')[0];
  const payload = `${method.toUpperCase()}${pathname}${timestamp}${body}`;
  return crypto.createHmac('sha256', secret).update(payload).digest('hex');
}

// GET 请求示例
const secret = 'your_api_secret';
const timestamp = Date.now().toString();
const signature = sign(secret, 'GET', '/api/v1/balance', timestamp, '');

const headers = {
  'X-Api-Key': 'your_api_key',
  'X-Timestamp': timestamp,
  'X-Signature': signature,
  'Content-Type': 'application/json',
};

// POST 请求示例
const body = JSON.stringify({ virtualCardId: 'VC2603172099197' });
const postSignature = sign(secret, 'POST', '/api/v1/cards/info', timestamp, body);

2.5 签名示例（Python）

复制import hmac, hashlib, time, json, requests

def sign(secret, method, path, timestamp, body=''):
    pathname = path.split('?')[0]
    payload = f"{method.upper()}{pathname}{timestamp}{body}"
    return hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

API_KEY = 'your_api_key'
API_SECRET = 'your_api_secret'
BASE = 'https://mama.best'

# GET 示例
ts = str(int(time.time() * 1000))
sig = sign(API_SECRET, 'GET', '/api/v1/balance', ts)
resp = requests.get(f'{BASE}/api/v1/balance', headers={
    'X-Api-Key': API_KEY, 'X-Timestamp': ts, 'X-Signature': sig,
    'Content-Type': 'application/json',
})

# POST 示例（注意 separators 不能有多余空格）
body = json.dumps({"virtualCardId": "VC2603..."}, separators=(',', ':'))
ts = str(int(time.time() * 1000))
sig = sign(API_SECRET, 'POST', '/api/v1/cards/info', ts, body)
resp = requests.post(f'{BASE}/api/v1/cards/info', data=body, headers={
    'X-Api-Key': API_KEY, 'X-Timestamp': ts, 'X-Signature': sig,
    'Content-Type': 'application/json',
})

---

三、通用响应格式

复制{
  "code": 0,
  "data": { ... },
  "message": "success"
}

错误码

---

四、接口总览

---

五、externalRef 用户标识

externalRef 是代理商自定义的用户标识，用于将平台资源（卡片/持卡人/交易）与你自己系统中的用户关联。

格式要求：

• 任意字符串，最长 128 字符
• 建议使用你系统中的用户 ID，如 user_123456

支持 externalRef 的接口：

以上路径省略前缀 /api/api/v1

---

六、接口详情

---

6.1 查询余额

GET /api/v1/balance

无请求参数。

响应示例：

复制{
  "code": 0,
  "data": {
    "balance": "500.00",
    "frozenBalance": "10.00",
    "currency": "USD"
  }
}

---

6.2 创建持卡人

POST /api/v1/cardholders

持卡人是虚拟卡的归属人，开卡时必须指定 cardholderId。一个持卡人可开多张卡。

请求参数：

idType 枚举：

⚠️ 重要： 平台会对持卡人信息进行真实性校验：

- 身份证号必须是真实存在的号码（区划码、生日与号码一致，有公安库比对）

- province / city 填中文（如 福建省 / 泉州市），填英文会导致审核失败

- birthday 必须与身份证中间 8 位一致

- email 若提供则全局唯一，同一邮箱不能注册两个持卡人

请求示例：

复制{
  "firstName": "San",
  "lastName": "Zhang",
  "birthday": "1990-01-15",
  "gender": "M",
  "idType": "ID_CARD",
  "idNumber": "350582199001150011",
  "phoneAreaCode": "86",
  "phone": "13800138000",
  "province": "福建省",
  "city": "泉州市",
  "address": "丰泽区东海街道东海大街1号",
  "country": "CN",
  "postalCode": "362000",
  "email": "[email protected]",
  "externalRef": "user_123456"
}

响应示例：

复制{
  "code": 0,
  "data": {
    "cardholderId": "2029856542649827330",
    "localId": "5",
    "firstName": "San",
    "lastName": "Zhang",
    "externalRef": "user_123456",
    "status": "1"
  }
}

---

6.3 持卡人列表

GET /api/v1/cardholders

Query 参数：

响应示例：

复制{
  "code": 0,
  "data": {
    "list": [
      {
        "cardholderId": "2029856542649827330",
        "localId": "5",
        "firstName": "San",
        "lastName": "Zhang",
        "country": "CN",
        "idType": "ID_CARD",
        "idNumber": "110***011",
        "externalRef": "user_123456",
        "createdAt": "2026-03-17T06:00:00.000Z"
      }
    ],
    "total": 1
  }
}

注：idNumber 返回脱敏值（前3位 + *** + 后3位）

---

6.4 查询可用卡 BIN

GET /api/v1/card-bins

无需请求参数。

响应示例：

复制{
  "code": 0,
  "data": [
    {
      "binCode": "48331700",
      "businessScene": "AD_DELIVERY",
      "area": "US",
      "currency": "USD",
      "cardType": "VISA",
      "productIntroduction": "适用于广告投放/线上订阅场景的虚拟卡产品",
      "cardOrganization": "VISA"
    },
    {
      "binCode": "55616701",
      "businessScene": "AD_DELIVERY",
      "area": "US",
      "currency": "USD",
      "cardType": "MASTERCARD",
      "productIntroduction": "适用于广告投放/线上订阅场景的虚拟卡产品",
      "cardOrganization": "MASTERCARD"
    }
  ]
}

响应字段说明：

建议开卡前先调用此接口获取最新可用 BIN 列表，而非写死在代码中。

---

6.5 开卡

POST /api/v1/cards/apply

请求参数：

⚠️ 不需要传 walletNo，平台自动使用主钱包。

请求示例：

复制{
  "outOrderId": "order-20260317-uuid-001",
  "cardBin": "556371",
  "cardAmt": 100,
  "cardholderId": "2029856542649827330",
  "externalRef": "user_123456"
}

响应示例（成功）：

复制{
  "code": 0,
  "data": {
    "virtualCardId": "VC2603172099197",
    "status": "0",
    "outOrderId": "order-20260317-uuid-001",
    "cardNoMasked": "****"
  }
}

cardNoMasked 在刚开卡时为 *（占位），等平台回调后更新为真实脱敏卡号（如 5561*7969）。

响应示例（幂等重放，相同 outOrderId）：

复制{
  "code": 0,
  "data": { "virtualCardId": "VC2603172099197", "..." : "..." },
  "message": "幂等重放"
}

响应示例（outOrderId 正在处理中）：

复制{
  "code": 4009,
  "message": "相同 outOrderId 正在处理中，请勿重复提交"
}

费用说明：

• 从余额扣 cardAmt（充值到卡片） + fee_apply（开卡固定费，管理员配置）
• 开卡失败 / cardholderId 无权限 → 自动全额退款（含开卡费）
• 两笔扣款在同一事务中完成，不会出现只扣了一半的情况

开卡流程：

复制扣款（cardAmt + fee_apply）→ 校验 cardholderId 归属 → 调上游渠道 → 本地预建记录
      ↓ 失败自动退款              ↓ 失败退款                ↓ 失败退款

⚠️ 异步激活： virtualCardId 立即返回，但卡片激活（status=3）需等待平台回调（通常几秒~几分钟）。

激活后 Webhook 推送 CARD_APPLY 事件，届时可通过 cards/info 查询完整卡号和 CVV。

---

6.6 卡片列表

GET /api/v1/cards

Query 参数：

响应示例：

复制{
  "code": 0,
  "data": {
    "list": [
      {
        "virtualCardId": "VC2603172099197",
        "cardNoMasked": "5561****7969",
        "cardBin": "55616701",
        "status": 3,
        "cardBalance": "50.00",
        "totalLimit": 100,
        "expiryDate": "03/27",
        "currency": "USD",
        "externalRef": "user_123456",
        "createdAt": "2026-03-17T08:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}

卡片状态枚举：

---

6.7 查卡详情

POST /api/v1/cards/info

实时查询卡片数据，包含完整卡号、CVV、实时余额。

请求参数：

响应示例：

复制{
  "code": 0,
  "data": {
    "virtualCardId": "VC2603172099197",
    "cardNo": "5561670158047969",
    "cardBin": "55616701",
    "cvv": "446",
    "expiry": "03/27",
    "status": "3",
    "cardAmt": 100,
    "totalLimit": 100,
    "usedLimit": 20,
    "availableLimit": 80,
    "ccy": "USD"
  }
}

⚠️ 判断卡片实际可用余额应使用 availableLimit，而非 cardAmt。

---

6.8 查卡号/CVV（专用接口）

POST /api/v1/cards/sensitive

功能与 cards/info 类似，但此接口每次调用都会记录审计日志（含调用 IP 和时间），适合前端展示卡号/CVV 的场景。

请求参数：

响应示例：

复制{
  "code": 0,
  "data": {
    "cardNo": "5561670158047969",
    "cvv": "446",
    "expiry": "03/27"
  }
}

⚠️ 安全提示： 请仅在你的服务端调用此接口，不要在前端 JS 中直接暴露 API Secret 和调用。

---

6.9 卡片交易记录

POST /api/v1/cards/transactions

支持两种查询模式：

模式一：按卡片查（单卡）

模式二：按用户查（该用户所有卡）

virtualCardId 和 externalRef 二选一，优先使用 externalRef（如果同时传了两个）。

响应示例：

复制{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "cardId": 5,
        "notifyType": "CARD_SETTLEMENT",
        "payOrderId": "CT2026...",
        "amount": "20.00",
        "currency": "USD",
        "merchantName": "OPENAI *CHATGPT SUBSCR",
        "transactionTime": "2026-03-17T10:00:00.000Z",
        "status": 1,
        "createdAt": "2026-03-17T10:00:05.000Z"
      }
    ],
    "total": 4,
    "page": 1,
    "pageSize": 20
  }
}

---

6.10 提额（向卡片充值）

POST /api/v1/cards/increase

请求参数：

响应示例：

复制{
  "code": 0,
  "data": {
    "message": "提额成功",
    "virtualCardId": "VC2603172099197",
    "amount": 50
  }
}

说明：

• 从代理商可用余额扣 amount，充值到指定卡片
• 提额失败 → 自动退款回代理商余额
• 不额外收手续费
• 已注销的卡（status=5）不可提额

---

6.11 降额（从卡片回收资金）

POST /api/v1/cards/decrease

请求参数：

响应示例：

复制{
  "code": 0,
  "data": {
    "message": "降额成功",
    "virtualCardId": "VC2603172099197",
    "amount": 30
  }
}

说明：

• 从卡片取回 amount，退回代理商可用余额
• 降额金额不能超过卡片当前 availableLimit（实时查询）
• 超过时返回详细错误：降额金额 $30.00 超过卡片可用余额 $20.00
• 不额外收手续费
• 已注销的卡不可降额

---

6.12 申请提现

POST /api/v1/withdraw/apply

请求参数：

请求示例：

复制{
  "amount": 200,
  "receiveAddress": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

响应示例：

复制{
  "code": 0,
  "data": {
    "id": 1,
    "requestNo": "AW1710641234567ABCD",
    "amount": "200.000000",
    "feeAmount": "2.000000",
    "actualAmount": "198.000000",
    "receiveAddress": "TXxxx...",
    "status": 0,
    "createdAt": "2026-03-17T05:30:00.000Z"
  }
}

提现状态枚举：

资金流转：

• 申请时：balance 减少 → frozenBalance 增加（原子操作）
• 完成时：frozenBalance 减少
• 拒绝时：frozenBalance 减少 → balance 增加（原子退回）

---

6.13 提现记录

GET /api/v1/withdraw/list

当前版本返回最近 20 条记录，按创建时间倒序。

响应示例：

复制{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "requestNo": "AW1710641234567ABCD",
        "amount": "200.000000",
        "feeAmount": "2.000000",
        "actualAmount": "198.000000",
        "receiveAddress": "TXxxx...",
        "status": 3,
        "txHash": "abc123...",
        "createdAt": "2026-03-17T05:30:00.000Z"
      }
    ],
    "total": 1
  }
}

---

6.14 扣费流水

GET /api/v1/fee-logs

当前版本返回最近 20 条记录，按创建时间倒序。

响应示例：

复制{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "feeType": "APPLY_CARD",
        "feeAmount": "2.000000",
        "balanceBefore": "502.000000",
        "balanceAfter": "500.000000",
        "relatedCardId": "VC2603...",
        "remark": "开卡费 cardBin=556371",
        "createdAt": "2026-03-17T05:00:00.000Z"
      }
    ],
    "total": 21
  }
}

feeType 枚举：

balanceBefore / balanceAfter 可用于对账，精度为 6 位小数。

---

七、资金流转说明

复制代理商平台余额（由管理员 USDT 充值）
    │
    ├── 开卡 ──→ 扣 cardAmt（→ 卡片 availableLimit）+ fee_apply（→ 平台收入）
    │            失败自动全额退款
    │
    ├── 提额 ──→ 扣 amount（→ 卡片 availableLimit）
    │            失败自动退款
    │
    ├── 降额 ←── 退 amount（← 卡片 availableLimit → 代理商余额）
    │
    ├── 销卡 ←── 退 cardBalance（← 卡片余额 → 代理商余额），然后卡注销
    │
    ├── 消费 ──→ 直接扣卡片额度（不经过代理商余额）
    │            平台通过 Webhook 通知
    │
    └── 提现 ──→ 冻结 amount（balance → frozenBalance）
                 管理员审核 → 出金 → 完成（frozenBalance 清除）
                 拒绝 → 退回（frozenBalance → balance）

---

八、Webhook 回调

8.1 概述

当卡片发生消费、退款、状态变更等事件时，平台自动向你配置的 webhookUrl 发送 POST 回调。

前提条件：

• 已配置 webhookUrl（联系管理员设置）
• 代理商状态为启用（status=1）
• 卡片 apiClientId 已关联（仅转发代理商自己的卡片事件）

8.2 请求格式

请求头：

⚠️ Webhook 签名规则与 API 签名不同：Webhook 只对 body 做 HMAC（不拼接 method/path/timestamp）。

请求体示例：

复制{
  "notifyType": "CARD_SETTLEMENT",
  "data": {
    "virtualCardId": "VC2603172099197",
    "payOrderId": "CT2026...",
    "externalRef": "user_123456",
    "clientId": "4",
    "clientName": "你的代理商名称",
    "settlementAmount": 20.00,
    "settlementCurrency": "USD",
    "consumptionAmount": 20.00,
    "consumptionCurrency": "USD",
    "transactionObject": "OPENAI *CHATGPT SUBSCR",
    "transactionTime": "2026-03-17 10:00:00",
    "status": "2"
  }
}

安全说明： 平台内部信息（merchantId/merchantName）已自动移除，替换为 clientId/clientName。

externalRef 字段从卡片记录自动读取并附加。

8.3 验签（必须实现）

复制const crypto = require('crypto');

function verifyWebhook(apiSecret, rawBody, signature) {
  // ⚠️ 注意：Webhook 签名只对 body 做 HMAC，不含 method/path/timestamp
  const expected = crypto
    .createHmac('sha256', apiSecret)
    .update(rawBody)  // 原始 body 字符串，不要 JSON.parse 后再 stringify
    .digest('hex');
  return expected === signature;
}

// Express 示例
// ⚠️ 重要：Webhook 路由必须在 express.json() 全局中间件之前注册！
// 如果全局注册了 app.use(express.json())，会提前消费 body stream，
// 导致 express.raw() 拿到空 body，签名验证永远失败。
// 正确写法：把 webhook 路由放在 express.json() 注册之前。
app.post('/webhook/dd', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-signature'];
  const raw = req.body.toString();
  
  if (!verifyWebhook('your_api_secret', raw, sig)) {
    return res.status(401).json({ code: 1, message: 'invalid signature' });
  }
  
  const payload = JSON.parse(raw);
  console.log('收到回调:', payload.notifyType, payload.data);
  
  // 处理业务...
  res.json({ code: 0, message: 'success' });
});

8.4 响应要求

10 秒内响应 HTTP 200：

复制{ "code": 0, "message": "success" }

• code 必须为 0，否则视为失败
• 失败时平台自动重试，最多 3 次（间隔 0s / 5s / 10s）
• 全部失败后记录到 Webhook 转发日志，可联系管理员查看

8.5 notifyType 枚举

---

九、完整接入流程

复制步骤1：获取凭证
  联系管理员创建代理商账号
  → 获得 api_key + api_secret（secret 只展示一次！）
  → 提供你的 Webhook URL 给管理员配置

步骤2：充值
  管理员通过后台给你充值平台余额（USDT → USD）
  → 调用 GET /balance 确认到账

步骤3：创建持卡人
  POST /cardholders
  → 保存返回的 cardholderId（后续开卡必须）

步骤4：开卡
  POST /cards/apply
  → 保存 virtualCardId

步骤5：等待激活
  收到 Webhook CARD_APPLY → 卡片 status=3
  → 调用 cards/info 或 cards/sensitive 获取完整卡号和 CVV

步骤6：使用
  用户拿到卡号+CVV+有效期，即可进行线上消费
  消费发生时你会收到 CARD_AUTH → CARD_SETTLEMENT 回调

步骤7：日常管理
  提额/降额/冻结/解冻/销卡/查交易

步骤8：提现
  POST /withdraw/apply → 管理员审核出金（1-2 工作日）

---

十、注意事项

1. 幂等性： outOrderId 相同的开卡请求只执行一次，重复请求返回原始结果；正在处理中的返回 4009 错误
2. 金额精度： 请求时可传 number 或 string；响应中金额为 string（6位小数精度），显示时建议保留 2 位
3. 时间戳： 精确到毫秒（13位），与服务器时差不超过 5 分钟
4. 签名 body： 使用 JSON.stringify 的原始字符串，不要格式化或添加多余空格
5. 签名路径： 使用 pathname，不含 query string
6. Webhook 验签： 使用 express.raw() 保留原始 body，不能先 parse 再 stringify；Webhook 签名只对 body 做 HMAC；若项目中全局注册了 express.json()，必须将 Webhook 路由放在它之前，否则 body 被提前消费导致签名永远失败
7. api_secret 安全： 仅在服务端使用，不要写入前端代码、Git 仓库或日志
8. 卡号安全： cards/info 和 cards/sensitive 返回明文卡号/CVV，仅在你的服务端调用
9. 已注销卡片： status=5 的卡禁止所有写操作（提额/降额/冻结/解冻/销卡）
10. 金额上限： 单次操作金额不超过 $1,000,000
11. 提现地址： 仅支持 TRC20 地址（T 开头，34位 Base58 字符）