Criando Assinatura

A assinatura representa uma cobrança recorrente baseada em um plano previamente criado. Ao criar uma assinatura, a Barte passa a gerar cobranças automaticamente de acordo com a periodicidade definida no plano.

📌 A confirmação de pagamentos recorrentes sempre ocorre via webhook, independentemente do método de pagamento.

---

Endpoint

POST /v2/subscriptions https://api.barte.com/v2/subscriptions

Headers

X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*

---

Pré-requisitos

Antes de criar uma assinatura, é necessário:

• Ter um plano ativo
• Possuir o uuid do plano
• Possuir o uuid do comprador (buyer)
• Definir o método de pagamento aceito pelo plano

---

Body

{
  "uuidPlan": "123e4567-e89b-12d3-a456-426614174000",
  "basicValue": {
    "type": "MONTHLY",
    "valuePerMonth": 100
  },
  "additionalValue": {
    "installments": 1,
    "value": 100
  },
  "payment": {
    "method": "CREDIT_CARD",
    "card": {
      "holderName": "JOAO DA SILVA",
      "number": "4111111111111111",
      "expiration": "12/2026",
      "cvv": "123",
      "buyerUuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "fraudData": {
      "document": "12345678900",
      "email": "[e-mail]",
      "name": "João da Silva",
      "phone": "11999999999"
    }
  },
  "uuidBuyer": "123e4567-e89b-12d3-a456-426614174000",
  "startDate": "2026-01-29",
  "metadata": [
    {
      "key": "text",
      "value": "text"
    }
  ]
}

---

Response

{
  "uuid": "f38644c8-ff93-410c-be8d-84c5c608dacf",
  "status": "ACTIVE",
  "customer": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "email": "[e-mail]",
    "document": "text"
  },
  "startDate": "2026-01-29",
  "value": {
    "type": "MONTHLY",
    "valuePerMonth": 100
  },
  "additionalValue": {
    "installments": 1,
    "value": 100
  },
  "paymentMethod": "CREDIT_CARD",
  "charges": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "status": "PAID",
      "value": 1,
      "createdAt": "2026-01-29T19:48:36.007Z",
      "updatedAt": "2026-01-29T19:48:36.007Z"
    }
  ]
}

---

Campos mais importantes da resposta

• uuid - Identificador único da assinatura. Deve ser salvo para:

  • Consultas futuras
  • Validação de webhooks
  • Gestão da assinatura
• status - Status atual da assinatura. Exemplos:

  • PENDING → aguardando primeiro pagamento
  • ACTIVE → assinatura ativa
  • CANCELED → assinatura cancelada
  • SUSPENDED → cobrança interrompida
• charges[].uuid - Identificador da cobrança gerada. Necessário para:

  • Estornos
  • Conciliação
  • Auditoria
• charges[].status - Status da cobrança recorrente. Exemplos:

  • PAID
  • PENDING
  • FAILED
  • ABANDONED

---

Confirmação de pagamento

Após a criação da assinatura:

• A primeira cobrança é gerada automaticamente
• O pagamento pode ser:

  • Processado imediatamente (cartão)
  • Processado de forma assíncrona (PIX / boleto)
• Alterações de status sempre geram webhooks

📌 Utilize o webhook como fonte única de verdade para:

• Confirmar pagamento
• Ativar serviços
• Liberar acesso

---

Fluxo resumido da assinatura

Criar assinatura
      ↓
Gerar cobrança recorrente
      ↓
Cliente realiza pagamento
      ↓
Status atualizado na Barte
      ↓
Webhook enviado
      ↓
Seu sistema confirma o pagamento

---

Boas práticas

• Sempre armazene:

  • uuid da assinatura
  • uuid das cobranças
• Utilize webhooks para confirmação
• Trate webhooks de forma idempotente
• Valide se o plano está ativo antes de criar a assinatura
• Use metadata para controle interno
• Monitore falhas de pagamento recorrente

---

O que não fazer

• Criar assinatura com plano inativo
• Confirmar pagamento sem webhook
• Reutilizar assinaturas canceladas
• Assumir sucesso apenas pela resposta da API
• Expor sua chave de API no frontend