跳转到主要内容

订阅

Quick Reference

What信用卡循环扣款
Why自动化计费周期——A55 托管或商户自控
Difficulty中级
Prerequisites身份验证 → 创建扣款

在扣款请求中附加 subscription 对象即可创建循环扣款。A55 支持两种循环策略，具体取决于您需要的控制程度。

仅限单期

订阅仅允许信用卡单期交易。

为什么使用订阅​

优势说明
持续收入自动化计费，无需手动创建扣款
灵活周期每周、每两周、每月、每季、每半年、每年
CIT（持卡人发起交易）/ MIT（商户发起交易）合规符合卡组织规则的交易发起方指示符
三种卡片输入方式原始 PAN、DPAN + 密码学凭证、A55 令牌
Webhook（网络钩子）通知每次扣款尝试和生命周期变更都有事件通知

循环模式​

模式谁调度扣款MIT 指示符重试管理
内部（A55 控制）A55 按周期自动生成扣款不使用A55 处理
外部（商户控制）商户触发每次扣款需要 C1 / M1商户处理

内部循环（A55 控制）​

A55 根据计费周期自动创建扣款，商户无需额外操作。

计费周期​

周期间隔
weekly每 7 天
biweekly每 14 天
monthly每月
quarterly每 3 个月
semiannually每 6 个月
yearly每年

创建订阅（内部）​

{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "张伟",
  "payer_tax_id": "12345678901",
  "payer_email": "zhangwei@example.com",
  "payer_cell_phone": "+5511999999999",
  "items": [{"name": "高级套餐", "quantity": 1, "total_amount": 99.90, "unit_amount": 99.90}],
  "currency": "BRL",
  "installment_value": 99.90,
  "due_date": "2026-12-31",
  "description": "每月高级订阅",
  "type_charge": "credit_card",
  "card_name": "ZHANG WEI",
  "card_number": "4111111111111111",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "card_cvv": "123",
  "subscription": {
    "cycle": "monthly",
    "end_date": "2027-06-30"
  },
  "webhook_url": "https://merchant.example/webhooks/a55"
}

外部循环（商户控制）​

商户控制每次扣款的时机。适用于 CRM 驱动计费、可变金额或自定义重试逻辑。

交易发起方指示符​

指示符含义使用时机
C1持卡人发起交易首次订阅付款（持卡人在场）
M1商户发起循环扣款所有后续付款

首次付款（CIT）​

{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "张伟",
  "payer_tax_id": "12345678901",
  "payer_email": "zhangwei@example.com",
  "currency": "BRL",
  "installment_value": 99.90,
  "type_charge": "credit_card",
  "card_name": "ZHANG WEI",
  "card_number": "4111111111111111",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "card_cvv": "123",
  "subscription": {
    "external_recurrence": true,
    "initiated_transaction_indicator_category": "C1"
  },
  "webhook_url": "https://merchant.example/webhooks/a55"
}

后续扣款（MIT）​

引用初始付款的 cit_charge_uuid 并切换为 M1：

{
  "wallet_uuid": "00000000-0000-4000-8000-000000000001",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "payer_name": "张伟",
  "currency": "BRL",
  "installment_value": 99.90,
  "type_charge": "credit_card",
  "card_token": "7c2a9b6e-4f6a-4e3d-9d8b-0e3f9c6b1a42",
  "subscription": {
    "cit_charge_uuid": "ce4ccc7f-d3f7-46eb-a912-d4a6bc0423d1",
    "external_recurrence": true,
    "initiated_transaction_indicator_category": "M1"
  },
  "webhook_url": "https://merchant.example/webhooks/a55"
}

订阅状态生命周期​

状态描述
pending初始付款尚未确认
active订阅运行中，正在生成扣款
error上次扣款尝试失败
cancelled由商户或客户手动取消
expired已到结束日期或重试次数耗尽

查询订阅​

GET /api/v1/bank/wallet/subscription/?wallet_uuid={WALLET_UUID}&subscription_uuid={SUBSCRIPTION_UUID}

{
  "subscription_uuid": "b13216d0-1054-4353-9c47-ef12824e262a",
  "cycle": "monthly",
  "end_date": "2027-06-30",
  "status": "active",
  "next_due_date": "2026-04-30",
  "charges": [
    {
      "charge_uuid": "e7a22849-5a1b-41c8-b244-f7b8f2acfa1f",
      "value": 99.90,
      "currency": "BRL",
      "status": "confirmed"
    }
  ]
}

取消订阅​

DELETE /api/v1/bank/wallet/subscription/{subscription_uuid}/cancel/{wallet_uuid}/

{
  "subscription_uuid": "b13216d0-1054-4353-9c47-ef12824e262a",
  "status": "cancelled"
}
待处理扣款

取消操作会停止未来的计费周期。已结算的扣款按您的协议保持不变。请对账 Webhook 事件并相应地更新权限。

零额验证 →在存储卡片前验证有效性。卡片令牌化 →用于卡片存档续费的令牌。Webhook 概述 →监听订阅生命周期事件。