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: daily (diário), weekly (semanal), monthly (mensal) e yearly (anual). Escolha o intervalo que melhor se adequa ao seu modelo de negócio.
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": "225d39bc-1fbb-480a-90bd-f0caad05d2d0",
  "customerId": "2a8b64ce-904c-4256-b79a-49525808609c",
  "referenceKey": "SUB-PREMIUM-001",
  "recurrence": {
    "interval": "monthly",
    "startAt": "2025-07-30"
  },
  "paymentSource": {
    "sourceType": "card",
    "cardId": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5"
  },
  "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"
      }
    }
  ]
}'

​
Próximos Passos

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

Gerenciar assinatura

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

Configurar webhooks

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

Revisar a API de Subscriptions

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