Cobrança recorrente e assinaturas

A cobrança recorrente da UvviPay cobra seus clientes de forma automática e periódica — mensalidades, assinaturas de SaaS, clubes de benefícios ou qualquer serviço com pagamento repetido. Você define o plano uma vez, assina o cliente e a UvviPay cuida do resto: cobra o meio de pagamento (cartão ou PIX), renova o ciclo e avisa você a cada evento.

O que é cobrança recorrente?

Em vez de gerar uma cobrança manual todo mês, você cria um plano (valor, moeda e frequência) e vincula clientes a ele por meio de uma assinatura. A partir daí, a cada ciclo a UvviPay gera uma fatura e cobra o método de pagamento padrão automaticamente. Benefícios:

Receita previsível — cobranças automáticas em intervalos fixos.
Menos trabalho manual — renovação e retentativas sem intervenção.
Pagamento seguro — cartão tokenizado (PCI) ou PIX sem dados sensíveis de cartão.
Acompanhamento em tempo real — webhooks para cada mudança de status.

Quando usar

Mensalidades e SaaS

Acesso a plataformas, aplicativos ou APIs com cobrança mensal ou anual.

Clubes e assinaturas

Clubes de benefícios, comunidades, caixas mensais e programas de fidelidade.

Cursos e conteúdo

Cursos, mídia e conteúdo premium com renovação automática.

Contratos de serviço

Manutenção, suporte e prestação de serviço com cobrança periódica.

Conceitos

Termo	O que é
Plano	Modelo de cobrança: valor, moeda e cadência (mensal, anual, etc.). Criado uma vez e reutilizado por vários clientes.
Assinatura	Vínculo entre um cliente e um plano. É o que “liga” a cobrança recorrente para aquele cliente.
Fatura	Cobrança de um ciclo específico da assinatura. Cada renovação gera uma nova fatura.
Ciclo	Período coberto por uma fatura (ex.: 1 mês).
Trial	Período de teste gratuito antes da primeira cobrança.
Carência	Dias de tolerância após uma falha de cobrança antes do cancelamento.

Como funciona

Crie um plano

Defina valor, moeda e frequência (POST /v1/recurrency/plan). A cadência é definida uma vez e não muda depois.

Assine o cliente

Envie cliente + meio de pagamento (POST /v1/recurrency/subscription). Sem trial, a primeira cobrança roda no mesmo request (201 se cartão pago, trial ou PIX pendente; 422 / UVV154147 se decline de cartão).

Primeira cobrança

Sem trial, o resultado da cobrança já vem na resposta HTTP. Em PIX pendente, aguarde a liquidação via webhook. Webhooks (subscription.activated, subscription.past_due, etc.) cobrem as transições seguintes.

Renovação automática

A cada ciclo, a UvviPay gera a próxima fatura e cobra o método de pagamento padrão.

Pré-requisitos

Produto habilitado

O produto Recorrência precisa estar ativo para o seu merchant. A ativação é feita pela equipe UvviPay — solicite ao seu contato comercial.

Credenciais de API

Use client-id e client-secret no backend. Nunca exponha o client-secret no front-end. Veja Autenticação.

Webhooks (recomendado)

Registre um endpoint para receber subscription.* e acompanhar a ativação sem polling agressivo. Veja Webhooks.

Não envie dados de cartão a partir do navegador. Chame os endpoints de assinatura e troca de método de pagamento apenas do seu backend (PCI).

Catálogo (planos)

Ação	Método	Endpoint
Criar	`POST`	`/v1/recurrency/plan`
Consultar	`GET`	`/v1/recurrency/plan/{planId}`
Listar	`GET`	`/v1/recurrency/plans`
Atualizar	`PATCH`	`/v1/recurrency/plan/{planId}`
Desativar	`POST`	`/v1/recurrency/plan/{planId}/deactivate`
Ativar	`POST`	`/v1/recurrency/plan/{planId}/activate`

A cadência do plano (interval / custom_interval) é imutável após a criação. Tentativas de alteração retornam 422 CADENCE_IMMUTABLE.

Assinaturas

Ação	Método	Endpoint
Criar	`POST`	`/v1/recurrency/subscription` (`201` / `422`)
Consultar	`GET`	`/v1/recurrency/subscription/{subscriptionId}`
Listar	`GET`	`/v1/recurrency/subscriptions`
Cancelar	`POST`	`/v1/recurrency/subscription/{subscriptionId}/cancel`
Trocar meio de pagamento	`POST`	`/v1/recurrency/subscription/{subscriptionId}/payment-method`
Reativar	`POST`	`/v1/recurrency/subscription/{subscriptionId}/reactivate`

Status da assinatura

Status	Significado
`PENDING`	Criada; aguardando a primeira cobrança
`TRIAL`	Em período de teste gratuito
`ACTIVE`	Cobrança ativa e renovando
`PAST_DUE`	Cobrança falhou, com retentativas restantes
`CANCELLED`	Encerrada (ação do usuário ou falha terminal)

Exemplo prático

1) Criar um plano mensal

Defina valor, moeda e cadência do plano:

Criar plano

curl -X POST https://api.uvvipay.com.br/v1/recurrency/plan \
  -H "Content-Type: application/json" \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -d '{
    "name": "Plano Mensal Pro",
    "description": "Acesso completo",
    "amount": 9900,
    "pricing_type": "FIXED_PRICE",
    "currency": "BRL",
    "interval": "MONTHLY",
    "custom_interval": null,
    "allowed_payment_types": ["credit_card"],
    "default_trial_unit": null,
    "default_trial_duration": null,
    "prevent_trial_abuse": true
  }'

2) Assinar um cliente

Envie o cliente e o meio de pagamento (credit_card ou pix) referenciando o subscription_plan_id. Sem trial, a primeira cobrança roda no mesmo request. Não envie campos de cartão quando type for pix.

Assinar cliente

curl -X POST https://api.uvvipay.com.br/v1/recurrency/subscription \
  -H "Content-Type: application/json" \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -d '{
    "subscription_plan_id": "PLAN_UUID",
    "grace_period_days": 3,
    "trial_duration": null,
    "trial_unit": null,
    "transaction_idempotency_id": "sub-create-0001",
    "customer": {
      "external_customer_id": "customer-ext-0001",
      "name": "João da Silva",
      "email": "joao@exemplo.com",
      "phone": "11987654321",
      "address": {
        "street": "Rua Exemplo",
        "street_number": "100",
        "zip_code": "01310100",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR",
        "neighborhood": "Bela Vista"
      },
      "document": {
        "number": "12345678901",
        "type": "cpf"
      }
    },
    "payment_methods": {
      "number": "4111111111111111",
      "holder_name": "JOAO DA SILVA",
      "security_code": "123",
      "expiration_month": 12,
      "expiration_year": 2030,
      "main_payment_method": true,
      "type": "credit_card"
    }
  }'

PIX (sem trial) — payment_methods pode ser apenas { "type": "pix" }. A resposta inclui pix.qrcode.

Respostas da criação

`201` — cobrança aprovada (sem trial)

Resposta 201 (cartão pago)

{
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "660e8400-e29b-41d4-a716-446655440000",
  "invoice_id": "770e8400-e29b-41d4-a716-446655440000",
  "subscription_status": "ACTIVE",
  "invoice_status": "paid",
  "charge_status": "succeeded",
  "transaction_id": "880e8400-e29b-41d4-a716-446655440000",
  "failure_code": null,
  "failure_message": null,
  "pix": null
}

`201` — trial (sem cobrança no create)

Com trial, não há cobrança no create (subscription_status: "TRIAL").

`422` / `UVV154147` — decline de negócio na cobrança sync

A assinatura é criada (PAST_DUE, invoice OPEN), mas a API responde 422 (não 201 com falha embutida):

Resposta 422 UVV154147

{
  "code": "UVV154147",
  "message": "Nao foi possivel processar o pagamento. Verifique os dados e tente novamente.",
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
  "invoice_id": "770e8400-e29b-41d4-a716-446655440000",
  "failure_code": "issuer_declined",
  "failure_message": "Recusa do banco emissor"
}

Retry manual: reenvie o mesmo POST com o mesmo transaction_idempotency_id e o mesmo payload completo. O replay não duplica a assinatura (invoice permanece OPEN) e inicia uma nova tentativa de cobrança. Alterar o fingerprint do payload retorna 409 / UVV154862. A primeira cobrança não entra em retry automático na fila (auto_charge=false). Detalhes em Criar assinatura.

Webhooks de ciclo de vida

Com um endpoint de webhook registrado, você recebe:

Evento	Quando
`subscription.created`	Assinatura criada
`subscription.trial_started`	Criação com status `TRIAL`
`subscription.activated`	Primeira cobrança paga (`ACTIVE`)
`subscription.past_due`	Cobrança falhou com retentativas restantes
`subscription.cancelled`	Cancelamento por usuário ou falha terminal
`subscription.reactivated`	Reativação após cancelamento por `USER_ACTION`
`subscription.completed`	Assinatura concluída por esgotamento de ciclos
`subscription.renewed`	Cobrança paga com assinatura já `ACTIVE` e período avançado

Exemplo de payload:

{
  "event": "subscription.activated",
  "event_id": "<subscription_events.id>",
  "id": "<subscriptionId>",
  "status": "ACTIVE",
  "plan_id": "...",
  "amount": 9900,
  "currency": "BRL",
  "next_billing_date": "...",
  "period_start_date": "...",
  "period_end_date": "...",
  "occurred_at": "...",
  "customer_id": "<customerId>",
  "external_customer_id": "<externalCustomerId>",
  "invoice_id": "...",
  "charge_attempt_id": "...",
  "transaction_id": "...",
  "attempt": null,
  "decline_kind": null,
  "failure_category": null,
  "cancellation_reason": null,
  "payment_method_id": null,
  "trial_unit": null,
  "trial_duration": null,
  "metadata": {
    "invoiceId": "...",
    "chargeAttemptId": "...",
    "transactionId": "..."
  }
}

A entrega é at-least-once: o mesmo webhook pode ser reenviado. Use event_id como chave de deduplicação (id é o id da assinatura). Campos de contexto no top-level podem ser null conforme o evento; metadata é o payload bruto do evento. Gerencie endpoints em Webhooks.

Campos importantes

Campo	Observação
`amount`	Sempre em centavos (ex.: `9900` = R $99,00). Mín. `1` (R$ 0,01); máx. `1000000` (R$ 10.000,00)
`default_trial_duration`	Duração do trial padrão do plano; máx. `31` dias
`allowed_payment_types`	`credit_card` e/ou `pix`
`grace_period_days`	Dias de tolerância após falha antes do cancelamento terminal
`prevent_trial_abuse`	Bloqueia novo trial para o mesmo cliente quando ativo no plano
`trial_unit`	Apenas `DAY` no create subscription
Request bodies	snake_case (`subscription_plan_id`, `payment_methods`, …)
Responses	snake_case em todos os endpoints (`subscription_id`, `subscription_status`, `next_billing_date`, …)
Webhooks	payload em snake_case (`plan_id`, `next_billing_date`, `occurred_at`, …)

Perguntas frequentes

Preciso armazenar os dados do cartão?

Não. Na criação da assinatura o cartão é tokenizado com segurança e as cobranças seguintes usam o token. Você nunca guarda o número do cartão.

O que acontece se uma cobrança falhar?

Na primeira cobrança (create sem trial), a API responde erro HTTP (422 / UVV154147) com subscription_id e invoice_id (invoice OPEN). A assinatura fica PAST_DUE e não entra em retry automático na fila. Para retry manual, reenvie o mesmo POST com o mesmo transaction_idempotency_id e o mesmo payload completo: o replay não duplica a assinatura e inicia uma nova tentativa de cobrança. Se o fingerprint do payload mudar, a API responde 409 / UVV154862. Em renovações, a UvviPay pode retentar conforme a política de soft/hard/grace enquanto auto_charge estiver habilitado.

Tem período de teste (trial)?

Sim. Defina o trial no plano (default_trial_unit / default_trial_duration, máx. 31 dias) ou na assinatura (trial_unit / trial_duration). A primeira cobrança ocorre automaticamente ao fim do trial.

Como cancelo uma assinatura?

Use POST /v1/recurrency/subscription/{id}/cancel. As faturas em aberto são canceladas e a assinatura passa a CANCELLED por ação do usuário. É possível reativar depois com .../reactivate.

Posso trocar o meio de pagamento de um cliente?

Sim. Use POST /v1/recurrency/subscription/{id}/payment-method (apenas do backend) para definir cartão ou PIX como padrão antes do próximo ciclo. Em payment_methods com type: "pix", não envie campos de cartão.

Consigo mudar o valor ou a frequência do plano?

O valor pode ser atualizado no plano, mas a cadência é imutável após a criação (422 CADENCE_IMMUTABLE). Para outra frequência, crie um novo plano.

Boas práticas

Trate o retorno do create como síncrono para o desfecho HTTP: 201 (cartão pago, trial ou PIX pendente sem trial) ou 422 / UVV154147 (decline com ids). Em 201, confira subscription_status, charge_status e pix. Em PIX pendente, não liberar o serviço até a liquidação ser confirmada.
Use webhooks para transições futuras (renovação, past_due, cancelamento, etc.). Em PIX pendente, confirme a liquidação com subscription.activated e/ou transaction.paid, correlacionando pelo subscription_id ou transaction_id.
Guarde subscription_id e transaction_idempotency_id no seu sistema.
Em decline na primeira cobrança, reenvie o mesmo POST com o mesmo transaction_idempotency_id e o mesmo payload completo (fingerprint diferente → 409 / UVV154862).
Seja idempotente no consumo de webhook — a mesma notificação pode ser reentregue.
Reenviar o mesmo transaction_idempotency_id com o mesmo payload devolve a assinatura já criada (não duplica) e, se a invoice seguir OPEN, pode iniciar nova tentativa de cobrança.
Troque o meio de pagamento com .../payment-method antes do próximo ciclo quando o cliente atualizar cartão ou PIX.

​O que é cobrança recorrente?

​Quando usar

Mensalidades e SaaS

Clubes e assinaturas

Cursos e conteúdo

Contratos de serviço

​Conceitos

​Como funciona

​Pré-requisitos

​Catálogo (planos)

​Assinaturas

​Status da assinatura

​Exemplo prático

​1) Criar um plano mensal

​2) Assinar um cliente

​Respostas da criação

​201 — cobrança aprovada (sem trial)

​201 — trial (sem cobrança no create)

​422 / UVV154147 — decline de negócio na cobrança sync

​Webhooks de ciclo de vida

​Campos importantes

​Perguntas frequentes

​Boas práticas

O que é cobrança recorrente?

Quando usar

Conceitos

Como funciona

Pré-requisitos

Catálogo (planos)

Assinaturas

Status da assinatura

Exemplo prático

1) Criar um plano mensal

2) Assinar um cliente

Respostas da criação

`201` — cobrança aprovada (sem trial)

`201` — trial (sem cobrança no create)

`422` / `UVV154147` — decline de negócio na cobrança sync

Webhooks de ciclo de vida

Campos importantes

Perguntas frequentes

Boas práticas