> ## 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.
# Integração
> Passo a passo para começar a usar o motor de recorrência
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](/api-reference/customers/criacao-de-novo-customer-para-cobranca)
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": "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 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](/api-reference/tokens/criar-um-novo-token) 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": "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](/api-reference/cards/criar-novo-cartao-a-partir-de-token) 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": "cc0b1e41-2936-45c5-947f-93995ffcdc00"
}'
```
```bash Response theme={null}
{
"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](/api-reference/customers/adicionar-cartao-de-credito-ao-customer).
```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": "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), **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](/documentations/more/recurrence/engine/trial-system).
**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": "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 recorrência 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",
"dayOfMonth": 15
},
"trialEnd": "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",
"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 recorrência está criada, você pode:
Saiba como realizar cobranças instantâneas com a recorrência e entenda as
suas particularidades.
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.
Configure períodos de trial gratuito para suas assinaturas.
Personalize retentativas e statement descriptors.
Configure regras de retentativa personalizadas para suas assinaturas.
Revise a documentação completa da API de Subscriptions.
Receba notificações em tempo real sobre mudanças de status.