创建订阅
POST
/api/v1/bank/wallet/charge/Bearer Token通过收款端点创建订阅
订阅是通过在创建收款请求体中包含 subscription 对象来创建的。首次收款会立即处理，后续收款将根据计费周期自动创建。
请求头
| 请求头 | 值 | 必填 |
|---|---|---|
Authorization | Bearer {A55_ACCESS_TOKEN} | 是 |
Content-Type | application/json | 是 |
Idempotency-Key（幂等键） | UUID v4 | 建议 |
请求体
所有创建收款的字段均适用，另加 subscription 对象：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type_charge | string | 是 | 必须为 credit_card 或 debit_card |
subscription.cycle | string | 是 | 计费周期——见下表 |
subscription.end_date | string | 否 | 结束日期 YYYY-MM-DD（省略则为无限期） |
计费周期
| 周期 | 说明 | 收款频率 |
|---|---|---|
weekly | 每 7 天 | 52 次/年 |
biweekly | 每 14 天 | 26 次/年 |
monthly | 每月同一天 | 12 次/年 |
quarterly | 每 3 个月 | 4 次/年 |
semiannually | 每 6 个月 | 2 次/年 |
yearly | 每年一次 | 1 次/年 |
响应字段
所有创建收款的响应字段，另加：
| 字段 | 类型 | 说明 |
|---|---|---|
subscription.subscription_uuid | string | 唯一订阅标识符 |
subscription.cycle | string | 计费周期 |
subscription.status | string | 创建时为 active |
subscription.next_charge_date | string | 下次自动收款日期 |
subscription.end_date | string | 订阅结束日期（无限期时为 null） |
HTTP 状态码
| 状态码 | 说明 |
|---|---|
| 200 | 订阅已创建且首次收款已处理 |
| 400 | 无效的订阅周期或缺少必填字段 |
| 401 | Bearer Token（持有者令牌）无效或已过期 |
| 403 | 该钱包权限不足 |
| 404 | 钱包未找到 |
| 409 | 重复（相同的 Idempotency-Key） |
| 422 | 验证错误（无效卡片、周期、日期） |
| 429 | 超出速率限制 |
| 500 | 服务器内部错误 - 请使用指数退避重试 |
代码示例
- cURL
- Python
- Node.js
curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/ \
-H "Authorization: Bearer $A55_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: aa0e8400-e29b-41d4-a716-446655440005" \
-d '{
"wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"merchant_id": "11111111-1111-1111-1111-111111111111",
"payer_name": "张伟",
"payer_email": "zhangwei@example.com",
"payer_tax_id": "123.456.789-09",
"payer_cell_phone": "+5511999999999",
"installment_value": 49.90,
"installment_count": 1,
"currency": "BRL",
"due_date": "2026-12-31",
"description": "高级计划——月度订阅",
"type_charge": "credit_card",
"card_number": "4024007153763191",
"card_name": "张伟",
"card_expiry_month": "12",
"card_expiry_year": "2030",
"card_cvv": "123",
"subscription": {
"cycle": "monthly",
"end_date": "2027-12-31"
},
"webhook_url": "https://your-app.com/webhooks/a55",
"payer_address": {
"street": "Av. Paulista",
"address_number": "1000",
"complement": "Sala 101",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"postal_code": "01310-100",
"country": "BR"
}
}'
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/charge/",
json={
"wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"merchant_id": "11111111-1111-1111-1111-111111111111",
"payer_name": "张伟",
"payer_email": "zhangwei@example.com",
"payer_tax_id": "123.456.789-09",
"payer_cell_phone": "+5511999999999",
"installment_value": 49.90,
"installment_count": 1,
"currency": "BRL",
"due_date": "2026-12-31",
"description": "高级计划——月度订阅",
"type_charge": "credit_card",
"card_number": "4024007153763191",
"card_name": "张伟",
"card_expiry_month": "12",
"card_expiry_year": "2030",
"card_cvv": "123",
"subscription": {
"cycle": "monthly",
"end_date": "2027-12-31",
},
"webhook_url": "https://your-app.com/webhooks/a55",
"payer_address": {
"street": "Av. Paulista",
"address_number": "1000",
"complement": "Sala 101",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"postal_code": "01310-100",
"country": "BR",
},
},
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
"Idempotency-Key": "aa0e8400-e29b-41d4-a716-446655440005",
},
)
response.raise_for_status()
charge = response.json()
sub = charge.get("subscription", {})
print(f"收款：{charge['charge_uuid']}——状态：{charge['status']}")
print(f"订阅：{sub.get('subscription_uuid')}——下次扣款：{sub.get('next_charge_date')}")
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}")
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/charge/`, {
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
"Idempotency-Key": "aa0e8400-e29b-41d4-a716-446655440005",
},
body: JSON.stringify({
wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
merchant_id: "11111111-1111-1111-1111-111111111111",
payer_name: "张伟",
payer_email: "zhangwei@example.com",
payer_tax_id: "123.456.789-09",
payer_cell_phone: "+5511999999999",
installment_value: 49.90,
installment_count: 1,
currency: "BRL",
due_date: "2026-12-31",
description: "高级计划——月度订阅",
type_charge: "credit_card",
card_number: "4024007153763191",
card_name: "张伟",
card_expiry_month: "12",
card_expiry_year: "2030",
card_cvv: "123",
subscription: { cycle: "monthly", end_date: "2027-12-31" },
webhook_url: "https://your-app.com/webhooks/a55",
payer_address: {
street: "Av. Paulista",
address_number: "1000",
complement: "Sala 101",
neighborhood: "Bela Vista",
city: "São Paulo",
state: "SP",
postal_code: "01310-100",
country: "BR",
},
}),
});
if (!response.ok) throw new Error(`请求失败（HTTP ${response.status}）：${await response.text()}`);
const charge = await response.json();
console.log(`收款：${charge.charge_uuid}——状态：${charge.status}`);
console.log(`订阅：${charge.subscription?.subscription_uuid}——下次扣款：${charge.subscription?.next_charge_date}`);
} catch (error) {
console.error("订阅创建失败：", error.message);
}
错误响应示例
{
"charge_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "error",
"message": [
{
"code": "INVALID_SUBSCRIPTION_CYCLE",
"source": "subscription",
"description": "Cycle 'daily' is not supported. Use: weekly, biweekly, monthly, quarterly, semiannually, yearly"
}
]
}