卡片令牌化

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)	是	关联令牌的钱包
card_number	string	是	卡号 PAN（例如 4024007153763191）
card_name	string	是	卡面上印刷的持卡人姓名
card_expiry_month	string	是	有效期月份 MM（例如 12）
card_expiry_year	string	是	有效期年份 YYYY（例如 2030）
card_cvv	string	是	卡片验证码
payer_tax_id	string	是	持卡人税号（CPF、RFC、RUT、CUIT）
payer_email	string	否	持卡人电子邮箱，用于通知

卡片数据处理

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

---

响应字段

字段	类型	说明
token_uuid	string	可复用的令牌标识符，用于后续收款
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 创建时间戳

---

HTTP 状态码

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

---

代码示例

cURL

curl -s -X POST https://core-manager.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",
    "card_number": "4024007153763191",
    "card_name": "张伟",
    "card_expiry_month": "12",
    "card_expiry_year": "2030",
    "card_cvv": "123",
    "payer_tax_id": "123.456.789-09",
    "payer_email": "zhangwei@example.com"
  }'

Python

import requests
import os

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

try:
    response = requests.post(
        f"{base}/api/v1/bank/wallet/tokenization/",
        json={
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "card_number": "4024007153763191",
            "card_name": "张伟",
            "card_expiry_month": "12",
            "card_expiry_year": "2030",
            "card_cvv": "123",
            "payer_tax_id": "123.456.789-09",
            "payer_email": "zhangwei@example.com",
        },
        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://core-manager.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",
      card_number: "4024007153763191",
      card_name: "张伟",
      card_expiry_month: "12",
      card_expiry_year: "2030",
      card_cvv: "123",
      payer_tax_id: "123.456.789-09",
      payer_email: "zhangwei@example.com",
    }),
  });

  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);
}

---

错误响应示例

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

---

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