Skip to main content
Quando você cria uma assinatura com startAt definido como a data atual, o motor de recorrência da Malga processa a primeira cobrança imediatamente. Este comportamento especial permite que você inicie a cobrança no mesmo dia da criação da assinatura.
Importante: O campo startAt deve ser informado em formato UTC (YYYY-MM-DD).

​
Comportamento especial

Ao definir startAt como a data atual, o motor de recorrência:
  1. Processa a cobrança imediatamente após a criação da assinatura
  2. Retorna informações detalhadas sobre o processamento na resposta da API
  3. Envia webhooks específicos para notificar sobre o resultado da cobrança
  4. Atualiza o status da assinatura baseado no resultado da cobrança

​
Exemplo de criação com startAt sendo hoje

curl --location 'https://api.malga.io/v1/subscriptions' \
--header 'Content-Type: application/json' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'X-Api-Key: YOUR_API_KEY' \
--data '{
  "name": "Assinatura Premium com Eventos",
  "merchantId": "YOUR_MERCHANT_ID",
  "customerId": "YOUR_CUSTOMER_ID",
  "referenceKey": "SUB-PREMIUM-001",
  "recurrence": {
    "interval": "monthly",
    "startAt": "2025-08-06"
  },
  "paymentMethod": {
    "type": "credit",
    "card": {
      "cardId": "YOUR_CARD_ID"
    }
  },
  "items": [
    {
      "name": "Ingresso VIP Mensal",
      "description": "Acesso VIP premium a eventos mensais",
      "amount": 29900,
      "quantity": 1,
      "sku": "VIP-EVENT-001",
      "risk": "Low",
      "categoryId": "entertainment",
      "locality": "São Paulo",
      "date": "2025-12-01",
      "type": 1,
      "genre": "Shows e Eventos",
      "tickets": {
        "quantityTicketSale": 1,
        "convenienceFeeValue": 15.5,
        "quantityFull": 1,
        "batch": 1
      },
      "location": {
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Centro de Convenções",
        "zipCode": "01310-100",
        "city": "São Paulo",
        "state": "SP",
        "country": "Brasil",
        "district": "Bela Vista",
        "reference": "Próximo ao MASP"
      }
    }
  ]
}'
Sobre o campo lastCycle: O campo lastCycle sempre está presente nas respostas individuais de assinatura (GET, CREATE, UPDATE), mesmo quando não há cobrança instantânea. Quando não existem faturas, o campo será null. Nos exemplos acima, o campo contém um objeto porque há cobrança instantânea, mas em outros cenários você pode receber "lastCycle": null.

​
Webhooks específicos

Quando você cria uma assinatura com cobrança instantânea, você receberá webhooks específicos:

​
Ordem de eventos

  1. Quando a assinatura é criada: subscription.created;
  2. Quando a cobrança é processada:
    • subscription.activated (em caso de sucesso);
    • subscription.cycle_failed (quando há falha no processamento da cobrança);
  3. subscription.unpaid (após esgotar todas as tentativas de cobrança da fatura).

​
Novo webhook: subscription.cycle_failed

Este webhook é enviado quando uma fatura de cobrança falha após todas as retentativas: 
{
  "id": "webhook_event_id_example",
  "apiVersion": "1.1",
  "object": "subscription",
  "event": "cycle_failed",
  "createdAt": "2025-08-06T13:57:36.672Z",
  "data": {
    "subscription": {
      "id": "subscription_id_example",
      "name": "Assinatura Premium com Eventos",
      "clientId": "YOUR_CLIENT_ID",
      "merchantId": "YOUR_MERCHANT_ID",
      "customerId": "YOUR_CUSTOMER_ID",
      "referenceKey": "SUB-PREMIUM-001",
      "currency": "BRL",
      "items": [
        {
          "name": "Ingresso VIP Mensal",
          "description": "Acesso VIP premium a eventos mensais",
          "amount": 29900,
          "quantity": 1,
          "sku": "VIP-EVENT-001",
          "risk": "Low",
          "categoryId": "entertainment",
          "locality": "São Paulo",
          "date": "2025-12-01",
          "type": 1,
          "genre": "Shows e Eventos",
          "tickets": {
            "quantityTicketSale": 1,
            "convenienceFeeValue": 15.5,
            "quantityFull": 1,
            "batch": 1
          },
          "location": {
            "street": "Av. Paulista",
            "number": "1000",
            "complement": "Centro de Convenções",
            "zipCode": "01310-100",
            "city": "São Paulo",
            "state": "SP",
            "country": "Brasil",
            "district": "Bela Vista",
            "reference": "Próximo ao MASP"
          }
        }
      ],
      "recurrence": {
        "interval": "monthly",
        "startAt": "2025-08-06",
        "nextDueDate": "2025-09-06"
      },
      "paymentMethod": {
        "type": "credit",
        "card": {
          "cardId": "YOUR_CARD_ID"
        },
        "installments": 1
      },
      "status": "created",
      "amount": 29900,
      "liveMode": true,
      "createdAt": "2025-08-06T13:57:36.295605Z",
      "updatedAt": "2025-08-06T13:57:36.393955Z",
      "lastCycle": {
        "id": "cycle_id_example",
        "customerId": "YOUR_CUSTOMER_ID",
        "merchantId": "YOUR_MERCHANT_ID",
        "cycle": 1,
        "attempts": 1,
        "status": "pending",
        "isEmulated": false,
        "createdAt": "2025-08-06T13:57:36.3877Z",
        "scheduledAt": "2025-08-06",
        "paymentHistory": [
          {
            "id": "payment_history_id_example",
            "createdAt": "2025-08-06T13:57:36.396306294Z",
            "chargeId": null,
            "attemptNumber": 1,
            "status": "pending",
            "error": null
          }
        ]
      }
    },
    "errorCode": 404
  }
}

​
Observações importantes

  • Campo lastCycle: Sempre presente nas respostas individuais de subscription (GET, CREATE, UPDATE). Pode ser null se não houver cycles, ou um objeto completo com os detalhes do último cycle. Na cobrança instantânea, o campo conterá informações sobre o cycle processado imediatamente.
  • Status da assinatura:
  • Status da fatura:
    • Sucesso: authorized
    • Erro: retrying
  • Payment History: Contém detalhes de cada tentativa, incluindo erros
  • Next Attempt: Indica quando será a próxima tentativa de cobrança

​
Próximos passos

Gerenciar assinatura

Aprenda como gerenciar assinaturas após a criação

Configurar webhooks

Configure webhooks para receber notificações em tempo real