curl --request POST \
--url https://api.malga.io/v1/subscriptions \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--header 'X-Client-Id: <api-key>' \
--data '
{
"name": "Assinatura Premium com Eventos",
"merchantId": "90d64a51-d442-426c-bbf9-b66e000e5576",
"customerId": "b99e159e-27d5-4927-b46e-ae7348f20131",
"items": [
{
"name": "Ingresso VIP Mensal",
"amount": 29900,
"quantity": 1,
"description": "Acesso VIP premium a eventos mensais",
"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,
"quantityEventHouse": 0,
"convenienceFeeValue": 15.5,
"quantityFull": 1,
"quantityHalf": 0,
"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",
"cycles": 12,
"startAt": "2025-07-30"
},
"paymentMethod": {
"type": "credit",
"card": {
"cardId": "bfb60d16-108c-440b-bdb8-bbe67140f936",
"cvv": "123"
},
"installments": 1
},
"referenceKey": "SUB-PREMIUM-001",
"trial": {
"endDate": "2025-08-15"
},
"splitRules": [
{
"sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08",
"percentage": 70,
"processingFee": false,
"chargeEntireFee": false,
"chargeRemainderFee": false,
"liable": true,
"fares": {
"mdr": 2.5,
"fee": 0.3
}
}
],
"cancelAtPeriodEnd": false,
"scheduledCancellationAt": "2025-12-31",
"scheduledCancellationReason": "Cliente solicitou cancelamento"
}
'const options = {
method: 'POST',
headers: {
'X-Client-Id': '<api-key>',
'X-Api-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Assinatura Premium com Eventos',
merchantId: '90d64a51-d442-426c-bbf9-b66e000e5576',
customerId: 'b99e159e-27d5-4927-b46e-ae7348f20131',
items: [
{
name: 'Ingresso VIP Mensal',
amount: 29900,
quantity: 1,
description: 'Acesso VIP premium a eventos mensais',
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,
quantityEventHouse: 0,
convenienceFeeValue: 15.5,
quantityFull: 1,
quantityHalf: 0,
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', cycles: 12, startAt: '2025-07-30'},
paymentMethod: {
type: 'credit',
card: {cardId: 'bfb60d16-108c-440b-bdb8-bbe67140f936', cvv: '123'},
installments: 1
},
referenceKey: 'SUB-PREMIUM-001',
trial: {endDate: '2025-08-15'},
splitRules: [
{
sellerId: 'd98106e8-568a-44c3-94d0-0e0bbd8b7e08',
percentage: 70,
processingFee: false,
chargeEntireFee: false,
chargeRemainderFee: false,
liable: true,
fares: {mdr: 2.5, fee: 0.3}
}
],
cancelAtPeriodEnd: false,
scheduledCancellationAt: '2025-12-31',
scheduledCancellationReason: 'Cliente solicitou cancelamento'
})
};
fetch('https://api.malga.io/v1/subscriptions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.malga.io/v1/subscriptions"
payload := strings.NewReader("{\n \"name\": \"Assinatura Premium com Eventos\",\n \"merchantId\": \"90d64a51-d442-426c-bbf9-b66e000e5576\",\n \"customerId\": \"b99e159e-27d5-4927-b46e-ae7348f20131\",\n \"items\": [\n {\n \"name\": \"Ingresso VIP Mensal\",\n \"amount\": 29900,\n \"quantity\": 1,\n \"description\": \"Acesso VIP premium a eventos mensais\",\n \"sku\": \"VIP-EVENT-001\",\n \"risk\": \"Low\",\n \"categoryId\": \"entertainment\",\n \"locality\": \"São Paulo\",\n \"date\": \"2025-12-01\",\n \"type\": 1,\n \"genre\": \"Shows e Eventos\",\n \"tickets\": {\n \"quantityTicketSale\": 1,\n \"quantityEventHouse\": 0,\n \"convenienceFeeValue\": 15.5,\n \"quantityFull\": 1,\n \"quantityHalf\": 0,\n \"batch\": 1\n },\n \"location\": {\n \"street\": \"Av. Paulista\",\n \"number\": \"1000\",\n \"complement\": \"Centro de Convenções\",\n \"zipCode\": \"01310-100\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"Brasil\",\n \"district\": \"Bela Vista\",\n \"reference\": \"Próximo ao MASP\"\n }\n }\n ],\n \"recurrence\": {\n \"interval\": \"monthly\",\n \"cycles\": 12,\n \"startAt\": \"2025-07-30\"\n },\n \"paymentMethod\": {\n \"type\": \"credit\",\n \"card\": {\n \"cardId\": \"bfb60d16-108c-440b-bdb8-bbe67140f936\",\n \"cvv\": \"123\"\n },\n \"installments\": 1\n },\n \"referenceKey\": \"SUB-PREMIUM-001\",\n \"trial\": {\n \"endDate\": \"2025-08-15\"\n },\n \"splitRules\": [\n {\n \"sellerId\": \"d98106e8-568a-44c3-94d0-0e0bbd8b7e08\",\n \"percentage\": 70,\n \"processingFee\": false,\n \"chargeEntireFee\": false,\n \"chargeRemainderFee\": false,\n \"liable\": true,\n \"fares\": {\n \"mdr\": 2.5,\n \"fee\": 0.3\n }\n }\n ],\n \"cancelAtPeriodEnd\": false,\n \"scheduledCancellationAt\": \"2025-12-31\",\n \"scheduledCancellationReason\": \"Cliente solicitou cancelamento\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Client-Id", "<api-key>")
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}Criação de uma nova assinatura
Cria uma assinatura no Motor de Assinaturas.
Cobrança na criação. O primeiro ciclo é cobrado na mesma chamada quando recurrence.startAt é hoje ou ontem (UTC), ou quando startAt é omitido e não há trial. A resposta é 201 mesmo se essa cobrança falhar: confira o resultado em lastCycle.status e em lastCycle.paymentHistory. Com trial, a assinatura nasce trialing e a primeira cobrança acontece em trial.endDate.
Datas. Sem startAt e sem trial, o início é hoje. startAt anterior a ontem (UTC) devolve 400. Sem recurrence.interval, vale monthly.
Sem idempotência. Repetir a requisição, por exemplo depois de um timeout, cria outra assinatura e faz outra cobrança. Antes de repetir, procure pelo seu referenceKey na listagem de assinaturas.
curl --request POST \
--url https://api.malga.io/v1/subscriptions \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--header 'X-Client-Id: <api-key>' \
--data '
{
"name": "Assinatura Premium com Eventos",
"merchantId": "90d64a51-d442-426c-bbf9-b66e000e5576",
"customerId": "b99e159e-27d5-4927-b46e-ae7348f20131",
"items": [
{
"name": "Ingresso VIP Mensal",
"amount": 29900,
"quantity": 1,
"description": "Acesso VIP premium a eventos mensais",
"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,
"quantityEventHouse": 0,
"convenienceFeeValue": 15.5,
"quantityFull": 1,
"quantityHalf": 0,
"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",
"cycles": 12,
"startAt": "2025-07-30"
},
"paymentMethod": {
"type": "credit",
"card": {
"cardId": "bfb60d16-108c-440b-bdb8-bbe67140f936",
"cvv": "123"
},
"installments": 1
},
"referenceKey": "SUB-PREMIUM-001",
"trial": {
"endDate": "2025-08-15"
},
"splitRules": [
{
"sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08",
"percentage": 70,
"processingFee": false,
"chargeEntireFee": false,
"chargeRemainderFee": false,
"liable": true,
"fares": {
"mdr": 2.5,
"fee": 0.3
}
}
],
"cancelAtPeriodEnd": false,
"scheduledCancellationAt": "2025-12-31",
"scheduledCancellationReason": "Cliente solicitou cancelamento"
}
'const options = {
method: 'POST',
headers: {
'X-Client-Id': '<api-key>',
'X-Api-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Assinatura Premium com Eventos',
merchantId: '90d64a51-d442-426c-bbf9-b66e000e5576',
customerId: 'b99e159e-27d5-4927-b46e-ae7348f20131',
items: [
{
name: 'Ingresso VIP Mensal',
amount: 29900,
quantity: 1,
description: 'Acesso VIP premium a eventos mensais',
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,
quantityEventHouse: 0,
convenienceFeeValue: 15.5,
quantityFull: 1,
quantityHalf: 0,
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', cycles: 12, startAt: '2025-07-30'},
paymentMethod: {
type: 'credit',
card: {cardId: 'bfb60d16-108c-440b-bdb8-bbe67140f936', cvv: '123'},
installments: 1
},
referenceKey: 'SUB-PREMIUM-001',
trial: {endDate: '2025-08-15'},
splitRules: [
{
sellerId: 'd98106e8-568a-44c3-94d0-0e0bbd8b7e08',
percentage: 70,
processingFee: false,
chargeEntireFee: false,
chargeRemainderFee: false,
liable: true,
fares: {mdr: 2.5, fee: 0.3}
}
],
cancelAtPeriodEnd: false,
scheduledCancellationAt: '2025-12-31',
scheduledCancellationReason: 'Cliente solicitou cancelamento'
})
};
fetch('https://api.malga.io/v1/subscriptions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.malga.io/v1/subscriptions"
payload := strings.NewReader("{\n \"name\": \"Assinatura Premium com Eventos\",\n \"merchantId\": \"90d64a51-d442-426c-bbf9-b66e000e5576\",\n \"customerId\": \"b99e159e-27d5-4927-b46e-ae7348f20131\",\n \"items\": [\n {\n \"name\": \"Ingresso VIP Mensal\",\n \"amount\": 29900,\n \"quantity\": 1,\n \"description\": \"Acesso VIP premium a eventos mensais\",\n \"sku\": \"VIP-EVENT-001\",\n \"risk\": \"Low\",\n \"categoryId\": \"entertainment\",\n \"locality\": \"São Paulo\",\n \"date\": \"2025-12-01\",\n \"type\": 1,\n \"genre\": \"Shows e Eventos\",\n \"tickets\": {\n \"quantityTicketSale\": 1,\n \"quantityEventHouse\": 0,\n \"convenienceFeeValue\": 15.5,\n \"quantityFull\": 1,\n \"quantityHalf\": 0,\n \"batch\": 1\n },\n \"location\": {\n \"street\": \"Av. Paulista\",\n \"number\": \"1000\",\n \"complement\": \"Centro de Convenções\",\n \"zipCode\": \"01310-100\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"Brasil\",\n \"district\": \"Bela Vista\",\n \"reference\": \"Próximo ao MASP\"\n }\n }\n ],\n \"recurrence\": {\n \"interval\": \"monthly\",\n \"cycles\": 12,\n \"startAt\": \"2025-07-30\"\n },\n \"paymentMethod\": {\n \"type\": \"credit\",\n \"card\": {\n \"cardId\": \"bfb60d16-108c-440b-bdb8-bbe67140f936\",\n \"cvv\": \"123\"\n },\n \"installments\": 1\n },\n \"referenceKey\": \"SUB-PREMIUM-001\",\n \"trial\": {\n \"endDate\": \"2025-08-15\"\n },\n \"splitRules\": [\n {\n \"sellerId\": \"d98106e8-568a-44c3-94d0-0e0bbd8b7e08\",\n \"percentage\": 70,\n \"processingFee\": false,\n \"chargeEntireFee\": false,\n \"chargeRemainderFee\": false,\n \"liable\": true,\n \"fares\": {\n \"mdr\": 2.5,\n \"fee\": 0.3\n }\n }\n ],\n \"cancelAtPeriodEnd\": false,\n \"scheduledCancellationAt\": \"2025-12-31\",\n \"scheduledCancellationReason\": \"Cliente solicitou cancelamento\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Client-Id", "<api-key>")
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}Body
Nome da assinatura. Sem statementDescriptor nas configurações, é o texto enviado para a fatura do cartão
100"Assinatura Premium com Eventos"
Identificador do merchant
"90d64a51-d442-426c-bbf9-b66e000e5576"
Identificador do cliente
"b99e159e-27d5-4927-b46e-ae7348f20131"
Itens cobrados a cada ciclo. O valor do ciclo é a soma de amount vezes quantity de todos os itens
1Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Chave de referência da assinatura no seu sistema. Não pode ser alterada depois da criação
"SUB-PREMIUM-001"
Período de trial (opcional). O nome do campo é endDate. Um campo com outro nome é ignorado sem erro, e a assinatura nasce sem trial e é cobrada conforme startAt
Show child attributes
Show child attributes
Regras de divisão de valores entre recebedores (opcional). Assinaturas aceitam split só por percentage
Show child attributes
Show child attributes
Cria a assinatura já com cancelamento agendado. Com true e recurrence.cycles definido, cycles passa a ser o ciclo atual mais um
false
Data do cancelamento agendado (YYYY-MM-DD). Exige cancelAtPeriodEnd igual a true e não pode ser anterior a ontem (UTC). Sem esta data, o cancelamento acontece em trial.endDate ou, sem trial, em recurrence.nextDueDate
"2025-12-31"
Motivo do cancelamento agendado (opcional)
"Cliente solicitou cancelamento"
Response
Assinatura criada. Se o primeiro ciclo foi cobrado na criação, lastCycle traz o resultado da cobrança, que pode ter falhado
Identificador da assinatura
"abecf6d6-153e-4fc9-8222-8be5441de581"
Nome da assinatura
"Assinatura Premium com Eventos"
Identificador do client
"567265cb-fa7f-419f-9c1c-8e878dd2faf7"
Identificador do merchant
"90d64a51-d442-426c-bbf9-b66e000e5576"
Identificador do cliente
"b99e159e-27d5-4927-b46e-ae7348f20131"
Chave de referência da assinatura
"SUB-PREMIUM-001"
Moeda da assinatura
"BRL"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Período de trial. Só vem quando a assinatura foi criada com trial
Show child attributes
Show child attributes
Regras de divisão de valores entre recebedores. Só vem quando a assinatura tem split
Show child attributes
Show child attributes
Status da assinatura
created, active, paused, canceled, unpaid, expired, trialing "created"
Valor de cada ciclo em centavos, a soma de amount vezes quantity dos itens
29900
Indica se a assinatura está em modo de produção
true
Último ciclo da assinatura. Sempre presente nas respostas individuais (GET, CREATE, UPDATE), pode ser null se não houver ciclos. Não traz items.
Show child attributes
Show child attributes
"2025-07-31T13:36:40.118822Z"
"2025-07-31T13:36:40.118822Z"
Indica se a assinatura tem cancelamento agendado. Enquanto for true, recurrence.cycles mostra o ciclo atual mais um, e o valor anterior volta quando o agendamento é removido
true
Data efetiva do cancelamento agendado (YYYY-MM-DD). Só vem quando cancelAtPeriodEnd é true. Sem data enviada, é trial.endDate ou, sem trial, recurrence.nextDueDate
"2025-12-31"
Motivo do cancelamento agendado. Só vem quando foi informado
"Cliente solicitou cancelamento"
Was this page helpful?