# 循环扣款 (/zh/docs/cartao/recurrence)

<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints/charges/post_charges" title="创建收款" method="POST" path="/charges" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/get_charges_recurrences__recurrentPaymentId_" title="查询循环扣款" method="GET" path="/charges/recurrences/{recurrentPaymentId}" />

  <QuickLink href="/docs/cartao/webhooks" title="Webhooks" />

  <QuickLink href="/docs/cartao/transaction-status" title="交易状态" />
</QuickLinks>

循环扣款就是一笔订阅:您在创建首笔收款时指定扣款周期,此后每个周期都会自动从客户的信用卡扣款,无需再次调用 API。

* **首笔收款**:即时创建,直接在 [`POST /charges`](/docs/cartao/endpoints/charges/post_charges) 的响应中返回。
* **后续周期**:按配置的周期(每月或每年)自动生成。
* 每个周期都会生成一笔关联到该循环扣款的收款,并以 `recurrenceCycle` 编号(`0` 为首笔,`1..n` 为后续周期)。
* 每个周期您都会在 `postbackUrl` 收到一个 [`recurrence.cycle`](/docs/cartao/webhooks) postback。

<Callout type="info">
  循环扣款可能并非对所有账户开放。请咨询支持了解您账户的可用性。
</Callout>

## 创建循环扣款 [#创建循环扣款]

循环扣款由一笔普通的信用卡收款([`POST /charges`](/docs/cartao/endpoints/charges/post_charges))加上 `recurrence` 节点创建。

Request 中 `recurrence` 的字段:

| 字段         | 类型        | 说明                                  |
| ---------- | --------- | ----------------------------------- |
| `interval` | string,必填 | `Monthly`(每月)或 `Annual`(每年)         |
| `endDate`  | string,可选 | 结束日期,格式 `YYYY-MM-DD`。不填时循环扣款将无限期持续。 |

<Callout type="warn">
  循环扣款始终为一次性全额付款。`installments` 字段必须为 `1`,更大的值会被拒绝。
</Callout>

Request 示例(金额以分为单位):

```json
{
  "amount": 10000,
  "paymentType": "creditcard",
  "externalId": "assinatura-123",
  "customer": { "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF" },
  "cart": [{ "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 }],
  "creditCardPayment": {
    "installments": 1,
    "authenticate": false,
    "card": { "number": "4111111111111111", "holder": "MARIA SOUZA", "expiration": "12/2030", "cvv": "123" }
  },
  "recurrence": { "interval": "Monthly", "endDate": "2027-06-12" }
}
```

响应:

```json
{
  "id": "uuid-da-cobranca",
  "amount": 10000,
  "creditCardPayment": { "status": 2, "acquirerTransactionId": "0725103012345" },
  "recurrence": {
    "recurrentPaymentId": "uuid-da-recorrencia",
    "interval": "MONTHLY",
    "status": "ACTIVE",
    "amount": 10000,
    "endDate": "2027-06-12T00:00:00.000Z",
    "nextRecurrency": "2026-07-12T00:00:00.000Z"
  },
  "recurrenceCycle": 0
}
```

响应中 `recurrence` 的字段:

| 字段                   | 说明                             |
| -------------------- | ------------------------------ |
| `recurrentPaymentId` | 循环扣款的标识符。用于各查询和管理 endpoint。    |
| `status`             | `ACTIVE`、`INACTIVE` 或 `ENDED`。 |
| `amount`             | 每个周期的金额,以分为单位。                 |
| `nextRecurrency`     | 下一次自动扣款的日期。                    |
| `endDate`            | 结束日期(若创建时提供)。                  |

## 周期如何运作 [#周期如何运作]

周期的执行不需要您做任何操作。每到一个周期,PayZu 会自动扣款并创建一笔关联到该循环扣款的新收款,`recurrenceCycle` 随之递增。每完成一个周期的扣款,PayZu 都会向您的 `postbackUrl` 发送 `recurrence.cycle` 事件的 postback,可用它进行对账。

## 生命周期 [#生命周期]

<Mermaid
  chart="`
stateDiagram-v2
  [*] --> ACTIVE: POST /charges 携带 recurrence
  ACTIVE --> ACTIVE: 新周期扣款 (recurrence.cycle)
  ACTIVE --> INACTIVE: PUT .../deactivate
  INACTIVE --> ACTIVE: PUT .../reactivate
  ACTIVE --> ENDED: 达到 endDate
  ENDED --> [*]
`"
/>

| 状态         | 含义                      |
| ---------- | ----------------------- |
| `ACTIVE`   | 生效中,按配置的周期持续生成扣款。       |
| `INACTIVE` | 已停用(手动或由发卡行停用)。不再生成新周期。 |
| `ENDED`    | 已因达到 `endDate` 而结束。     |

## 管理循环扣款 [#管理循环扣款]

使用创建时返回的 `recurrentPaymentId` 查询和管理订阅:

<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints/recurrences/get_charges_recurrences__recurrentPaymentId_" title="查询循环扣款" method="GET" path="/charges/recurrences/{recurrentPaymentId}" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__amount" title="修改循环扣款金额" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/amount" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__deactivate" title="停用循环扣款" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/deactivate" />

  <QuickLink href="/docs/cartao/endpoints/recurrences/put_charges_recurrences__recurrentPaymentId__reactivate" title="重新启用循环扣款" method="PUT" path="/charges/recurrences/{recurrentPaymentId}/reactivate" />
</QuickLinks>

### 查询循环扣款 [#查询循环扣款]

`GET /charges/recurrences/{recurrentPaymentId}` 返回循环扣款的当前状态:

```json
{
  "recurrentPaymentId": "uuid-da-recorrencia",
  "interval": "MONTHLY",
  "status": "ACTIVE",
  "amount": 10000,
  "nextRecurrency": "2026-07-12T00:00:00.000Z",
  "endDate": "2027-06-12T00:00:00.000Z"
}
```

### 列出循环扣款下的收款 [#列出循环扣款下的收款]

使用 [`GET /charges`](/docs/cartao/endpoints/charges/get_charges) 并携带 `recurrentPaymentId` 过滤条件:

```
GET /charges?recurrentPaymentId={recurrentPaymentId}
```

返回首笔收款以及已生成的全部周期(分页)。同时支持 `limit`、`page`、`startDate` 和 `endDate` 过滤参数。

### 修改金额 [#修改金额]

`PUT /charges/recurrences/{recurrentPaymentId}/amount` 修改后续扣款的金额。不影响已生成的周期。

```json
{ "amount": 12000 }
```

### 停用与重新启用 [#停用与重新启用]

* `PUT /charges/recurrences/{recurrentPaymentId}/deactivate` 中止循环扣款:不再生成新周期,状态变为 `INACTIVE`。
* `PUT /charges/recurrences/{recurrentPaymentId}/reactivate` 恢复已停用的循环扣款:状态回到 `ACTIVE`。