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, na tag Recorrências.

Como funciona

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:

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

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:

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

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 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.

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

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.

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

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.

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

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

Referência rápida

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.

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.