Link de Pagamento Recorrente

Este caso de uso descreve como um vendedor cria um Link de Pagamento Recorrente para contratação de uma assinatura, utilizando um checkout hospedado pela Barte. O cliente acessa o link, realiza a contratação e os pagamentos passam a ocorrer de forma recorrente, conforme o plano configurado.

---

Atores

• Vendedor (Seller): Sistema integrador
• Comprador (Buyer): Cliente final que contratará a assinatura
• Barte API: Responsável pelo checkout, criação da assinatura, cobranças recorrentes e notificações

---

Pré-condições

• O vendedor possui um Token de API válido

  • 📌 Referência: Obtendo o Token de API
• Um Plano de Assinatura deve estar previamente criado (obrigatório)

  • 📌 Referência: Criando Plano de Assinatura
• O vendedor definiu os métodos de pagamento permitidos no checkout
• O comprador não precisa ser criado previamente

  • O Buyer será criado automaticamente durante o checkout, se necessário

---

Fluxo Principal

1. Autenticação na API

Todas as requisições devem conter o Token de API no header:

X-Token-Api: YOUR_API_KEY

📌 Referência: Obtendo o Token de API

---

2. Criar um Plano de Assinatura (Obrigatório)

O plano define as regras da cobrança recorrente, como:

• Periodicidade
• Valor
• Ciclo de cobrança

📌 O UUID do plano será utilizado obrigatoriamente na criação do link recorrente.

📌 Referência: Criando Plano de Assinatura

---

3. Criar um Link de Pagamento Recorrente

Com o plano criado, o vendedor gera um link de pagamento recorrente.

Configuração importante:

• type = SUBSCRIPTION
• paymentSubscription.idPlan deve conter o UUID do plano
• Definição dos métodos de pagamento permitidos no checkout

Resultado esperado:

• A API retorna um link público (url) de checkout
• O link pode ser compartilhado livremente com o cliente

📌 Referência: Link de Pagamento Recorrente

---

4. Cliente acessa o Link de Pagamento

Ao acessar o link:

• O cliente preenche seus dados
• Escolhe o método de pagamento disponível
• Confirma a contratação da assinatura

O que acontece:

• Um Buyer pode ser criado automaticamente
• A assinatura é criada conforme o plano
• A primeira cobrança é processada (quando aplicável)

---

Fluxos Pós-Contratação

Após a criação da assinatura, o ciclo passa a ser gerenciado pela Barte.

Atualizações via webhook

Webhooks são enviados sempre que ocorrer:

• Criação da assinatura
• Pagamento confirmado
• Falha de pagamento
• Cancelamento
• Alteração de status

💡 Os webhooks de Subscriptions devem ser utilizados como fonte de verdade para o estado da assinatura.

---

Pós-condições

Ao final deste caso de uso, o vendedor consegue:

• Criar um plano de assinatura
• Criar um link de pagamento recorrente
• Permitir que clientes contratem assinaturas via checkout Barte
• Acompanhar o ciclo da assinatura via webhooks
• Controlar cobranças recorrentes sem checkout próprio

---

Observações Importantes

• O plano de assinatura é obrigatório
• O Buyer não é obrigatório antes da criação do link
• O link recorrente não cria regras de cobrança, apenas referencia um plano
• A confirmação da assinatura não deve ser feita pelo frontend
• Webhooks são a fonte de verdade do ciclo da assinatura