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": "[email protected]",
      "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": "[email protected]",
    "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