# Assinaturas e Pix Automático

Cobre o mesmo cliente todo mês, trimestre ou ano sem montar um agendador no seu sistema. Você cadastra a assinatura uma vez (valor, pagador, primeiro vencimento, intervalo e antecedência) e a Calebe Pay emite a cobrança de cada ciclo: um boleto, um link de Pix, um débito por Pix Automático ou um débito automático no cartão salvo. Boleto e link de Pix são emitidos na criação; no cartão, o débito ocorre na data de cada vencimento, sem antecipação. Cada cobrança emitida é uma cobrança comum: aparece em `GET /v1/transactions`, usa as mesmas tarifas e o mesmo split e chega aos seus webhooks como `transaction.created` e `transaction.updated`.

O calendário é da Calebe Pay: não existe uma API de assinaturas do provedor de pagamento por trás. O contrato completo está no [OpenAPI](openapi.json), na tag Recorrências.

## Como funciona

| Método (`method`) | O que cada ciclo emite | Permissão da chave | Antecedência dos ciclos seguintes (`advance_days`) |
| --- | --- | --- | --- |
| `boleto` | Um boleto com vencimento no dia do ciclo | `boleto:write` | 0 a 30 dias |
| `pix` | Um link de pagamento válido até o fim do dia do vencimento. O QR Code nasce quando o pagador escolhe pagar | `pix:write` | 0 a 30 dias |
| `credit_card` | Débito automático no cartão salvo, em uma parcela por ciclo | `credit_card:write` | 0 (débito no vencimento) |
| `pix_automatic` | Um débito agendado no banco do pagador, com a autorização que ele deu uma vez | `pix:write` | 2 a 10 dias |

1. A primeira cobrança é emitida na criação da assinatura, com o primeiro vencimento: a resposta já mostra o calendário no ciclo seguinte (`cycle: 1`). No Pix Automático, o primeiro débito é agendado depois que o pagador aprova, a partir de 10 dias antes do primeiro vencimento, o prazo que o banco aceita.
2. Os ciclos seguintes ficam com o agendador, que confere as assinaturas a cada minuto e emite cada um a partir de `next_due_date` menos `advance_days`, no horário de Brasília.
3. A cobrança recebe a referência `sub_ID:AAAA-MM-DD` (o ID da assinatura e o vencimento do ciclo) e segue o mesmo caminho de `POST /v1/pix` e `POST /v1/boleto`: regra de roteamento, liberação de produção, tarifas, split e webhooks.
4. O calendário anda para o próximo ciclo. Emitir não é receber: o pagamento chega como `transaction.updated` com `status: paid`.

O dia do primeiro vencimento se repete em todos os ciclos. Nos meses menores vale o último dia do mês, e o dia original volta quando o mês permite: 31/01, 28/02, 31/03. `interval_months` vai de 1 a 120 (1 é mensal e 12 é anual); o Pix Automático aceita 1, 3, 6 ou 12.

Se a emissão falhar antes de a cobrança ser reservada (por exemplo, produção não liberada ou regra de roteamento ausente), a Calebe Pay tenta de novo a cada 15 minutos enquanto o ciclo ainda puder ser emitido, e o motivo fica em `last_error`. Vale também para a primeira cobrança. No cartão, a criação exige roteamento habilitado e autorização de produção; se esses requisitos faltarem, o cadastro é recusado. Um ciclo que não pode mais ser emitido é registrado como `skipped`, sem cobrança retroativa.

## Cartão com débito automático

Para tenants com cartão habilitado na regra de recebimento, a tela de Assinaturas oferece **Cartão de crédito**. Informe o cartão e confirme que o pagador autorizou o valor e a recorrência. O cartão fica cadastrado no cofre do provedor; a Calebe Pay guarda somente o token criptografado, vinculado à assinatura e à conta de recebimento original. Número e código de segurança nunca são armazenados nem retornados.

Na API, use `method: "credit_card"`, `advance_days: 0` e `credit_card` com `authorized: true`. Aceita um token reutilizável do mesmo provedor e conta, ou os dados do cartão para cadastrar no cofre. Nunca envie ambos; `installments` deve ser 1:

```json
{
  "token": "TOKEN_REUTILIZAVEL_DO_PROVEDOR",
  "installments": 1,
  "authorized": true
}
```

Esse objeto é o campo `credit_card` do pedido de assinatura; os demais campos seguem o exemplo abaixo. Para cadastrar o cartão diretamente, substitua `token` por `holder`, `number` (13 a 19 dígitos), `expiration` (`MM/AAAA`) e `security_code` (3 ou 4 dígitos). Em modo de teste, o cadastro e os débitos são simulados sem chamadas ao provedor. O cofre de produção não é chamado por configurações sandbox.

Se o primeiro vencimento for futuro, a criação retorna `cycle: 0` e o débito aguarda essa data. Se vencer hoje, a primeira tentativa é processada na criação. Os ciclos continuam usando as taxas, o split e os webhooks comuns. Uma cobrança recusada ou com resultado incerto fica marcada como requerendo atenção e nunca é reenviada automaticamente no mesmo ciclo. Consulte a transação para confirmar seu resultado.

Desabilitar o cartão ou alterar a conta de recebimento bloqueia novos débitos. Após mudança de conta, cadastre uma nova assinatura com autorização do pagador. Pausar ou cancelar interrompe os ciclos seguintes; vencimentos perdidos ficam sem cobrança retroativa.

## Criar uma assinatura

Envie `POST /v1/subscriptions` com `X-API-Key`, `Content-Type: application/json` e uma `Idempotency-Key` que você guardou junto do pedido. A chave define o tenant e o modo: não envie `tenant_id` nem `mode`.

```bash
curl -X POST "$CALEBE_API_URL/v1/subscriptions" \
  -H "X-API-Key: $CALEBE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: plano-pro-maria-1" \
  -d '{
  "name": "Plano Pro mensal",
  "description": "Mensalidade do Plano Pro",
  "amount": 15990,
  "method": "boleto",
  "first_due_date": "2026-11-10",
  "interval_months": 1,
  "advance_days": 5,
  "customer": {
    "name": "Maria Souza",
    "document": "52998224725",
    "email": "maria@example.com",
    "phone": "11999998888",
    "address": {
      "zip_code": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP"
    }
  }
}'
```

Use uma data futura ao executar o exemplo. A resposta `201` traz a assinatura com a primeira cobrança já emitida: `cycle: 1` e `next_due_date` no vencimento seguinte. Guarde `data.id`:

```json
{
  "data": {
    "id": "sub_exemplo",
    "tenant_id": "ten_exemplo",
    "livemode": true,
    "status": "active",
    "name": "Plano Pro mensal",
    "customer_name": "Maria Souza",
    "amount": 15990,
    "method": "boleto",
    "description": "Mensalidade do Plano Pro",
    "first_due_date": "2026-11-10",
    "next_due_date": "2026-12-10",
    "interval_months": 1,
    "advance_days": 5,
    "cycle": 1,
    "authorization_id": null,
    "callback_url": null,
    "last_error": null,
    "next_attempt_at": "2026-10-01T12:00:00Z",
    "created_at": "2026-10-01T12:00:00Z",
    "updated_at": "2026-10-01T12:00:00Z"
  }
}
```

| Campo | Regra |
| --- | --- |
| `name` | Obrigatório, até 100 caracteres. |
| `description` | Descrição de cada cobrança, até 200 caracteres. |
| `amount` | Valor de cada ciclo em centavos, de 1 a 100000000. `15990` é R$ 159,90. |
| `method` | `boleto`, `pix` ou `pix_automatic`. |
| `first_due_date` | `AAAA-MM-DD`, de hoje em diante no horário de Brasília. Em `boleto` e `pix`, até 365 dias à frente, porque a primeira cobrança é emitida na criação; no Pix Automático, ao menos 2 dias à frente. |
| `interval_months` | 1 a 120; no Pix Automático, 1, 3, 6 ou 12. |
| `advance_days` | Antecedência dos ciclos seguintes: 0 a 30; no Pix Automático, 2 a 10. A primeira cobrança não espera por ela. |
| `customer` | Pagador completo: nome, CPF ou CNPJ sem pontuação, e-mail, telefone só com dígitos e endereço brasileiro. Diferente do Pix avulso, não usa o pagador padrão do tenant: os mesmos dados valem para todos os ciclos. |
| `authorization_id` | Obrigatório com `pix_automatic` e proibido nos outros métodos. |
| `callback_url` | Opcional. Endereço https que recebe os eventos das cobranças desta assinatura, além dos webhooks cadastrados. |

Repetir o envio com a mesma `Idempotency-Key` e o mesmo corpo devolve a mesma assinatura com `200` e o cabeçalho `Idempotency-Replayed: true`. A mesma chave com outro corpo é `409 idempotency_conflict`, e a repetição nunca emite outra primeira cobrança. Se a primeira cobrança não sair na criação (produção não liberada, regra de roteamento ausente), a assinatura existe mesmo assim, com o motivo em `last_error` e nova tentativa a cada 15 minutos. Revogar a chave de API não interrompe a assinatura: pause ou cancele.

O boleto de um ciclo sai com o vencimento do ciclo e sem instrução, multa ou juros, acompanhado do [Pix do mesmo valor](./boleto.md#pix-no-boleto) quando o Pix pode ser emitido. O link de Pix fica aberto até o fim do dia do vencimento; se o Pix gerado expirar sem pagamento antes disso, o link volta a oferecer o pagamento.

## Acompanhar os ciclos

`GET /v1/subscriptions/{id}/cycles` lista os ciclos do mais recente ao mais antigo, com a cobrança de cada um e o link para enviar ao pagador.

```json
{
  "data": [
    {
      "id": "scy_exemplo",
      "subscription_id": "sub_exemplo",
      "cycle": 0,
      "due_date": "2026-11-10",
      "status": "created",
      "transaction_id": "txn_exemplo",
      "checkout_id": null,
      "transaction_status": "pending",
      "payment_url": "https://api.calebepay.com.br/cobranca/txn_exemplo/c2lnbmF0dXJh",
      "error_code": null,
      "created_at": "2026-11-05T03:00:00Z",
      "updated_at": "2026-11-05T03:00:00Z"
    }
  ],
  "meta": { "limit": 50, "offset": 0, "count": 1 }
}
```

| `status` do ciclo | O que quer dizer |
| --- | --- |
| `created` | A cobrança (ou o link de Pix) foi emitida. Não é pagamento: leia `transaction_status`. |
| `attention` | A cobrança foi reservada, mas terminou recusada ou sem resultado confirmado. Acompanhe a transação e não emita outra para o mesmo ciclo. |
| `skipped` | O ciclo não será cobrado. `error_code` diz por quê. |
| `pending` | A emissão está em andamento. |

`payment_url` é o link do checkout (Pix) ou o documento da cobrança (boleto e Pix Automático), no domínio da Calebe Pay. A Calebe Pay não envia o link por e-mail ou WhatsApp: mande-o pelo seu canal. No método `pix`, `transaction_id` e `transaction_status` aparecem quando o pagador escolhe pagar no link.

| `error_code` | Motivo |
| --- | --- |
| `cycle_overdue` | O vencimento passou sem emissão, por exemplo durante uma pausa. |
| `automatic_schedule_window` | Faltavam menos de 2 dias para o vencimento: o banco não aceita mais o agendamento. |
| `automatic_authorization_cancelled` | O pagador ou você cancelou a autorização de Pix Automático. |
| `automatic_authorization_expired` | A autorização expirou sem aprovação ou chegou ao fim. |
| `automatic_charge_exists` | O vencimento já tinha um débito agendado fora da assinatura. |
| `payment_unknown` / `payment_processing` | A cobrança foi reservada sem resultado confirmado. |
| `provider_rejected` | O provedor de pagamento recusou a cobrança. |

A assinatura em si também traz o último motivo em `last_error`, inclusive das tentativas que ainda vão se repetir, como `automatic_not_approved` (aguardando o pagador aprovar) ou `live_payments_disabled` (produção não liberada).

## Pix Automático

No Pix Automático, o pagador autoriza uma vez no aplicativo do banco e os débitos seguintes acontecem sem ele precisar pagar de novo. A autorização tem valor fixo, calendário em meses e não tem cobrança imediata nem nova tentativa do banco quando falta saldo.

### 1. Peça a autorização

```bash
curl -X POST "$CALEBE_API_URL/v1/pix-automatic/authorizations" \
  -H "X-API-Key: $CALEBE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: autorizacao-plano-pro-maria-1" \
  -d '{
  "name": "Plano Pro mensal",
  "description": "Mensalidade do Plano Pro",
  "amount": 15990,
  "first_due_date": "2026-11-10",
  "interval_months": 1,
  "customer": {
    "name": "Maria Souza",
    "document": "52998224725",
    "email": "maria@example.com",
    "phone": "11999998888",
    "address": { "zip_code": "01310100", "street": "Avenida Paulista", "number": "1000", "district": "Bela Vista", "city": "São Paulo", "state": "SP" }
  }
}'
```

A chave precisa de `pix:write`. `first_due_date` precisa estar ao menos 2 dias à frente, porque cada débito é agendado de 2 a 10 dias antes do vencimento. A resposta `201` traz `status: pending` e `copy_paste`, o código Pix que o pagador aprova. Em produção, a autorização usa a regra de roteamento Pix do seu tenant e a liberação de produção; a conta que recebe a autorização é a mesma que agenda os débitos.

Uma recusa confirmada do provedor de pagamento volta `201` com `status: failed`. Um resultado sem confirmação volta `202` com `status: unknown`: consulte a autorização e não crie outra para o mesmo contrato.

### 2. O pagador aprova no banco

Mostre `copy_paste` ao pagador como QR Code (gere a imagem a partir do texto) ou como texto para copiar. Ele tem **24 horas** para aprovar; depois disso a autorização expira.

`GET /v1/pix-automatic/authorizations/{id}` lê o registro local. Para saber se o pagador aprovou, chame `POST /v1/pix-automatic/authorizations/{id}/refresh`, que consulta o provedor de pagamento e grava o estado.

| `status` | O que quer dizer |
| --- | --- |
| `pending` | Aguardando o pagador aprovar. |
| `approved` | Aprovada: os débitos podem ser agendados. |
| `expired` | Não foi aprovada a tempo ou chegou ao fim. Definitivo. |
| `cancelled` | Cancelada por você ou pelo pagador no banco. Definitivo. |
| `failed` | O provedor recusou a criação. |
| `unknown` / `processing` | A criação ficou sem resultado confirmado. Consulte antes de qualquer nova tentativa. |

Não há evento de webhook para a autorização nesta versão: consulte com `refresh`.

### 3. Crie a assinatura com a autorização

Envie `POST /v1/subscriptions` com `method: "pix_automatic"`, `authorization_id` e os mesmos `amount`, `customer.document`, `first_due_date` e `interval_months` da autorização, com `advance_days` de 2 a 10. Você pode criar a assinatura enquanto a autorização ainda está `pending`: a Calebe Pay consulta a autorização a cada 15 minutos e agenda o primeiro débito assim que ela estiver aprovada, a partir de 10 dias antes do primeiro vencimento e desde que ainda faltem 2 dias para ele. Os débitos seguintes são agendados `advance_days` antes de cada vencimento. Um `refresh` seu que encontre a aprovação antecipa essa tentativa para o minuto seguinte. Cada autorização atende uma única assinatura.

### Agendar débitos sem assinatura

Se você controla o próprio calendário, agende cada débito com `POST /v1/pix-automatic/charges`, informando `authorization_id`, `due_date` (um vencimento do calendário autorizado, de 2 a 10 dias à frente), `amount`, `reference`, `description` e `customer` com o mesmo documento da autorização. Cada autorização aceita um débito por vencimento: um segundo pedido para a mesma data é `409 automatic_charge_exists`.

### Como o débito é confirmado

O débito agendado é uma transação com `method: pix`, `pix_automatic_authorization_id`, `scheduled_due_date` e `expires_at` nulo. `status: pending` quer dizer débito agendado, não pago: não mostre QR Code nem peça outro Pix ao pagador. A partir da data do débito, a Calebe Pay confere o pagamento com o provedor de pagamento a cada 5 minutos por 3 dias e depois a cada hora, até 30 dias; o resultado chega como `transaction.updated`, com `paid` quando o dinheiro entrou. Você também pode consultar a qualquer momento com `POST /v1/transactions/{id}/refresh`.

### Revogar a autorização

`DELETE /v1/pix-automatic/authorizations/{id}` cancela o consentimento e nenhum débito novo pode ser agendado. Não estorna débitos já feitos. A assinatura ligada continua existindo e passa a registrar os ciclos como `skipped` com `automatic_authorization_cancelled`: cancele-a também, se for o caso. O pagador também pode cancelar pelo aplicativo do banco. Enquanto houver um débito em processamento ou sem resultado confirmado, a revogação responde `409 reconciliation_required`.

## Centro de custo

Envie opcionalmente `cost_center_id` na criação da assinatura. O centro deve estar ativo e pertencer ao tenant; caso contrário, a resposta é `422 invalid_cost_center`. O campo entra na idempotência e aparece nas respostas com `cost_center_name` (nome atual). Omitir mantém a assinatura sem classificação.

Cada novo ciclo herda o centro: boleto, cartão, débito de Pix Automático ou checkout de Pix. O centro do checkout passa para a transação quando o pagador escolhe pagar. Desativar um centro já vinculado preserva a classificação e a continuidade da assinatura.

Para mudar o centro dos próximos ciclos, use `PATCH /v1/subscriptions/{id}` com `{"cost_center_id":"cc_..."}`; `{"cost_center_id":null}` remove a classificação. Pode enviar `status` junto. São exigidos os mesmos escopos de escrita do método da assinatura. Uma emissão em andamento termina antes da alteração; cobranças e links já emitidos conservam o centro anterior.

No portal, o campo está em **Nova assinatura**. Nas assinaturas existentes, abra **Ciclos** e use **Alterar centro de custo**. A classificação não altera o calendário, o valor ou os repasses.

## Pausar, retomar e cancelar

`PATCH /v1/subscriptions/{id}` com `{"status": "paused"}`, `{"status": "active"}` ou `{"status": "cancelled"}`. A mudança afeta só as próximas emissões: cobranças já emitidas continuam valendo, e a autorização de Pix Automático continua ativa até você revogá-la. Uma emissão em andamento termina antes da mudança.

Ao retomar, os ciclos cujo vencimento já passou ficam `skipped` com `cycle_overdue`, sem cobrança retroativa. `cancelled` é definitivo: uma assinatura cancelada não volta a `active` nem a `paused` (`409 subscription_cancelled`). Retomar uma assinatura de Pix Automático com a autorização expirada ou cancelada é `409 automatic_not_available`.

A administração da Calebe Pay pode excluir uma assinatura pelo painel, por exemplo uma criada por engano. A exclusão apaga a assinatura e os ciclos: nenhum ciclo novo é emitido, e a consulta passa a responder `404 not_found`. As cobranças já emitidas continuam em `GET /v1/transactions`, valendo para o pagador e com a referência `sub_ID:AAAA-MM-DD`, e a autorização de Pix Automático não é revogada.

## Teste antes de cobrar

Com uma chave de teste (`cp_test_`), assinaturas, autorizações e cobranças são de teste (`livemode: false`) e nada chega ao provedor de pagamento.

1. Crie uma assinatura de boleto ou Pix: a primeira cobrança sai na própria criação, e a resposta traz `cycle: 1`.
2. Liste os ciclos e pegue `transaction_id` (no método `pix`, abra `payment_url` e escolha pagar para gerar a cobrança).
3. Simule o pagamento com `POST /v1/transactions/{id}/simulate` e `{"status":"paid"}`. Seu webhook de teste recebe `transaction.updated`.
4. No Pix Automático, simule a aprovação com `POST /v1/pix-automatic/authorizations/{id}/simulate` e `{"status":"approved"}` (ou `cancelled` e `expired` para testar o encerramento). O `copy_paste` de teste é um marcador que nenhum banco aceita.

## Permissões e hierarquia

| Operação | Permissão |
| --- | --- |
| Criar, pausar, retomar e cancelar assinatura | `pix:write` (Pix e Pix Automático) ou `boleto:write` (boleto) |
| Pedir, consultar no provedor, simular e revogar autorização; agendar débito | `pix:write` |
| Listar e consultar assinaturas, ciclos e autorizações | `transactions:read` |

Uma chave de teste só enxerga registros de teste, e uma de produção, os de produção. As listas mostram o tenant da chave; `include_descendants=true` inclui os tenants abaixo dele e `tenant_id` escolhe um deles. A chave lê a árvore, mas só altera recursos do próprio tenant: pausar a assinatura de um tenant filho ou revogar a autorização dele responde `403 forbidden`. `GET /v1/subscriptions` aceita também `status` (`active`, `paused` ou `cancelled`). Todas as listas usam `limit` (até 100) e `offset`.

## Erros

| HTTP | `code` | O que fazer |
| --- | --- | --- |
| 400 | `idempotency_key_required` | Envie `Idempotency-Key` com 1 a 128 caracteres. |
| 403 | `insufficient_scope` | Use uma chave com a permissão do método. |
| 403 | `forbidden` | O recurso é de um tenant descendente: altere-o com a chave dele. |
| 403 | `live_payments_disabled` | A produção ainda não foi liberada para a sua conta. |
| 404 | `not_found` | ID inexistente, de outro tenant ou do outro modo (teste ou produção). |
| 409 | `idempotency_conflict` | A chave já foi usada com outro corpo. |
| 409 | `automatic_authorization_in_use` | A autorização já pertence a outra assinatura. |
| 409 | `automatic_charge_exists` | Já existe um débito para esse vencimento. |
| 409 | `subscription_cancelled` | Assinatura cancelada não é reativada. |
| 409 | `automatic_not_available` | A autorização está encerrada. |
| 409 | `reconciliation_required` | Há um resultado sem confirmação; consulte antes de repetir. |
| 422 | `validation_error` | A mensagem diz qual campo corrigir. |
| 422 | `automatic_contract_mismatch` | Valor, documento, primeiro vencimento ou intervalo diferentes da autorização. |
| 422 | `automatic_not_approved` | O pagador ainda não aprovou. |
| 422 | `automatic_schedule_window` | O débito precisa estar de 2 a 10 dias à frente. |
| 422 | `automatic_calendar_mismatch` | A data não é um vencimento do calendário autorizado. |
| 422 | `automatic_routing_changed` | A regra Pix do tenant passou a usar outra conta; peça uma nova autorização. |
| 422 | `automatic_provider_unavailable` | A regra Pix do tenant não usa o provedor de produção. |
| 502 | `provider_refresh_failed` / `provider_cancel_unconfirmed` | O provedor não respondeu ou não confirmou; consulte com `refresh` antes de repetir. |

## Referência rápida

| Operação | Endpoint |
| --- | --- |
| Criar assinatura | `POST /v1/subscriptions` |
| Listar assinaturas | `GET /v1/subscriptions` |
| Consultar assinatura | `GET /v1/subscriptions/{id}` |
| Pausar, retomar ou cancelar | `PATCH /v1/subscriptions/{id}` |
| Listar ciclos | `GET /v1/subscriptions/{id}/cycles` |
| Pedir autorização de Pix Automático | `POST /v1/pix-automatic/authorizations` |
| Listar autorizações | `GET /v1/pix-automatic/authorizations` |
| Consultar autorização (local) | `GET /v1/pix-automatic/authorizations/{id}` |
| Consultar autorização no provedor | `POST /v1/pix-automatic/authorizations/{id}/refresh` |
| Simular a resposta do pagador (teste) | `POST /v1/pix-automatic/authorizations/{id}/simulate` |
| Revogar autorização | `DELETE /v1/pix-automatic/authorizations/{id}` |
| Agendar um débito avulso | `POST /v1/pix-automatic/charges` |

No painel, o mesmo fluxo fica em **Assinaturas**: criar, acompanhar ciclos, copiar links, pausar, retomar, cancelar e mostrar o QR Code da autorização ao pagador.

## SDK TypeScript

O SDK oferece `createSubscription`, `getSubscription`, `listSubscriptions`, `updateSubscription`, `listSubscriptionCycles`, `createAutomaticAuthorization`, `getAutomaticAuthorization`, `listAutomaticAuthorizations`, `refreshAutomaticAuthorization`, `simulateAutomaticAuthorization`, `cancelAutomaticAuthorization` e `createAutomaticCharge`. Nenhum método repete uma chamada sozinho: guarde o corpo e a `Idempotency-Key` de cada criação e repita os dois juntos depois de um timeout.

## Estornar ou alterar uma cobrança do ciclo

Leia `transaction_id` em `GET /v1/subscriptions/{id}/cycles`; nos ciclos de Pix, ele aparece depois que o pagador escolhe pagar pelo checkout. Use esse ID em `POST /v1/transactions/{id}/refund` para estorno integral, ou em `PATCH /v1/transactions/{id}/boleto` para mudar o vencimento de um boleto em aberto. Ambas exigem `Idempotency-Key` e os escopos da cobrança; veja [estornos e vencimento](operations.md#estornos-e-vencimento).

No painel, abra **Ciclos → Gerenciar cobrança**. O estorno atua no pagamento escolhido e não interrompe os próximos ciclos. A mudança de vencimento altera o boleto desse ciclo; o vencimento original do ciclo continua como referência do calendário da assinatura.