卡片令牌化

POST/api/v1/bank/wallet/tokenization/Bearer Token

---

请求头

请求头	值	必填
Authorization	Bearer {A55_ACCESS_TOKEN}	是
Content-Type	application/json	是
Idempotency-Key（幂等键）	UUID v4	建议

请求体

字段	类型	必填	说明
wallet_uuid	string (UUID)	是	钱包 ID
merchant_uuid	string (UUID)	是	商户 ID
card	object	是	待令牌化的卡片信息
card.holder_name	string	是	卡面印刷的持卡人姓名
card.number	string	是	卡号（PAN），13–16 位数字
card.expiry_month	string	是	有效期月份（01–12），2 位数字
card.expiry_year	string	是	有效期年份（YYYY），4 位数字
card.cvv	string	是	卡片安全码（CVV），3 位数字

卡片数据处理

发送原始卡片数据时，A55 会在收到后立即加密并存入安全保险库。如果您不希望在后端处理卡片数据，请改用 A55Pay SDK 或 Checkout 页面。

---

响应字段

字段	类型	说明
token_uuid	string (UUID)	可复用的令牌标识符，用于后续收款
card_brand	string	卡品牌（visa、mastercard、amex、elo）
card_last_four	string	卡号后 4 位
card_expiry_month	string	有效期月份
card_expiry_year	string	有效期年份
status	string	成功时为 active
created_at	string	ISO 8601 创建时间戳

响应示例

{
  "token_uuid": "d7641ce9-9411-432c-bb25-240ce7dd3cef",
  "card_brand": "visa",
  "card_last_four": "3191",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "status": "active",
  "created_at": "2026-03-21T14:30:00-03:00"
}

---

HTTP 状态码

状态码	说明
200	卡片令牌化成功
400	卡片数据无效或缺少必填字段
401	Bearer Token（持有者令牌）无效或已过期
403	该钱包权限不足
404	钱包未找到
409	该卡片已在此钱包中完成令牌化
422	卡片验证失败（卡号无效、已过期）
429	超出速率限制
500	服务器内部错误 - 请使用指数退避重试

---

代码示例

cURL

curl -s -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/tokenization/ \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 880e8400-e29b-41d4-a716-446655440003" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_uuid": "d6f921ef-5bdd-4ebf-a065-bd38de839bd1",
    "card": {
      "holder_name": "张伟",
      "number": "4024007153763191",
      "expiry_month": "12",
      "expiry_year": "2030",
      "cvv": "123"
    }
  }'

Python

import requests
import os

token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://sandbox.api.a55.tech")

try:
    response = requests.post(
        f"{base}/api/v1/bank/wallet/tokenization/",
        json={
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "merchant_uuid": "d6f921ef-5bdd-4ebf-a065-bd38de839bd1",
            "card": {
                "holder_name": "张伟",
                "number": "4024007153763191",
                "expiry_month": "12",
                "expiry_year": "2030",
                "cvv": "123",
            },
        },
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Idempotency-Key": "880e8400-e29b-41d4-a716-446655440003",
        },
    )
    response.raise_for_status()
    result = response.json()
    print(f"令牌：{result['token_uuid']}——卡组织：{result['card_brand']}")
    print(f"卡号：****{result['card_last_four']} 有效期 {result['card_expiry_month']}/{result['card_expiry_year']}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"请求失败：{e}")

Node.js

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://sandbox.api.a55.tech";

try {
  const response = await fetch(`${base}/api/v1/bank/wallet/tokenization/`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "880e8400-e29b-41d4-a716-446655440003",
    },
    body: JSON.stringify({
      wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      merchant_uuid: "d6f921ef-5bdd-4ebf-a065-bd38de839bd1",
      card: {
        holder_name: "张伟",
        number: "4024007153763191",
        expiry_month: "12",
        expiry_year: "2030",
        cvv: "123",
      },
    }),
  });

  if (!response.ok) throw new Error(`请求失败（HTTP ${response.status}）：${await response.text()}`);
  const result = await response.json();
  console.log(`令牌：${result.token_uuid}——卡组织：${result.card_brand}`);
  console.log(`卡号：****${result.card_last_four} 有效期 ${result.card_expiry_month}/${result.card_expiry_year}`);
} catch (error) {
  console.error("令牌化失败：", error.message);
}

---

沙箱模拟

在沙箱中，令牌化结果遵循与收款相同的测试卡规则。成功注册返回 HTTP 200 和 token_uuid；失败返回 HTTP 400 和 card_tokenization_failed。

需要商户配置 tokenization_enabled: true。请联系客户经理启用。

---

错误响应示例

{
  "status": "error",
  "message": [
    {
      "code": "INVALID_CARD_NUMBER",
      "source": "validation",
      "description": "Card number failed Luhn check"
    }
  ]
}

---

创建收款 →使用 token_uuid 对卡片进行后续收款。BIN 查询 →在令牌化之前检查卡品牌和类型。零额授权 →验证卡片有效性而不产生扣款。