Cobrança recorrente e assinaturas

A cobrança recorrente da UvviPay cobra de novo no intervalo que você escolher: mensalidade, SaaS, clube ou outro serviço com pagamento repetido. Você cria o plano uma vez (valor, moeda e frequência) e depois assina o cliente. A cada ciclo a UvviPay gera uma fatura, cobra o método padrão e avisa por webhook.

Cobrança em intervalos fixos.
Renovação e novas tentativas sem você ter que intervir.
Cartão tokenizado (PCI) ou PIX, sem guardar dados de cartão.
Webhook a 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	Valor, moeda e frequência (mensal, anual, etc.). Você cria uma vez e reusa em vários clientes.
Cliente	Quem você cobra. Depois da primeira assinatura, o cadastro fica na sua conta com um `customer_id`. Use esse `customer_id` nas assinaturas seguintes.
Assinatura	O vínculo entre um cliente e um plano. A UvviPay cobra a cada ciclo a partir daqui.
Fatura	Cobrança de um ciclo 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 depois de uma falha de cobrança, antes do cancelamento.

Como funciona

Crie um plano

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

Assine o cliente

Envie o cliente e o meio de pagamento (POST /v1/subscriptions). Se o cliente já estiver cadastrado, prefira customer_id. O bloco customer também reaproveita o cadastro pelo external_customer_id. Sem trial, a primeira cobrança acontece neste request (201 se cartão pago ou PIX pendente; 422 / UVV154147 se o cartão for recusado). Se o trial for aceito, a API responde 201 sem cobrança inicial. A primeira cobrança acontece no fim do trial. Em pix_type: automatic, o trial deve terminar no mínimo em 3 dias. Duração menor responde 422 / UVV154490.

Primeira cobrança

Sem trial, o resultado da cobrança já vem na resposta HTTP. Em PIX pendente, aguarde a confirmação pelo webhook. Os eventos subscription.activated, subscription.past_due e os demais cobrem as mudanças 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 na sua conta. A equipe UvviPay faz a ativação. Peça 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)

Cadastre um endpoint para receber subscription.* e acompanhar a ativação sem consultar a API o tempo todo. Veja Webhooks.

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

Catálogo (planos)

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

A frequência do plano (interval / custom_interval) não muda depois da criação. Se você tentar alterar, a API responde 422.

Assinaturas

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

Faturas

Ação	Método	Endpoint
Listar	`GET`	`/v1/subscriptions/invoices`
Consultar	`GET`	`/v1/subscriptions/invoices/{invoiceId}`

Clientes

Ação	Método	Endpoint
Criar	`POST`	`/v1/customers`
Listar	`GET`	`/v1/customers`
Consultar	`GET`	`/v1/customers/{customerId}`

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`	A cobrança falhou. Ainda há tentativas restantes.
`CANCELLED`	Encerrada pelo cliente ou por falha de pagamento.

Exemplo prático

1) Criar um plano mensal

Defina valor, moeda e frequência do plano:

Criar plano

curl -X POST https://api.uvvipay.com.br/v1/subscriptions/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) com o subscription_plan_id. Sem trial, a primeira cobrança acontece neste request. Não envie dados de cartão quando type for pix.

Assinar cliente

curl -X POST https://api.uvvipay.com.br/v1/subscriptions \
  -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 só { "type": "pix" }. A resposta inclui pix.qrcode.

3) Assinar um cliente que já existe

Cadastre o cliente com POST /v1/customers. Guarde o id. Na criação da assinatura, envie esse valor em customer_id e não reenvie os dados do cliente. A criação aceita duas formas de identificar o cliente. Envie uma. Nunca as duas.

Campo	Quando usar	O que a API faz
`customer_id`	O cliente já está na sua conta	Usa esse cliente na assinatura
`customer`	Primeira assinatura do cliente	Cria o cadastro, ou reaproveita o que já existe pelo `external_customer_id`

Para obter o customer_id:

Crie o cliente com POST /v1/customers e use o id da resposta.
Ou liste com GET /v1/customers e use o id de cada item.

Assinar cliente existente

curl -X POST https://api.uvvipay.com.br/v1/subscriptions \
  -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,
    "transaction_idempotency_id": "sub-create-0002",
    "customer_id": "660e8400-e29b-41d4-a716-446655440000",
    "payment_methods": {
      "type": "pix",
      "main_payment_method": true
    }
  }'

O resto da criação não muda. Plano, payment_methods, trial, carência e idempotência funcionam igual nas duas formas.

O que muda com `customer_id`

A API não olha nome, e-mail, telefone nem documento. Por isso UVV154640 e UVV154718 não aparecem.
A busca é na sua conta. Um customer_id de outra conta responde 404.
O cadastro do cliente não muda. Nem customer_id nem customer atualizam quem já está salvo.

Erros do cliente na criação

HTTP	`code`	Forma	Causa
`400`	-	ambas	Enviou `customer_id` e `customer` juntos, ou não enviou nenhum
`404`	`UVV154225`	`customer_id`	O `customer_id` não existe na sua conta
`422`	`UVV154640`	`customer`	Dados diferentes do cadastro para o mesmo `external_customer_id`
`422`	`UVV154718`	`customer`	Documento já ligado a outro `external_customer_id`
`409`	`UVV154158`	ambas	O cliente já tem assinatura neste plano
`422`	`UVV154361`	ambas	Pix Automático sem endereço completo

Pix Automático (pix_type: automatic) pede endereço completo: zip_code, street, street_number, neighborhood, city, state e country.Se o cliente já está salvo sem endereço, customer_id não resolve. A API responde 422 / UVV154361 e não cria a assinatura.Cadastre o endereço na primeira assinatura. Não há endpoint público para atualizar o cadastro depois. Enviar customer com address vale só para aquela criação: o cliente que já existe continua sem endereço.PIX imediato e cartão não pedem endereço.

O endereço dentro de customer é opcional. Se você enviar address, preencha todos os campos. Se faltar algum, a API responde 400. Envie o endereço na primeira assinatura se pretende usar Pix Automático depois.

A idempotência considera a forma de identificar o cliente. Para repetir a chamada com o mesmo transaction_idempotency_id, envie o mesmo payload. Se a primeira chamada enviou o bloco customer e a nova enviar customer_id, a API responde 409 / UVV154862.

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 na criação)

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

`422` / `UVV154147`: cartão recusado na primeira cobrança

A assinatura é criada mesmo assim (PAST_DUE, fatura open). A API responde 422, não 201:

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

Para tentar de novo, reenvie o mesmo POST com o mesmo transaction_idempotency_id e o mesmo payload. A API não cria outra assinatura. Se a fatura ainda estiver open, a cobrança roda de novo. Payload diferente responde 409 / UVV154862. Detalhes em Criar assinatura.

Webhooks de ciclo de vida

Com um endpoint de webhook cadastrado, 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 tentativas restantes
`subscription.cancelled`	Cancelamento pelo cliente ou por falha de pagamento
`subscription.reactivated`	Reativação após cancelamento por `USER_ACTION`
`subscription.completed`	Assinatura concluída ao esgotar os ciclos
`subscription.renewed`	Cobrança paga com a assinatura já `ACTIVE` e o 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": "..."
  }
}

O mesmo webhook pode chegar mais de uma vez. Use event_id para ignorar duplicata. O campo id é o id da assinatura. Alguns campos no topo podem vir null, conforme o 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 depois da falha, antes do cancelamento
`prevent_trial_abuse`	Impede novo trial para o mesmo cliente neste plano
`trial_unit`	Só `DAY` na criação da assinatura
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. 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 (criação sem trial), a API responde 422 / UVV154147 com subscription_id e invoice_id (fatura open). A assinatura fica PAST_DUE. Para tentar de novo, reenvie o mesmo POST com o mesmo transaction_idempotency_id e o mesmo payload. A API não cria outra assinatura. Payload diferente responde 409 / UVV154862. Nas renovações, a UvviPay pode tentar de novo enquanto a assinatura estiver em atraso.

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 acontece no fim do trial.

Como cancelo uma assinatura?

Use POST /v1/subscriptions/{id}/cancel. As faturas open passam a void e a assinatura fica CANCELLED por ação do cliente. Dá para reativar depois com .../reactivate.

Posso trocar o meio de pagamento de um cliente?

Sim. Use POST /v1/subscriptions/{id}/payment-method (só 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 dados de cartão.

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

O valor pode ser atualizado no plano. A frequência não muda depois da criação (422). Para outra frequência, crie um novo plano.

Preciso reenviar os dados do cliente em cada assinatura?

Não. Se o cliente já estiver cadastrado, inclusive por POST /v1/customers, prefira customer_id desde a primeira assinatura. O bloco customer também vale: a API reaproveita o cadastro pelo external_customer_id. As duas formas são exclusivas: envie uma ou outra. Os dois juntos respondem 400.

O mesmo cliente pode ter mais de uma assinatura?

Sim, em planos diferentes. Use o mesmo customer_id em cada criação. No mesmo plano, uma segunda assinatura ativa responde 409 / UVV154158.

Como atualizo os dados de um cliente já salvo?

A criação da assinatura não atualiza o cliente. Enviar o bloco customer com o mesmo external_customer_id e dados diferentes responde 422 / UVV154640. Para corrigir o cadastro, fale com o suporte UvviPay.

Boas práticas

Trate a criação pelo status HTTP: 201 (cartão pago, trial ou PIX pendente) ou 422 / UVV154147 (recusa com ids). Em 201, confira subscription_status, charge_status e pix. Em PIX pendente, não libere o serviço até a confirmação do pagamento.
Use webhooks para as mudanças seguintes (renovação, past_due, cancelamento). Em PIX pendente, confirme com subscription.activated e/ou transaction.paid, pelo subscription_id ou transaction_id.
Guarde subscription_id, customer_id e transaction_idempotency_id. Com o customer_id salvo, as assinaturas seguintes do mesmo cliente não precisam do bloco customer.
Cadastre o cliente com endereço completo na primeira assinatura se você pretende usar Pix Automático depois. Sem endereço, a API responde 422 / UVV154361.
Se a primeira cobrança for recusada, reenvie o mesmo POST com o mesmo transaction_idempotency_id e o mesmo payload. Payload diferente responde 409 / UVV154862.
Trate o webhook como idempotente. A mesma notificação pode chegar de novo.
Reenviar o mesmo transaction_idempotency_id com o mesmo payload devolve a assinatura já criada. Se a fatura ainda estiver open, a cobrança pode rodar de novo.
Troque o meio de pagamento com .../payment-method antes do próximo ciclo, quando o cliente atualizar cartão ou PIX.

​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

​Faturas

​Clientes

​Status da assinatura

​Exemplo prático

​1) Criar um plano mensal

​2) Assinar um cliente

​3) Assinar um cliente que já existe

​O que muda com customer_id

​Erros do cliente na criação

​Respostas da criação

​201: cobrança aprovada (sem trial)

​201: trial (sem cobrança na criação)

​422 / UVV154147: cartão recusado na primeira cobrança

​Webhooks de ciclo de vida

​Campos importantes

​Perguntas frequentes

​Boas práticas

Quando usar

Conceitos

Como funciona

Pré-requisitos

Catálogo (planos)

Assinaturas

Faturas

Clientes

Status da assinatura

Exemplo prático

1) Criar um plano mensal

2) Assinar um cliente

3) Assinar um cliente que já existe

O que muda com `customer_id`

Erros do cliente na criação

Respostas da criação

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

`201`: trial (sem cobrança na criação)

`422` / `UVV154147`: cartão recusado na primeira cobrança

Webhooks de ciclo de vida

Campos importantes

Perguntas frequentes

Boas práticas