下游代理商 API 文档

一、认证与签名

1.1 获取凭证

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

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

1.2 Sandbox 测试环境

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

Sandbox 特征：

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

Sandbox Webhook 测试

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

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

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

1.3 请求规范

• 请求方式：HTTPS
• 数据格式：application/json
• 字符编码：UTF-8

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

1.3 签名算法

时间戳有效期

时间戳必须在当前时间 ±5 分钟 内，超时返回 401。服务端使用 timing-safe 比较防止时序攻击。

1.4 签名示例（Node.js）

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

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

const secret = 'your_api_secret';
const timestamp = Date.now().toString();

// GET 请求示例
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 postSig = sign(secret, 'POST', '/api/v1/cards/info', timestamp, body);

1.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。

GET 查询余额

无请求参数。

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

POST 创建持卡人

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

idType 枚举

请求示例

复制{
  "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"
  }
}

GET 持卡人列表

复制{
  "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位）

GET 查询可用卡 BIN

获取当前平台支持的所有卡 BIN 列表，开卡时 cardBin 字段从此处取值。建议每次开卡前动态获取，不要写死。

无需请求参数。

响应示例

{
  "code": 0,
  "data": [
    {
      "binCode": "48331700",
      "businessScene": "AD_DELIVERY",
      "area": "US",
      "currency": "USD",
      "cardType": "VISA"
    },
    {
      "binCode": "55616701",
      "businessScene": "AD_DELIVERY",
      "area": "US",
      "currency": "USD",
      "cardType": "MASTERCARD"
    }
  ]
}

响应字段

POST 开卡

请求示例

复制{
  "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": "****"
  }
}

费用说明

从余额扣 cardAmt（充值到卡片）+ fee_apply（开卡固定费，管理员配置）。开卡失败 / cardholderId 无权限 → 自动全额退款。

GET 卡片列表

复制{
  "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
  }
}

卡片状态枚举

POST 查卡详情

实时查询卡片数据，包含完整卡号、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"
  }
}

POST 查卡号/CVV

每次调用都会记录审计日志（含调用 IP 和时间），适合前端展示卡号/CVV 的场景。

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

POST 卡片交易记录

支持两种查询模式：

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

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

复制{
  "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
  }
}

POST 提额（向卡片充值）

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

从代理商可用余额扣 amount，充值到指定卡片。失败自动退款。不额外收手续费。

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

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

从卡片取回 amount，退回代理商可用余额。降额金额不能超过卡片当前 availableLimit。不额外收手续费。

POST 申请提现

复制{
  "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"
  }
}

提现状态枚举

GET 提现记录

返回最近 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
  }
}

GET 扣费流水

返回最近 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 枚举

六、资金流转说明

七、Webhook 回调

7.1 概述

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

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

7.2 请求格式

复制{
  "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"
  }
}

7.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，签名验证永远失败。
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' });
});

7.4 notifyType 枚举

八、完整接入流程

九、注意事项

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；Webhook 签名只对 body 做 HMAC，与 API 签名规则不同；若项目全局注册了 express.json()，必须将 Webhook 路由放在它之前，否则 body 被提前消费导致签名永远失败
7. api_secret 安全：仅在服务端使用，不要写入前端代码、Git 仓库或日志
8. 卡号安全：cards/info 和 cards/sensitive 返回明文卡号/CVV，仅在你的服务端调用
9. 金额上限：单次操作金额不超过 $1,000,000
10. 提现地址：仅支持 TRC20 地址（T 开头，34位 Base58 字符）