Assinatura recorrente com primeira cobrança

Plano e recursos necessários

Contratar pelo checkout público exige um plano que inclua esse recurso: Growth ou Scale na oferta atual. O Starter permite testes de API, mas não habilita este fluxo de contratação pública.

Confira os requisitos por tipo de integração e compare os planos disponíveis.

O problema resolvido

Tenha um checkout próprio sem reconstruir o motor de recorrência

Seu frontend controla marca, navegação e formulário. A API continua sendo a fonte de verdade do catálogo e cria o cliente, a assinatura e a cobrança inicial dentro do fluxo operacional já validado pelo RecoPay.

Guardrail de arquitetura

Não acesse o banco, não calcule preços como fonte de verdade e não processe o pagamento no checkout próprio. Redirecione para a URL devolvida pela API.

Checkout próprio

Apresenta produtos, planos e componentes.
Coleta e revisa os dados cadastrais.
Obtém o aceite dos termos.
Redireciona para o pagamento retornado.

RecoPay

Revalida catálogo, valores e limites.
Evita cliente duplicado no mesmo escopo.
Cria assinatura e primeira cobrança.
Concilia, notifica, ativa e emite NFS-e.

Antes da integração

Pré-requisitos

Obtenha o checkoutPublicoId da empresa.
Defina o produto ou plano que será oferecido.
Use HTTPS e mantenha tokens de cliente fora de armazenamento persistente desnecessário.
Implemente uma chave idempotente por tentativa lógica de contratação.

Roadmap literal

Fluxo completo de implementação

Carregue o catálogo

Consulte produtos, planos e o detalhe do plano escolhido diretamente na API.

Identifique o cliente

Valide documento e e-mail. Cliente existente deve autenticar antes de contratar.

Monte a revisão

Mostre plano, componentes, valor estimado, pagamento, cadastro e termos.

Crie a contratação

Envie o payload com Idempotency-Key e token quando o cliente já existir.

Redirecione ao pagamento

Use exclusivamente dados.checkoutUrl devolvido pela API.

Etapa 1

Carregue produtos, planos e componentes

Monte a vitrine com o contrato público. Assim, alterações feitas no painel passam a valer sem republicar o checkout.

GET/checkout/{checkoutPublicoId}/produtos

cURL · listar produtos

curl --request GET \
  --url https://api.recopay.com.br/checkout/SEU_CHECKOUT_PUBLICO_ID/produtos \
  --header "Accept: application/json"

GET/checkout/{checkoutPublicoId}/planos/{planoId}

cURL · detalhe do plano

curl --request GET \
  --url https://api.recopay.com.br/checkout/SEU_CHECKOUT_PUBLICO_ID/planos/4 \
  --header "Accept: application/json"

Rota complementar	Quando usar
`GET /checkout/{id}/produtos/{codigo}/planos`	Listar apenas os planos de um produto.
`GET /checkout/{id}/planos/{planoId}`	Carregar componentes, formas de pagamento e termos para a revisão.

Não invente valores

O frontend pode exibir uma estimativa, mas deve usar IDs, quantidades permitidas, formas de pagamento e termos retornados pela API.

Etapa 2

Trate cliente novo e cliente existente

POST/checkout/{checkoutPublicoId}/clientes/verificacao

cURL · verificar identidade

curl --request POST \
  --url https://api.recopay.com.br/checkout/SEU_CHECKOUT_PUBLICO_ID/clientes/verificacao \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "documento": "12345678000190",
    "email": "[email protected]"
  }'

HTTP 200 · cliente existente

{
  "clienteExistente": true,
  "documentoEmUso": true,
  "emailEmUso": true,
  "requerLogin": true,
  "mensagem": "Cliente ja cadastrado para esta empresa."
}

Cliente novo segue com os dados completos no payload da contratação. Cliente existente deve autenticar para impedir apropriação de cadastro.

POST/clientes/auth/login

cURL · autenticar e contratar

curl --request POST \
  --url https://api.recopay.com.br/clientes/auth/login \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "checkoutPublicoId": "SEU_CHECKOUT_PUBLICO_ID",
    "email": "[email protected]",
    "senha": "SENHA_DO_CLIENTE"
  }'

HTTP 200 · autenticação

{
  "mensagem": "Login realizado com sucesso.",
  "dados": {
    "token": "TOKEN_DO_CLIENTE",
    "expiraEm": "2026-08-07T15:30:00-03:00",
    "trocaSenhaObrigatoria": false
  }
}

Se trocaSenhaObrigatoria for verdadeira, conclua POST /clientes/auth/trocar-senha. Para recuperação, use POST /clientes/auth/recuperar-senha; a mensagem é genérica para não enumerar contas.

Etapa 3

Revise o contrato antes de enviar

Mostre produto, plano, periodicidade e valor estimado.
Permita alterar somente componentes opcionais dentro dos limites.
Ofereça apenas as formas de pagamento retornadas.
Renderize os termos de forma sanitizada e exija aceite expresso.
Apresente os dados cadastrais para conferência.

DevTools não altera o contrato

O usuário pode modificar o payload no navegador. O backend revalida plano, componentes, quantidades, identidade e termos antes de gravar.

Etapa 4

Crie a assinatura e a primeira cobrança

POST/checkout/{checkoutPublicoId}/contratacoes

Gere uma chave por tentativa lógica e reutilize-a em retries do mesmo payload. Para cliente existente, acrescente o token Bearer.

cURL · criar contratação

curl --request POST \
  --url https://api.recopay.com.br/checkout/SEU_CHECKOUT_PUBLICO_ID/contratacoes \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: 6636c360-a5f8-47fe-92f5-8d1d6951646b" \
  --header "Authorization: Bearer TOKEN_DO_CLIENTE" \
  --data '{
    "planoId": 4,
    "cliente": {
      "tipoPessoa": "juridica",
      "nome": "Empresa Exemplo LTDA",
      "nomeFantasia": "Empresa Exemplo",
      "documento": "12345678000190",
      "email": "[email protected]",
      "telefone": "11999999999",
      "endereco": {
        "cep": "01001000",
        "logradouro": "Praca da Se",
        "numero": "100",
        "bairro": "Se",
        "municipio": "Sao Paulo",
        "uf": "SP",
        "codigoMunicipioIbge": "3550308"
      }
    },
    "componentes": [
      { "planoPrecoId": 13, "quantidade": 1 }
    ],
    "formaPagamento": "pix",
    "descricao": "Contratacao pelo checkout proprio",
    "termosUsoAceitos": true
  }'

Cliente novo não usa Bearer

Omita Authorization quando a verificação indicar um cadastro novo. Para cliente existente, o token é obrigatório e deve corresponder ao documento e e-mail.

Etapa 5

Redirecione para a primeira cobrança

HTTP 200 · contratação criada

{
  "mensagem": "Contratacao criada com sucesso.",
  "dados": {
    "checkoutUrl": "https://recopay.app/cobrancas/visualizar/..."
  }
}

A única responsabilidade restante do frontend é encaminhar o comprador. JavaScript é adequado aqui porque não substitui o contrato HTTP.

JavaScript · redirecionamento

window.location.assign(resultado.dados.checkoutUrl);

Pix, boleto ou cartão, conciliação, ativação, notificações e NFS-e seguem o fluxo oficial. Não monte a URL com IDs internos.

Resiliência

Falhas esperadas e segurança

Status	Significado	Ação
400	Campos, quantidades ou termos inválidos.	Corrigir o formulário; não repetir automaticamente.
401	Token inválido ou expirado.	Solicitar nova autenticação.
403	Troca obrigatória ou identidade incompatível.	Concluir a troca ou interromper a contratação.
404	Checkout, produto ou plano indisponível.	Atualizar o catálogo.
409	Cliente sem login ou conflito idempotente.	Autenticar ou revisar chave e payload.
429	Limite de requisições.	Aplicar backoff.

Não exponha chaves administrativas nem acesse o banco.
Sanitize termosUsoHtml antes de renderizar.
Prefira memória ou sessionStorage para o token temporário.
Use HTTPS, CSP restritiva e logs sem credenciais.
Em timeout da contratação, repita com a mesma chave idempotente.

Antes de publicar

Checklist de produção

Catálogo carregado pela API
Plano validado no servidor
Cliente existente direcionado ao login
Recuperação sem enumerar contas
Termos sanitizados e aceitos
Componentes dentro dos limites
Forma de pagamento permitida
Idempotency-Key preservada no retry
Token restrito ao cliente existente
Redirecionamento pela URL retornada
Nenhuma ativação no frontend
Testes de 400, 401, 403, 409 e 429

Implementação assistida

Contrato resumido para agentes de IA

Prompt de integração

OBJETIVO
Construir um checkout proprio para assinatura recorrente RecoPay.

FLUXO
1. GET /checkout/{checkoutPublicoId}/produtos
2. GET /checkout/{checkoutPublicoId}/produtos/{produtoCodigo}/planos
3. GET /checkout/{checkoutPublicoId}/planos/{planoId}
4. POST /checkout/{checkoutPublicoId}/clientes/verificacao
5. Se existente: POST /clientes/auth/login
6. Exibir revisao e obter aceite dos termos.
7. POST /checkout/{checkoutPublicoId}/contratacoes com Idempotency-Key.
8. Redirecionar para dados.checkoutUrl.

GUARDRAILS
- Nao acessar banco nem usar chave administrativa.
- Nao inventar preco, desconto, componente ou forma de pagamento.
- Reutilizar a Idempotency-Key apenas no retry do mesmo payload.
- Cliente existente deve contratar com Bearer token.
- Sanitizar termosUsoHtml.
- Nao processar pagamento, ativar assinatura ou emitir NFS-e.

RESULTADO
Cliente, assinatura e primeira cobranca criados pela API;
navegador redirecionado ao pagamento oficial do RecoPay.

Crie uma assinatura recorrente e encaminhe a primeira cobrança