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. Cada ciclo emitido também chega como subscription.cycle_created, com o link do pagador, e o próprio pagador pode receber esse link por e-mail ou WhatsApp: veja Avisos de cada ciclo.
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
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 |
- 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. - Os ciclos seguintes ficam com o agendador, que confere as assinaturas a cada minuto e emite cada um a partir de
next_due_datemenosadvance_days, no horário de Brasília. - 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 dePOST /v1/pixePOST /v1/boleto: regra de roteamento, liberação de produção, tarifas, split e webhooks. - O calendário anda para o próximo ciclo. Emitir não é receber: o pagamento chega como
transaction.updatedcomstatus: 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, e um cartão terminado em 0002 (por exemplo 4000000000000002) é recusado em todos os ciclos, como um cartão sem limite. 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 até o cartão ser trocado. Pausar ou cancelar interrompe os ciclos seguintes; vencimentos perdidos ficam sem cobrança retroativa.
Trocar o cartão e cobrar de novo o mês recusado
Quando o débito de um ciclo é recusado (cartão vencido, bloqueado ou sem limite), o ciclo fica attention com transaction_status: failed em GET /v1/subscriptions/{id}/cycles, e o calendário segue para o próximo vencimento. Para receber o mês recusado:
- Peça ao pagador um novo cartão e a autorização dos débitos recorrentes nele.
- Troque o cartão com
PUT /v1/subscriptions/{id}/credit-card. O corpo é o mesmo objetocredit_cardda criação: um token reutilizável ou titular, número, validade e código de segurança, cominstallments: 1eauthorized: true. Nada é cobrado na troca; a resposta é a assinatura, comcard_authorized_atno momento da troca. Os próximos ciclos já usam o novo cartão. - Cobre de novo o ciclo recusado com
POST /v1/subscriptions/{id}/cycles/{cycle}/retry, sem corpo e com umaIdempotency-Keynova. Se o pagador preferir pagar esse mês por Pix ou boleto, veja Mudar de cartão para Pix ou boleto.
curl -X PUT "$CALEBE_API_URL/v1/subscriptions/sub_exemplo/credit-card" \
-H "X-API-Key: $CALEBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"token": "NOVO_TOKEN_REUTILIZAVEL_DO_PROVEDOR",
"installments": 1,
"authorized": true
}'
curl -X POST "$CALEBE_API_URL/v1/subscriptions/sub_exemplo/cycles/3/retry" \
-H "X-API-Key: $CALEBE_API_KEY" \
-H "Idempotency-Key: sub_exemplo-ciclo-3-tentativa-2"
A nova tentativa é uma cobrança comum, com a mesma referência sub_ID:AAAA-MM-DD do ciclo, as tarifas, o split e os webhooks de sempre, e passa a ser a cobrança do ciclo (transaction_id); a recusada continua em GET /v1/transactions. A resposta é a mesma de POST /v1/credit-card: 201 com a cobrança paga, 202 sem resultado confirmado e 502 provider_rejected numa nova recusa, com error.transaction_id. A mesma Idempotency-Key repete a resposta sem debitar de novo.
Só uma recusa confirmada reabre o ciclo. Um ciclo pago, pulado ou ainda sem cobrança responde 409 cycle_not_retryable, e uma cobrança ainda sem resultado confirmado (unknown ou processing) responde 409 cycle_payment_uncertain: ela pode estar paga, e outra tentativa cobraria o pagador duas vezes. Tentativas simultâneas no mesmo ciclo são serializadas, e só uma debita. A nova tentativa vale também para um ciclo com o vencimento já passado e para assinatura pausada; assinatura cancelada responde 409 subscription_cancelled.
Se a conta de recebimento de cartão da empresa mudou, os débitos param com subscription_card_routing_changed em last_error. Trocar o cartão cadastra o novo na conta atual e libera os débitos sem criar outra assinatura; um ciclo que ficou pendente por isso é tentado de novo no minuto seguinte.
Mudar de cartão para Pix ou boleto
A forma de pagamento não fica presa à criação: a cada ciclo a assinatura pode passar do cartão para Pix ou boleto, e voltar.
Para os próximos ciclos, envie method em PATCH /v1/subscriptions/{id}, com advance_days se quiser emitir antes do vencimento (0 a 30 em Pix e boleto):
curl -X PATCH "$CALEBE_API_URL/v1/subscriptions/sub_exemplo" \
-H "X-API-Key: $CALEBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"method":"boleto","advance_days":5}'
- A troca vale da próxima emissão em diante. Um ciclo já emitido não muda.
- A chave precisa da permissão de escrita da forma atual e da nova (
credit_card:write,pix:write,boleto:write). - O cartão salvo continua guardado:
{"method":"credit_card"}volta a ele sem pedir os dados de novo. Uma assinatura que nunca teve cartão responde422 subscription_card_required; cadastre-o comPUT /v1/subscriptions/{id}/credit-card, que já passa os próximos ciclos para o cartão. - No cartão o débito é no vencimento (
advance_daysvira 0) e não há link para o pagador: os avisos por e-mail e WhatsApp são desligados na ida para o cartão. Ligue-os de novo, se quiser, ao voltar para Pix ou boleto. - Assinatura de Pix Automático não troca de forma (
422 subscription_method_fixed): ela segue a autorização do pagador.
Só para um ciclo recusado no cartão, sem mexer na assinatura, envie method na nova tentativa:
curl -X POST "$CALEBE_API_URL/v1/subscriptions/sub_exemplo/cycles/3/retry" \
-H "X-API-Key: $CALEBE_API_KEY" \
-H "Idempotency-Key: ciclo-3-pix-1" \
-H "Content-Type: application/json" \
-d '{"method":"pix"}'
Com pix, a resposta é o link de pagamento (checkout_url); com boleto, a cobrança do boleto. O ciclo passa a apontar para essa cobrança, com a mesma referência sub_ID:AAAA-MM-DD, e payment_url em GET …/cycles traz o link para mandar ao pagador. O vencimento é o do ciclo ou, se ele já passou, hoje; due_date escolhe outra data, de hoje a 365 dias. Vale a mesma regra da nova tentativa no cartão: só um ciclo com transaction_status: failed é cobrado de novo.
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,
"promotional_amount": null,
"promotional_cycles": null,
"next_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,
"notifications": { "webhook": true, "email": false, "whatsapp": false },
"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 integral de cada ciclo em centavos, de 1 a 100000000. 15990 é R$ 159,90. |
promotional_amount |
Opcional. Valor promocional dos primeiros ciclos, em centavos, menor que amount. Veja Valor promocional nos primeiros ciclos. |
promotional_cycles |
Opcional. Quantos ciclos saem pelo valor promocional, de 1 a 120. Vem junto com promotional_amount. |
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 dos ciclos e das cobranças desta assinatura, além dos webhooks cadastrados. |
notifications |
Opcional. Como cada ciclo emitido é avisado: webhook (padrão true), email e whatsapp ao pagador (padrão false). Veja Avisos de cada ciclo. |
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.
Valor promocional nos primeiros ciclos
Para uma campanha em que o cliente paga menos nas primeiras mensalidades e depois passa ao valor do plano, informe três valores na criação: o valor integral em amount, o valor promocional em promotional_amount e a quantidade de ciclos promocionais em promotional_cycles. A Calebe Pay emite os primeiros ciclos pelo valor promocional e os seguintes pelo valor integral, na mesma assinatura e sem outra chamada. Quem entra na campanha, em que data e com qual desconto continua sendo decisão do seu sistema: a API recebe os valores já calculados, em centavos.
Um plano de R$ 100,00 com 20% de desconto nas três primeiras mensalidades:
{
"amount": 10000,
"promotional_amount": 8000,
"promotional_cycles": 3
}
Esses campos entram no pedido de POST /v1/subscriptions; os demais seguem o exemplo de Criar uma assinatura.
Ciclo (cycle) |
Cobrança | Valor |
|---|---|---|
0, 1 e 2 |
1ª, 2ª e 3ª | R$ 80,00 (promotional_amount) |
3 em diante |
4ª e seguintes | R$ 100,00 (amount) |
- Os dois campos vêm juntos: só um deles é
422 validation_error.promotional_amountvai de 1 centavo até um centavo abaixo deamount, epromotional_cycles, de 1 a 120. - Vale para
boleto,pixecredit_card, em qualquerinterval_months. No Pix Automático a autorização do pagador tem valor fixo, e a promoção é recusada com422 validation_error. - No cartão, a autorização do pagador (
authorized: true) precisa cobrir os dois valores. - A resposta traz
promotional_amountepromotional_cycles(os doisnullnuma assinatura sem promoção) enext_amount, o valor do próximo ciclo a emitir. EmGET /v1/subscriptions/{id}/cycles, cada ciclo traz oamountdele, o mesmo que vai no eventosubscription.cycle_created. - A promoção vale para os primeiros ciclos do calendário, contados do primeiro vencimento. Um ciclo não cobrado (
skipped) dentro dela, por exemplo durante uma pausa, conta como um dos ciclos promocionais. - Cobrar de novo um ciclo recusado no cartão (
POST …/cycles/{cycle}/retry) usa o valor daquele ciclo: um ciclo promocional continua promocional mesmo depois do fim da promoção. - Tarifas e split são calculados em cada cobrança, sobre o valor do ciclo.
- Os valores ficam definidos na criação e entram no hash de idempotência:
PATCHnão alteraamountnem a promoção. Para outro preço ou outra campanha, cancele a assinatura e crie outra.
No painel, os mesmos campos estão em Assinaturas → Nova assinatura: "Valor promocional" e "Ciclos promocionais", os dois opcionais.
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",
"amount": 15990,
"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,
"notifications": [
{ "channel": "email", "status": "sent", "error_code": null, "updated_at": "2026-11-05T03:00:40Z" }
],
"pending_notices": [],
"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. Por padrão, quem manda o link ao pagador é você, pelo seu canal; com notifications.email ou notifications.whatsapp, a Calebe Pay manda por você. notifications do ciclo mostra o que já foi enviado ao pagador e pending_notices, o que ainda vai sair. 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).
Avisos de cada ciclo
Quando um ciclo é emitido, inclusive o primeiro, na criação, a assinatura avisa pelos canais de notifications:
| Canal | Padrão | O que acontece |
|---|---|---|
webhook |
true |
O evento subscription.cycle_created vai aos endpoints inscritos nele e ao callback_url da assinatura, com o link do pagador. Vale também para as assinaturas criadas antes deste campo. |
email |
false |
O pagador recebe por e-mail o link da cobrança, com a marca da empresa. |
whatsapp |
false |
O pagador recebe o mesmo link por WhatsApp, no customer.phone. |
{
"id": "evt_wh_7f3a",
"type": "subscription.cycle_created",
"created_at": "2026-11-01T03:00:05Z",
"tenant_id": "ten_exemplo",
"data": {
"subscription_id": "sub_exemplo",
"cycle": 1,
"due_date": "2026-11-06",
"status": "created",
"error_code": null,
"method": "pix",
"amount": 15990,
"currency": "BRL",
"reference": "sub_exemplo:2026-11-06",
"transaction_id": null,
"transaction_status": null,
"checkout_id": "chk_exemplo",
"payment_url": "https://api.calebepay.com.br/checkout/chk_exemplo/c2lnbmF0dXJh",
"payer_notices": ["email"],
"livemode": true
}
}
statusé o do ciclo:created(emitido, ainda não pago),attention(cobrança recusada ou sem resultado confirmado) ouskipped(não será cobrado, com o motivo emerror_codee sempayment_url).- No Pix,
transaction_idénull: a cobrança nasce quando o pagador escolhe pagar no link, e então chegatransaction.created. No boleto, a cobrança já vem no evento. amounté o valor do ciclo: numa assinatura com valor promocional, o promocional nos primeiros ciclos e o integral nos demais.payer_noticesdiz em quais canais a Calebe Pay vai mandar o link ao pagador. Vazio quer dizer que o envio fica com você.- O evento não traz dados do pagador. A assinatura e as retentativas são as de qualquer evento: veja Receber eventos por webhook.
E-mail e WhatsApp ao pagador seguem estas regras:
- Só nos métodos
pixeboleto. No cartão e no Pix Automático o débito é automático e não há link para o pagador:422 validation_error. - O canal precisa estar liberado para a empresa pela administração da Calebe Pay:
422 notification_not_enabled. É o mesmo canal do envio manual da cobrança pelo painel. - O contato do pagador precisa servir para o canal:
customer.emailválido para o e-mail, celular com DDD emcustomer.phonepara o WhatsApp. Se não servir, a resposta é422 notification_recipient_invalid. - A mensagem sai em até um minuto depois da emissão. Cada canal sai uma vez por ciclo. Uma recusa pode ser reenviada pelo painel, na própria cobrança. Um envio sem confirmação não é repetido, porque a mensagem pode ter chegado.
- No modo de teste, nada é enviado ao pagador. O webhook é entregue aos endpoints de teste.
- Uma assinatura pausada ou cancelada depois da emissão não manda mais o aviso daquele ciclo.
Para mudar depois, envie só os canais que mudam: PATCH /v1/subscriptions/{id} com {"notifications": {"whatsapp": true}}. A mudança vale para os próximos ciclos. Para um link já emitido, mande pela cobrança no painel ou pelo seu canal. Um canal já ligado continua ligado se a liberação for retirada depois. Nesse caso, o envio fica registrado como bloqueado no monitor de integrações.
No painel e no app, o mesmo fica em Assinaturas: na criação, em "Avisos de cada ciclo", e na assinatura aberta, em "Alterar avisos". Para um endpoint deixar de receber o evento, desmarque "Ciclo de assinatura emitido" em Webhooks.
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.
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"}. O mesmo PATCH aceita cost_center_id e notifications. 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.
- Crie uma assinatura de boleto ou Pix: a primeira cobrança sai na própria criação, e a resposta traz
cycle: 1. - Liste os ciclos e pegue
transaction_id(no métodopix, abrapayment_urle escolha pagar para gerar a cobrança). - Simule o pagamento com
POST /v1/transactions/{id}/simulatee{"status":"paid"}. Seu webhook de teste recebetransaction.updated. - No cartão, os débitos de teste ficam
pendingaté osimulate. Para testar a recusa e a troca do cartão, crie a assinatura com o cartão4000000000000002: o débito volta recusado (attention,transaction_status: failed,last_error: provider_rejected). Troque por outro cartão de teste comPUT …/credit-card, cobre o ciclo de novo comPOST …/cycles/{cycle}/retrye simule o pagamento da nova cobrança. Uma cobrança de cartão pendente também pode ser recusada com{"status":"failed"}nosimulate. - No Pix Automático, simule a aprovação com
POST /v1/pix-automatic/authorizations/{id}/simulatee{"status":"approved"}(oucancelledeexpiredpara testar o encerramento). Ocopy_pastede teste é um marcador que nenhum banco aceita. - Para ver os meses seguintes sem esperar o calendário, use
POST /v1/subscriptions/{id}/cycles/advance, sem corpo: o próximo ciclo é emitido na hora, com o vencimento e o valor que teria no dia, e a resposta traz a assinatura comcycleenext_due_dateadiantados. Cada chamada avança um ciclo. É assim que se confere uma promoção: numa assinatura compromotional_cycles: 1, o primeiro ciclo sai pelo valor promocional na criação e o avanço emite o seguinte pelo valor integral. Só vale para assinatura de teste e ativa; em produção responde422 simulation_not_allowed.
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 nem troca de forma de pagamento. |
| 422 | subscription_card_required |
A assinatura não tem cartão salvo: cadastre-o com PUT …/credit-card. |
| 422 | subscription_method_fixed |
Assinatura de Pix Automático não troca de forma de pagamento nem de antecedência. |
| 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. |
| 422 | notification_not_enabled |
O envio por e-mail ou WhatsApp não está liberado para a empresa. Fale com a administração da Calebe Pay. |
| 422 | notification_recipient_invalid |
O e-mail ou o celular do pagador não serve para o canal escolhido. |
| 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, cancelar, mudar os avisos ou a forma de pagamento | PATCH /v1/subscriptions/{id} |
| Trocar ou cadastrar o cartão | PUT /v1/subscriptions/{id}/credit-card |
| Cobrar de novo um ciclo recusado (cartão, Pix ou boleto) | POST /v1/subscriptions/{id}/cycles/{cycle}/retry |
| Listar ciclos | GET /v1/subscriptions/{id}/cycles |
| Emitir agora o próximo ciclo (só modo de teste) | POST /v1/subscriptions/{id}/cycles/advance |
| 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, escolher os avisos de cada ciclo, 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.