Criar Assinatura

Criar uma nova assinatura recorrente para um cliente. Assinaturas suportam múltiplas frequências de cobrança e podem incluir taxas adicionais como encargos de configuração.

Frequências de Cobrança

Mensal

Cobrar todo mês na mesma data

Trimestral

Cobrar a cada 3 meses na mesma data

Anual

Cobrar uma vez por ano na mesma data

Métodos de Pagamento

Você pode criar assinaturas usando:

Dados do cartão - Para novos clientes
Token de cartão - Para clientes existentes com cartões salvos
Comprador existente - Referenciar comprador por UUID

Exemplo de Requisição (Novo Cliente com Cartão)

Exemplo de Requisição

{
  "basicValue": {
    "type": "MONTHLY",
    "valuePerMonth": 30
  },
  "payment": {
    "method": "CREDIT_CARD",
    "card": {
      "name": "Ana Costa",
      "number": "5186882549895601",
      "expiration": "12/2025",
      "securityCode": "220"
    }
  },
  "buyer": {
    "name": "Ana Costa",
    "document": "25201246010",
    "email": "[email protected]",
    "phone": "11999998888",
    "countryCode": "+55",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Vila Madalena",
      "street": "Rua Harmonia",
      "zipCode": "05435000",
      "number": "789",
      "complement": "Casa 2"
    }
  },
  "startDate": "2024-02-01",
  "externalId": "subscription-ext-456",
  "description": "Assinatura mensal premium",
  "metadata": {
    "customerIp": "192.168.1.200",
    "source": "website",
    "campaign": "premium-2024"
  },
  "callbackUrl": "https://example.com/webhook/subscription"
}

Exemplo de Requisição (Cliente Existente com Token)

Requisição com Token

{
  "basicValue": {
    "type": "QUARTERLY",
    "valuePerMonth": 50
  },
  "payment": {
    "method": "CREDIT_CARD",
    "cardToken": {
      "cardToken": "card-token-uuid-789",
      "cvv": "789"
    }
  },
  "buyerUuid": "buyer-uuid-existing-123",
  "startDate": "2024-03-01",
  "externalId": "subscription-token-789",
  "description": "Assinatura trimestral empresarial"
}

Exemplo de Resposta

Resposta

{
  "uuid": "subscription-uuid-12345",
  "status": "active",
  "basicValue": {
    "type": "MONTHLY",
    "valuePerMonth": 30
  },
  "buyerUuid": "buyer-uuid-67890",
  "startDate": "2024-02-01",
  "nextBillingDate": "2024-02-01",
  "totalMonthlyValue": 30,
  "externalId": "subscription-ext-456",
  "description": "Assinatura mensal premium",
  "createdAt": "2024-01-15T14:30:00Z"
}

Valores da Assinatura

Valor Básico

O valor central da assinatura cobrado na frequência especificada.

basicValue.type

string

required

Frequência de cobrança: MONTHLY, QUARTERLY, ou ANNUALLY

basicValue.valuePerMonth

integer

required

Valor mensal em reais (sempre especificar mensal mesmo para trimestral/anual)

Lógica de Cobrança

Assinaturas Mensais

Básico: R$ 29,99/mês = valuePerMonth: 30
Total: R$ 29,99/mês

Assinaturas Trimestrais

Básico: R $149,99 a cada 3 meses = `valuePerMonth: 50` (cobrado como R$ 150,00)
Cobrança: Cobrado a cada 3 meses na data de início

Assinaturas Anuais

Básico: R $999,99 por ano = `valuePerMonth: 84` (cobrado como R$ 1008,00)
Cobrança: Cobrado uma vez por ano na data de início

Para assinaturas trimestrais e anuais, o valor cobrado real é calculado como valuePerMonth * meses_do_período_de_cobrança.

Data de Início

startDate

string

Data quando a assinatura se torna ativa (formato YYYY-MM-DD)

Data futura: Assinatura inicia na data especificada
Hoje ou passado: Assinatura inicia imediatamente
Padrão: Se não fornecido, inicia imediatamente

Ciclo de Vida da Assinatura

Criada - Assinatura é criada mas ainda não está ativa
Ativa - Assinatura está rodando e cobrando normalmente
Em Atraso - Pagamento falhou, tentando novamente conforme política de retry
Cancelada - Assinatura foi cancelada pelo comerciante ou cliente
Expirada - Assinatura atingiu sua data final ou máximo de tentativas de retry

A primeira tentativa de cobrança ocorre na startDate. Certifique-se de que o método de pagamento do cliente é válido e tem fundos suficientes.

Integração de Webhook

callbackUrl

string

URL para receber notificações de eventos da assinatura

Eventos de webhook incluem:

subscription.created
subscription.activated
subscription.payment.succeeded
subscription.payment.failed
subscription.cancelled

Melhores Práticas

Testar cartões primeiro - Use tokenização de cartão para validar métodos de pagamento
Preços claros - Seja transparente sobre todas as cobranças aos clientes
Lidar com falhas - Implemente lógica de retry para pagamentos falhados
Monitorar webhooks - Rastrear eventos de assinatura para inteligência de negócio
Atualizar cobrança - Manter métodos de pagamento dos clientes atuais

Authorizations

x-api-key

string

header

required

Chave de API para autenticação

Body

application/json

basicValue

object

required

Mostrar atributos filhos

basicValue.type

enum<string>

required

Frequência de cobrança

Opções disponíveis:

MONTHLY,

QUARTERLY,

ANNUALLY

basicValue.valuePerMonth

integer

required

Valor mensal em reais

Example:

30

payment

object

required

Mostrar atributos filhos

payment.method

enum<string>

required

Método de pagamento

Opções disponíveis:

CREDIT_CARD

payment.card

object

Mostrar atributos filhos

payment.card.name

string

required

Nome do portador do cartão

Example:

"JOSE DAS NEVES TEST"

payment.card.number

string

required

Número do cartão

Example:

"5383638854408981"

payment.card.expiration

string

required

Data de expiração do cartão (MM/AA)

Example:

"12/24"

payment.card.securityCode

string

required

Código de segurança do cartão (CVV)

Example:

"220"

payment.cardToken

object

Mostrar atributos filhos

payment.cardToken.cardToken

string<uuid>

required

Token do cartão salvo

Example:

"550e8400-e29b-41d4-a716-446655440000"

payment.cardToken.cvv

string

Código de segurança do cartão para pagamento com token

Example:

"220"

buyer

object

Mostrar atributos filhos

buyer.name

string

required

Nome completo do comprador

Example:

"João da Silva Teste"

buyer.document

string

required

Número do documento (CPF/CNPJ)

Example:

"11144477735"

buyer.email

string<email>

required

Endereço de email

Example:

"[email protected]"

buyer.phone

string

required

Número de telefone

Example:

"11999999999"

buyer.countryCode

string

required

Código do país com prefixo +

Example:

"+55"

buyer.address

object

required

Mostrar atributos filhos

buyer.address.country

string

required

Código do país

Example:

"BR"

buyer.address.state

string

required

Código do estado

Example:

"SP"

buyer.address.city

string

required

Nome da cidade

Example:

"São Paulo"

buyer.address.district

string

required

Bairro/distrito

Example:

"Centro"

buyer.address.street

string

required

Nome da rua

Example:

"Rua das Flores"

buyer.address.zipCode

string

required

CEP/código postal

Example:

"01000000"

buyer.address.number

string

required

Número da residência

Example:

"220"

buyer.address.complement

string

Complemento do endereço

Example:

"Apto 45"

buyerUuid

string<uuid>

UUID de comprador existente

startDate

string<date>

Data de início da assinatura

Example:

"2024-02-01"

externalId

string

ID de referência externa

Example:

"subscription-ext-456"

description

string

Descrição da assinatura

Example:

"Assinatura mensal premium"

metadata

object

Metadados adicionais

callbackUrl

string<uri>

URL de callback do webhook

Response

200 - application/json

Assinatura criada com sucesso

uuid

string<uuid>

UUID da assinatura

status

string

Status da assinatura

planUuid

string<uuid>

UUID do plano

basicValue

object

Mostrar atributos filhos

basicValue.type

enum<string>

required

Frequência de cobrança

Opções disponíveis:

MONTHLY,

QUARTERLY,

ANNUALLY

basicValue.valuePerMonth

integer

required

Valor mensal em reais

Example:

30

startDate

string<date>

Data de início

nextBillingDate

string<date>

Próxima data de cobrança

createdAt

string<date-time>

Timestamp de criação

Visão Geral

Fluxo de Integração

Pagamentos

Tokenização

Assinaturas

Gestão de Compradores

Webhooks

Frequências de Cobrança

Mensal

Trimestral

Anual

Métodos de Pagamento

Exemplo de Requisição (Novo Cliente com Cartão)

Exemplo de Requisição (Cliente Existente com Token)

Exemplo de Resposta

Valores da Assinatura

Valor Básico

Lógica de Cobrança

Assinaturas Mensais

Assinaturas Trimestrais

Assinaturas Anuais

Data de Início

Ciclo de Vida da Assinatura

Integração de Webhook

Melhores Práticas

Authorizations

Body

Response

Visão Geral

Fluxo de Integração

Pagamentos

Tokenização

Assinaturas

Gestão de Compradores

Webhooks

​Frequências de Cobrança

Mensal

Trimestral

Anual

​Métodos de Pagamento

​Exemplo de Requisição (Novo Cliente com Cartão)

​Exemplo de Requisição (Cliente Existente com Token)

​Exemplo de Resposta

​Valores da Assinatura

​Valor Básico

​Lógica de Cobrança

​Assinaturas Mensais

​Assinaturas Trimestrais

​Assinaturas Anuais

​Data de Início

​Ciclo de Vida da Assinatura

​Integração de Webhook

​Melhores Práticas

Authorizations

Body

Response

Frequências de Cobrança

Métodos de Pagamento

Exemplo de Requisição (Novo Cliente com Cartão)

Exemplo de Requisição (Cliente Existente com Token)

Exemplo de Resposta

Valores da Assinatura

Valor Básico

Lógica de Cobrança

Assinaturas Mensais

Assinaturas Trimestrais

Assinaturas Anuais

Data de Início

Ciclo de Vida da Assinatura

Integração de Webhook

Melhores Práticas