Skip to main content
O motor de recorrência da Malga permite criar assinaturas automáticas com cobranças recorrentes. Este guia mostra como configurar uma recorrência completa desde a criação do customer até a assinatura.

​
Pré-requisitos

Antes de começar, você precisará de:
  • Merchant ID: Identificador do seu fluxo na Malga;
  • API Keys: Chaves de autenticação para acessar as APIs;
  • ClientId: Seu identificador na Malga.

​
Passo 1: Criar um Customer

Primeiro, você precisa criar um customer na Malga para associar à recorrência.
O customer é obrigatório para criar uma assinatura. Confira a documentação completa da API de Customers para mais detalhes.Adicionamos novos campos de endereço de entrega e de cobrança para melhor suporte a antifraude dos provedores de pagamento.

​
Exemplo de criação de customer

curl -X POST https://api.malga.io/v1/customers \
-H "X-Client-Id: YOUR_CLIENT_ID" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "name": "Maria Fernanda Souza",
    "email": "maria.souza@example.com",
    "phoneNumber": "+55 21 99888-9999",
    "document": {
        "number": "98765432100",
        "type": "cpf",
        "country": "BR"
    }
}'

​
Passo 2: Salvar um Cartão

Para criar uma recorrência, você precisa de um cartão salvo na Malga. O processo é dividido em duas etapas:

​
Criar um Token

Primeiro, crie um token com os dados do cartão.
O token é temporário e deve ser usado imediatamente para salvar o cartão. Confira a documentação da API de Tokens para mais detalhes.
curl -X POST https://api.malga.io/v1/tokens \
-H "X-Client-Id: YOUR_CLIENT_ID" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "cardHolderName": "MARIA FERNANDA SOUZA",
    "cardNumber": "4019598346009339",
    "cardCvv": "123",
    "cardExpirationDate": "12/2026"
}'

​
Salvar o Cartão

Agora, use o token para salvar o cartão.
O cartão salvo será usado para as cobranças recorrentes. Confira a documentação da API de Cards para mais detalhes.
curl -X POST https://api.malga.io/v1/cards \
-H "X-Client-Id: YOUR_CLIENT_ID" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "tokenId": "cc0b1e41-2936-45c5-947f-93995ffcdc00"
}'

​
Vincular o cartão de crédito ao customer (recomendado)

Não é obrigatório vincular o cartão de crédito ao customer, mas é recomendado para melhorar a experiência do cliente. Por padrão não vinculamos o cartão de crédito ao customer. Para fazer isso, utilize a API de Vinculação de cartão de crédito ao customer.
Request
curl -X POST https://api.malga.io/v1/customers/YOUR_CUSTOMER_ID/cards \
-H "X-Client-Id: YOUR_CLIENT_ID" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "cardId": "4b12023e-9c76-4540-b720-5525066749c8"
}'

​
Passo 3: Criar a Recorrência

Agora você pode criar a assinatura recorrente com todos os dados necessários.
Os intervalos de recorrência disponíveis são: weekly (semanal), monthly (mensal), quarterly (trimestral) e yearly (anual). Escolha o intervalo que melhor se adequa ao seu modelo de negócio.Novidade: Agora também suportamos assinaturas com período de trial gratuito - confira a documentação do sistema de trial.Importante: O campo startAt deve ser informado em formato UTC (YYYY-MM-DD).
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-07-30"
  },
  "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"
      }
    }
  ]
}'
Assinaturas trimestrais seguem a mesma estratégia de retentativas das assinaturas mensais e anuais: 5 tentativas em D+0, D+1, D+4, D+9 e D+16.

​
Assinaturas com Trial

O motor de recorrência suporta períodos de trial gratuito. Durante o trial, a assinatura fica no status trialing e não gera cycles de cobrança.

​
Exemplo: Assinatura com Trial

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 Trial",
  "merchantId": "YOUR_MERCHANT_ID",
  "customerId": "YOUR_CUSTOMER_ID",
  "items": [
    {
      "name": "Plano Premium",
      "description": "Acesso premium com período de trial",
      "amount": 9990,
      "quantity": 1
    }
  ],
  "recurrence": {
    "interval": "monthly",
    "dayOfMonth": 15
  },
  "trialEnd": "2025-02-01",
  "paymentMethod": {
    "type": "credit",
    "card": {
      "cardId": "YOUR_CARD_ID"
    },
    "installments": 1
  }
}'

​
Características dos Trials

  • Período gratuito: Cliente pode usar o serviço sem ser cobrado
  • Status trialing: Assinatura fica neste status durante o período
  • Transição automática: Ao expirar, transiciona para created
  • Apenas cancelamento: Durante o trial, apenas cancelamento é permitido (não pausar)
O campo trialEnd deve ser uma data no formato YYYY-MM-DD indicando quando o trial termina. Se startAt não for fornecido, será automaticamente definido como a data de término do trial.

​
Próximos passos

Agora que sua recorrência está criada, você pode:

Entenda pagamentos instantâneos

Saiba como realizar pagamentos instantâneos com a recorrência e entenda as suas particularidades.

Gerenciar assinatura

Ative, pause ou cancele a assinatura conforme necessário.

Trial

Configure períodos de trial gratuito para suas assinaturas.

Configurações

Personalize retentativas e statement descriptors.

Configurar webhooks

Configure regras de retentativa personalizadas para suas assinaturas.

Revisar a API de Subscriptions

Revise a documentação completa da API de Subscriptions.

Configurar webhooks

Receba notificações em tempo real sobre mudanças de status.