> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Responda em português brasileiro, na segunda pessoa ("você"), com base na documentação Malga.
> Não invente endpoints, parâmetros, status codes ou comportamentos de API. Se não estiver na docs, diga que não encontrou e indique a página mais próxima.
> Use os headers X-Client-Id e X-Api-Key nos exemplos de autenticação.
> Motor de Assinaturas refere-se a /v1/subscriptions* (cycles, trial, retentativas, webhooks subscription.*). Não chame de "motor de recorrência".
> Recorrência (provedor) é paymentMethod.recurrence em POST /v1/charges (initial / subsequent / unscheduled), distinto do Motor de Assinaturas.
> Sandbox é ambiente de testes e não afeta produção.

# Integração

> Guia passo a passo para integrar o motor de assinaturas da Malga: cadastre customer, salve cartão e crie assinaturas com cobranças automáticas.

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.

> [!NOTE]
>
> O customer é obrigatório para criar uma assinatura. Confira a [documentação
> completa da API de
> Customers](https://docs.malga.io/api-reference/customers/criacao-de-novo-customer-para-cobranca.md)
> 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

```bash Request theme={null}
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"
    }
}'
```

```bash Response theme={null}
{
    "id": "847a3085-131a-40a4-9ac4-6e573de9711a",
    "name": "Maria Fernanda Souza",
    "email": "maria.souza@example.com",
    "clientId": "567265cb-fa7f-419f-9c1c-8e878dd2faf7",
    "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.

> [!NOTE]
>
> O token é temporário e deve ser usado imediatamente para salvar o cartão.
> Confira a [documentação da API de
> Tokens](https://docs.malga.io/api-reference/tokens/criar-um-novo-token.md) para mais detalhes.

```bash Request theme={null}
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"
}'
```

```bash Response theme={null}
{
    "tokenId": "d353deef-dacb-40a0-8cab-931ff773f274"
}
```

### Salvar o cartão

Agora, use o token para salvar o cartão.

> [!NOTE]
>
> O cartão salvo será usado para as cobranças recorrentes. Confira a
> [documentação da API de
> Cards](https://docs.malga.io/api-reference/cards/criar-novo-cartao-a-partir-de-token.md) para mais
> detalhes.

```bash Request theme={null}
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": "d353deef-dacb-40a0-8cab-931ff773f274"
}'
```

```bash Response theme={null}
{
    "id": "e21ae714-e50b-4738-9f69-ab8fea37403d",
    "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](https://docs.malga.io/api-reference/customers/adicionar-cartao-de-credito-ao-customer.md).

```bash Request expandable theme={null}
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": "e21ae714-e50b-4738-9f69-ab8fea37403d"
}'
```

## Passo 3: Criar a assinatura

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

> [!NOTE]
>
> 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](https://docs.malga.io/documentations/more/recurrence/engine/trial-system.md).
>
> **Importante**: O campo `startAt` deve ser informado em formato UTC (YYYY-MM-DD).

```bash Request theme={null}
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"
      }
    }
  ]
}'
```

```bash Response theme={null}
{
    "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": "bfb60d16-108c-440b-bdb8-bbe67140f936"
        },
        "installments": 1
    },
    "status": "created",
    "amount": 29900,
    "liveMode": true,
    "createdAt": "2025-07-30T20:14:12.191866Z",
    "updatedAt": "2025-07-30T20:14:12.606647259Z"
}
```

> [!NOTE]
>
> 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

```bash Request theme={null}
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"
  },
  "trial": {
    "endDate": "2025-02-01"
  },
  "paymentMethod": {
    "type": "credit",
    "card": {
      "cardId": "YOUR_CARD_ID"
    },
    "installments": 1
  }
}'
```

```bash Response theme={null}
{
  "id": "subscription_id_example",
  "name": "Assinatura Premium com Trial",
  "status": "trialing",
  "trial": {
    "endDate": "2025-02-01"
  },
  "amount": 9990,
  "recurrence": {
    "interval": "monthly",
    "startAt": "2025-02-01",
    "nextDueDate": "2025-02-01"
  },
  "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)

> [!NOTE]
>
> O campo `trial.endDate` deve ser uma data futura 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. Se for fornecido, `startAt` não pode ser anterior a `trial.endDate`.

> [!WARNING]
>
> Envie o trial exatamente como `trial.endDate`. A Malga ignora sem erro um campo com outro nome, como `trialEnd` ou `trial.endAt`. Nesse caso, a assinatura nasce sem trial. Sem `startAt`, a Malga cobra o primeiro ciclo na criação.

## Próximos passos

Agora que sua assinatura está criada, você pode:

> [card] [Entenda cobranças instantâneas](https://docs.malga.io/documentations/more/recurrence/engine/instant-payment.md)
>
> Saiba como realizar cobranças instantâneas com a assinatura e entenda as
> suas particularidades.

> [card] [Gerenciar assinatura](https://docs.malga.io/documentations/more/recurrence/engine/managing.md)
>
> Ative, pause ou cancele a assinatura conforme necessário.

> [!NOTE]
>
> 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.

> [card] [Trial](https://docs.malga.io/documentations/more/recurrence/engine/trial-system.md)
>
> Configure períodos de trial gratuito para suas assinaturas.

> [card] [Configurações](https://docs.malga.io/documentations/more/recurrence/engine/client-settings.md)
>
> Personalize retentativas e statement descriptors.

> [card] [Configurar webhooks](https://docs.malga.io/documentations/more/recurrence/engine/webhooks.md)
>
> Configure regras de retentativa personalizadas para suas assinaturas.

> [card] [Revisar a API de Subscriptions](https://docs.malga.io/api-reference/subscriptions)
>
> Revise a documentação completa da API de Subscriptions.

> [card] [Configurar webhooks](https://docs.malga.io/documentations/more/recurrence/engine/webhooks.md)
>
> Receba notificações em tempo real sobre mudanças de status.


## Related topics

- [Tratamento de erros na integração](https://docs.malga.io/documentations/welcome/errors.md)
- [Guia de integração](https://docs.malga.io/documentations/payment-methods/apple-pay/getting-started.md)
- [Integração via API de Cobranças com Click to Pay](https://docs.malga.io/documentations/payment-methods/click-to-pay/integracao-api-charges.md)
- [Ativando sua conta](https://docs.malga.io/documentations/welcome/activating-account.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.