PayZu Docs

POST创建收款/charges GET查询循环扣款/charges/recurrences/{recurrentPaymentId}Webhooks 交易状态

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

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

循环扣款可能并非对所有账户开放。请咨询支持了解您账户的可用性。

创建循环扣款

循环扣款由一笔普通的信用卡收款(POST /charges)加上 recurrence 节点创建。

Request 中 recurrence 的字段:

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

循环扣款始终为一次性全额付款。installments 字段必须为 1,更大的值会被拒绝。

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

{
  "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" }
}

响应:

{
  "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,可用它进行对账。

生命周期

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

管理循环扣款

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

GET查询循环扣款/charges/recurrences/{recurrentPaymentId}PUT修改循环扣款金额/charges/recurrences/{recurrentPaymentId}/amount PUT停用循环扣款/charges/recurrences/{recurrentPaymentId}/deactivate PUT重新启用循环扣款/charges/recurrences/{recurrentPaymentId}/reactivate

查询循环扣款

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

{
  "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 并携带 recurrentPaymentId 过滤条件:

GET /charges?recurrentPaymentId={recurrentPaymentId}

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

修改金额

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

{ "amount": 12000 }

停用与重新启用

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

循环扣款

本页内容