Integração

O motor de assinaturas da Malga permite criar assinaturas automáticas com cobranças recorrentes. Este guia mostra como configurar uma assinatura 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 à assinatura.

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"
    }
}'

{
    "id": "6204fc5c-434c-4b7f-a1e1-fbc3e5c55ad4",
    "name": "Maria Fernanda Souza",
    "email": "maria.souza@example.com",
    "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd",
    "phoneNumber": "+55 21 99888-9999",
    "createdAt": "2025-07-31T13:04:13.494Z",
    "document": {
        "number": "98765432100",
        "type": "cpf",
        "country": "BR"
    }
}

Passo 2: Salvar um Cartão

Para criar uma assinatura, 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"
}'

{
    "tokenId": "cc0b1e41-2936-45c5-947f-93995ffcdc00"
}

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"
}'

{
    "id": "4b12023e-9c76-4540-b720-5525066749c8",
    "status": "pending",
    "statusReason": null,
    "createdAt": "2025-07-31T13:12:27.095Z",
    "clientId": "YOUR_CLIENT_ID",
    "customerId": null,
    "brand": "Visa",
    "cardHolderName": "MARIA FERNANDA SOUZA",
    "cvvChecked": false,
    "fingerprint": "UiASDuDi7YeEFznY9oPrr11AAADUZLkBHT0F8n5Y2Vs=",
    "first6digits": "401959",
    "last4digits": "9339",
    "expirationMonth": "12",
    "expirationYear": "2026",
    "tokenFingerprint": "hUrLmnf8tjJN7+tTsknaUgh7XOsMztm02dlusWCJwBw="
}

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 assinatura

Agora você pode criar a assinatura recorrente com todos os dados necessários.

Os intervalos de assinatura disponíveis são: weekly (semanal), monthly (mensal), quarterly (trimestral), yearly (anual), biennial (bienal, a cada 2 anos) e triennial (trienal, a cada 3 anos). 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"
      }
    }
  ]
}'

{
    "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-07-30",
        "nextDueDate": "2025-08-30"
    },
    "paymentMethod": {
        "type": "credit",
        "card": {
            "cardId": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5"
        },
        "installments": 1
    },
    "status": "created",
    "amount": 29900,
    "liveMode": true,
    "createdAt": "2025-07-30T20:14:12.191866Z",
    "updatedAt": "2025-07-30T20:14:12.606647259Z"
}

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 assinaturas suporta períodos de trial gratuito. Durante o trial, a assinatura fica no status trialing e não gera faturas 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
  }
}'

{
  "id": "subscription_id_example",
  "name": "Assinatura Premium com Trial",
  "status": "trialing",
  "trialEnd": "2025-02-01",
  "amount": 9990,
  "recurrence": {
    "interval": "monthly",
    "dayOfMonth": 15,
    "startAt": "2025-02-01T00:00:00Z",
    "actualCycle": 0
  },
  "createdAt": "2025-01-20T10:00:00Z"
}

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 assinatura está criada, você pode:

Entenda cobranças instantâneas

Saiba como realizar cobranças instantâneas com a assinatura e entenda as suas particularidades.

Gerenciar assinatura

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

Ao pausar ou cancelar uma assinatura, as faturas pendentes (scheduled, pending, retrying) são automaticamente marcadas como canceled para preservar o histórico de auditoria. Faturas já finalizadas (authorized, failed) não são alteradas.

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.

Comece na Malga

Conexões

Guias

Serviços adicionais

Integração

Pré-requisitos

Passo 1: Criar um Customer

Exemplo de criação de customer

Passo 2: Salvar um Cartão

Criar um Token

Salvar o Cartão

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

Passo 3: Criar a assinatura

Assinaturas com Trial

Exemplo: Assinatura com Trial

Características dos Trials

Próximos passos

Entenda cobranças instantâneas

Gerenciar assinatura

Trial

Configurações

Configurar webhooks

Revisar a API de Subscriptions

Configurar webhooks

​Pré-requisitos

​Passo 1: Criar um Customer

​Exemplo de criação de customer

​Passo 2: Salvar um Cartão

​Criar um Token

​Salvar o Cartão

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

​Passo 3: Criar a assinatura

​Assinaturas com Trial

​Exemplo: Assinatura com Trial

​Características dos Trials

​Próximos passos

Entenda cobranças instantâneas

Gerenciar assinatura

Trial

Configurações

Configurar webhooks

Revisar a API de Subscriptions

Configurar webhooks

Pré-requisitos

Passo 1: Criar um Customer

Exemplo de criação de customer

Passo 2: Salvar um Cartão

Criar um Token

Salvar o Cartão

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

Passo 3: Criar a assinatura

Assinaturas com Trial

Exemplo: Assinatura com Trial

Características dos Trials

Próximos passos