Criação de uma nova assinatura

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": "225d39bc-1fbb-480a-90bd-f0caad05d2d0",
  "customerId": "2a8b64ce-904c-4256-b79a-49525808609c",
  "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",
        "quantityHalf": 0,
        "batch": 1
      }
    }
  ],
  "recurrence": {
    "interval": "monthly",
    "cycles": 123,
    "startAt": "2025-07-30"
  },
  "paymentMethod": {
    "type": "credit",
    "card": {
      "cardId": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5",
      "cvv": "123"
    },
    "installments": 1
  },
  "referenceKey": "SUB-PREMIUM-001",
  "trial": {
    "endAt": "2025-08-15"
  },
  "splitRules": [
    {
      "sellerId": "seller-primary-001",
      "percentage": 70,
      "amount": 5000,
      "processingFee": false,
      "chargeEntireFee": false,
      "chargeRemainderFee": false,
      "liable": true,
      "fares": {
        "mdr": 2.5,
        "fee": 0.3
      }
    }
  ]
}
'

{
  "id": "019860b2-feb8-7edf-b5ba-0c48a7a8bd3f",
  "name": "Assinatura Premium com Eventos",
  "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd",
  "merchantId": "225d39bc-1fbb-480a-90bd-f0caad05d2d0",
  "customerId": "2a8b64ce-904c-4256-b79a-49525808609c",
  "referenceKey": "SUB-PREMIUM-001",
  "currency": "BRL",
  "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",
        "quantityHalf": 0,
        "batch": 1
      }
    }
  ],
  "recurrence": {
    "interval": "monthly",
    "cycles": 12,
    "startAt": "2025-08-10",
    "endAt": "2026-08-10",
    "nextDueDate": "2025-07-30"
  },
  "paymentMethod": {
    "type": "credit",
    "card": {
      "cardId": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5"
    },
    "installments": 1
  },
  "trial": {
    "endAt": "2025-08-15"
  },
  "splitRules": [
    {
      "sellerId": "seller-primary-001",
      "percentage": 70,
      "amount": 5000,
      "processingFee": false,
      "chargeEntireFee": false,
      "chargeRemainderFee": false,
      "liable": true,
      "fares": {
        "mdr": 2.5,
        "fee": 0.3
      }
    }
  ],
  "status": "created",
  "amount": 29900,
  "liveMode": true,
  "lastCycle": {
    "id": "01985cf8-9877-7c09-bbf6-2cceb3384a61",
    "customerId": "2a8b64ce-904c-4256-b79a-49525808609c",
    "merchantId": "225d39bc-1fbb-480a-90bd-f0caad05d2d0",
    "cycle": 1,
    "status": "authorized",
    "createdAt": "2025-07-30T20:14:12.599715Z",
    "paymentHistory": [
      {
        "id": "84ec50c5-1fb4-4d6b-bbff-fedc47ba9fa3",
        "createdAt": "2025-07-30T20:14:12.608115Z",
        "chargeId": "6f2a0713-c4cd-4e2d-8603-69855902676d",
        "status": "authorized"
      }
    ]
  },
  "createdAt": "2025-07-31T13:36:40.118822Z",
  "updatedAt": "2025-07-31T13:36:40.118822Z"
}

POST

subscriptions

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": "225d39bc-1fbb-480a-90bd-f0caad05d2d0",
  "customerId": "2a8b64ce-904c-4256-b79a-49525808609c",
  "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",
        "quantityHalf": 0,
        "batch": 1
      }
    }
  ],
  "recurrence": {
    "interval": "monthly",
    "cycles": 123,
    "startAt": "2025-07-30"
  },
  "paymentMethod": {
    "type": "credit",
    "card": {
      "cardId": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5",
      "cvv": "123"
    },
    "installments": 1
  },
  "referenceKey": "SUB-PREMIUM-001",
  "trial": {
    "endAt": "2025-08-15"
  },
  "splitRules": [
    {
      "sellerId": "seller-primary-001",
      "percentage": 70,
      "amount": 5000,
      "processingFee": false,
      "chargeEntireFee": false,
      "chargeRemainderFee": false,
      "liable": true,
      "fares": {
        "mdr": 2.5,
        "fee": 0.3
      }
    }
  ]
}
'

{
  "id": "019860b2-feb8-7edf-b5ba-0c48a7a8bd3f",
  "name": "Assinatura Premium com Eventos",
  "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd",
  "merchantId": "225d39bc-1fbb-480a-90bd-f0caad05d2d0",
  "customerId": "2a8b64ce-904c-4256-b79a-49525808609c",
  "referenceKey": "SUB-PREMIUM-001",
  "currency": "BRL",
  "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",
        "quantityHalf": 0,
        "batch": 1
      }
    }
  ],
  "recurrence": {
    "interval": "monthly",
    "cycles": 12,
    "startAt": "2025-08-10",
    "endAt": "2026-08-10",
    "nextDueDate": "2025-07-30"
  },
  "paymentMethod": {
    "type": "credit",
    "card": {
      "cardId": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5"
    },
    "installments": 1
  },
  "trial": {
    "endAt": "2025-08-15"
  },
  "splitRules": [
    {
      "sellerId": "seller-primary-001",
      "percentage": 70,
      "amount": 5000,
      "processingFee": false,
      "chargeEntireFee": false,
      "chargeRemainderFee": false,
      "liable": true,
      "fares": {
        "mdr": 2.5,
        "fee": 0.3
      }
    }
  ],
  "status": "created",
  "amount": 29900,
  "liveMode": true,
  "lastCycle": {
    "id": "01985cf8-9877-7c09-bbf6-2cceb3384a61",
    "customerId": "2a8b64ce-904c-4256-b79a-49525808609c",
    "merchantId": "225d39bc-1fbb-480a-90bd-f0caad05d2d0",
    "cycle": 1,
    "status": "authorized",
    "createdAt": "2025-07-30T20:14:12.599715Z",
    "paymentHistory": [
      {
        "id": "84ec50c5-1fb4-4d6b-bbff-fedc47ba9fa3",
        "createdAt": "2025-07-30T20:14:12.608115Z",
        "chargeId": "6f2a0713-c4cd-4e2d-8603-69855902676d",
        "status": "authorized"
      }
    ]
  },
  "createdAt": "2025-07-31T13:36:40.118822Z",
  "updatedAt": "2025-07-31T13:36:40.118822Z"
}

Authorizations

X-Client-Id

string

header

required

X-Api-Key

string

header

required

Body

application/json

name

string

required

Nome da assinatura

Example:

"Assinatura Premium com Eventos"

merchantId

string<uuid>

required

Identificador do merchant

Example:

"225d39bc-1fbb-480a-90bd-f0caad05d2d0"

customerId

string<uuid>

required

Identificador do cliente

Example:

"2a8b64ce-904c-4256-b79a-49525808609c"

items

object[]

required

Show child attributes

items.name

string

required

Nome do item

Example:

"Ingresso VIP Mensal"

items.amount

integer

required

Valor do item em centavos

Example:

29900

items.quantity

integer

required

Quantidade do item

Example:

1

items.description

string

Descrição do item

Example:

"Acesso VIP premium a eventos mensais"

items.sku

string

Código de identificação do item

Example:

"VIP-EVENT-001"

items.risk

enum<string>

Nível de risco da transação

Available options:

Low,

High

Example:

"Low"

items.categoryId

string

Categoria do item

Example:

"entertainment"

items.locality

string

Localidade do evento

Example:

"São Paulo"

items.date

string<date>

Data do evento

Example:

"2025-12-01"

items.type

integer

Tipo de item

Example:

1

items.genre

string

Gênero do evento

Example:

"Shows e Eventos"

items.tickets

object

Show child attributes

items.tickets.quantityTicketSale

integer

Quantidade de ingressos à venda

Example:

1

items.tickets.quantityEventHouse

integer | null

Quantidade de ingressos da casa de eventos

Example:

0

items.tickets.convenienceFeeValue

number<float>

Valor da taxa de conveniência

Example:

15.5

items.tickets.quantityFull

integer

Quantidade de ingressos inteiros

Example:

1

items.tickets.quantityHalf

integer

Quantidade de ingressos meia-entrada

Example:

0

items.tickets.batch

integer

Lote do ingresso

Example:

1

items.location

object

Show child attributes

items.location.street

string

Nome da rua

Example:

"Av. Paulista"

items.location.number

string

Número do endereço

Example:

"1000"

items.location.complement

string

Complemento do endereço

Example:

"Centro de Convenções"

items.location.zipCode

string

CEP

Example:

"01310-100"

items.location.city

string

Cidade

Example:

"São Paulo"

items.location.state

string

Estado

Example:

"SP"

items.location.country

string

País

Example:

"Brasil"

items.location.district

string

Bairro

Example:

"Bela Vista"

items.location.reference

string

Ponto de referência

Example:

"Próximo ao MASP"

items.location.quantityHalf

integer | null

Example:

0

items.location.batch

integer

Example:

1

recurrence

object

required

Show child attributes

recurrence.interval

enum<string>

Intervalo de recorrência

Available options:

weekly,

monthly,

quarterly,

yearly

Example:

"monthly"

recurrence.cycles

number

Quantidade de ciclos de recorrência

recurrence.startAt

string

Data de início da assinatura em formato YYYY-MM-DD (UTC)

Example:

"2025-07-30"

paymentMethod

object

required

Show child attributes

paymentMethod.type

enum<string>

required

Tipo de método de pagamento

Available options:

credit

Example:

"credit"

paymentMethod.card

object

required

Show child attributes

paymentMethod.card.cardId

string<uuid>

required

Identificador do cartão

Example:

"ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5"

paymentMethod.card.cvv

string

Código de segurança do cartão

Example:

"123"

paymentMethod.installments

integer

Número de parcelas

Example:

1

referenceKey

string

Chave de referência da assinatura no seu sistema

Example:

"SUB-PREMIUM-001"

trial

object

Configuração do período de trial (opcional)

Show child attributes

trial.endAt

string<date>

Data de término do período de trial em formato YYYY-MM-DD

Example:

"2025-08-15"

splitRules

object[]

Regras de divisão de valores entre recebedores (opcional)

Show child attributes

splitRules.sellerId

string<uuid>

identificador do recebedor já cadastrado na API de sellers

Example:

"seller-primary-001"

splitRules.percentage

number | null

porcentagem do valor da transação que será enviada ao recebedor

Example:

70

splitRules.amount

number | null

valor que será enviado ao recebedor em centavos

Example:

5000

splitRules.processingFee

boolean

indica se o recebedor vinculado à regra será cobrado pelas taxas da transação

Example:

false

splitRules.chargeEntireFee

boolean

indica se o recebedor será cobrado pela taxa inteira da transação

Example:

false

splitRules.chargeRemainderFee

boolean

indica se o recebedor será cobrado pela taxa restante da transação

Example:

false

splitRules.liable

boolean

indica se o recebedor atrelado assumirá os riscos de chargeback da transação

Example:

true

splitRules.fares

object

Informações sobre as taxas que serão cobradas do recebedor

Show child attributes

splitRules.fares.mdr

number

Percentual MDR (Merchant Discount Rate)

Example:

2.5

splitRules.fares.fee

number

Taxa fixa por transação

Example:

0.3

Response

201 - application/json

Created

string<uuid>

Identificador da assinatura

Example:

"019860b2-feb8-7edf-b5ba-0c48a7a8bd3f"

name

string

Nome da assinatura

Example:

"Assinatura Premium com Eventos"

clientId

string<uuid>

Identificador do client

Example:

"e234eeb3-483d-4df2-87eb-1e2be5cdaccd"

merchantId

string<uuid>

Identificador do merchant

Example:

"225d39bc-1fbb-480a-90bd-f0caad05d2d0"

customerId

string<uuid>

Identificador do cliente

Example:

"2a8b64ce-904c-4256-b79a-49525808609c"

referenceKey

string

Chave de referência da assinatura

Example:

"SUB-PREMIUM-001"

currency

string

Moeda da assinatura

Example:

"BRL"

items

object[]

Show child attributes

items.name

string

required

Nome do item

Example:

"Ingresso VIP Mensal"

items.amount

integer

required

Valor do item em centavos

Example:

29900

items.quantity

integer

required

Quantidade do item

Example:

1

items.description

string

Descrição do item

Example:

"Acesso VIP premium a eventos mensais"

items.sku

string

Código de identificação do item

Example:

"VIP-EVENT-001"

items.risk

enum<string>

Nível de risco da transação

Available options:

Low,

High

Example:

"Low"

items.categoryId

string

Categoria do item

Example:

"entertainment"

items.locality

string

Localidade do evento

Example:

"São Paulo"

items.date

string<date>

Data do evento

Example:

"2025-12-01"

items.type

integer

Tipo de item

Example:

1

items.genre

string

Gênero do evento

Example:

"Shows e Eventos"

items.tickets

object

Show child attributes

items.tickets.quantityTicketSale

integer

Quantidade de ingressos à venda

Example:

1

items.tickets.quantityEventHouse

integer | null

Quantidade de ingressos da casa de eventos

Example:

0

items.tickets.convenienceFeeValue

number<float>

Valor da taxa de conveniência

Example:

15.5

items.tickets.quantityFull

integer

Quantidade de ingressos inteiros

Example:

1

items.tickets.quantityHalf

integer

Quantidade de ingressos meia-entrada

Example:

0

items.tickets.batch

integer

Lote do ingresso

Example:

1

items.location

object

Show child attributes

items.location.street

string

Nome da rua

Example:

"Av. Paulista"

items.location.number

string

Número do endereço

Example:

"1000"

items.location.complement

string

Complemento do endereço

Example:

"Centro de Convenções"

items.location.zipCode

string

CEP

Example:

"01310-100"

items.location.city

string

Cidade

Example:

"São Paulo"

items.location.state

string

Estado

Example:

"SP"

items.location.country

string

País

Example:

"Brasil"

items.location.district

string

Bairro

Example:

"Bela Vista"

items.location.reference

string

Ponto de referência

Example:

"Próximo ao MASP"

items.location.quantityHalf

integer | null

Example:

0

items.location.batch

integer

Example:

1

recurrence

object

Show child attributes

recurrence.interval

enum<string>

Available options:

weekly,

monthly,

yearly

Example:

"monthly"

recurrence.cycles

integer

Example:

12

recurrence.startAt

string<date>

Data de início da assinatura (UTC)

Example:

"2025-08-10"

recurrence.endAt

string<date>

Example:

"2026-08-10"

recurrence.nextDueDate

string<date>

Próxima data de vencimento da assinatura

Example:

"2025-07-30"

paymentMethod

object

Show child attributes

paymentMethod.type

enum<string>

required

Tipo de método de pagamento

Available options:

credit

Example:

"credit"

paymentMethod.card

object

required

Show child attributes

paymentMethod.card.cardId

string<uuid>

required

Identificador do cartão

Example:

"ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5"

paymentMethod.installments

integer

Número de parcelas

Example:

1

trial

object

Informações do período de trial (se aplicável)

Show child attributes

trial.endAt

string<date>

Data de término do período de trial

Example:

"2025-08-15"

splitRules

object[]

Regras de divisão de valores entre recebedores

Show child attributes

splitRules.sellerId

string<uuid>

identificador do recebedor já cadastrado na API de sellers

Example:

"seller-primary-001"

splitRules.percentage

number | null

porcentagem do valor da transação que será enviada ao recebedor

Example:

70

splitRules.amount

number | null

valor que será enviado ao recebedor em centavos

Example:

5000

splitRules.processingFee

boolean

indica se o recebedor vinculado à regra será cobrado pelas taxas da transação

Example:

false

splitRules.chargeEntireFee

boolean

indica se o recebedor será cobrado pela taxa inteira da transação

Example:

false

splitRules.chargeRemainderFee

boolean

indica se o recebedor será cobrado pela taxa restante da transação

Example:

false

splitRules.liable

boolean

indica se o recebedor atrelado assumirá os riscos de chargeback da transação

Example:

true

splitRules.fares

object

Informações sobre as taxas que serão cobradas do recebedor

Show child attributes

splitRules.fares.mdr

number

Percentual MDR (Merchant Discount Rate)

Example:

2.5

splitRules.fares.fee

number

Taxa fixa por transação

Example:

0.3

status

enum<string>

Status da assinatura

Available options:

created,

active,

paused,

canceled,

unpaid,

expired,

trialing

Example:

"created"

amount

integer

Example:

29900

liveMode

boolean

Indica se a assinatura está em modo de produção

Example:

true

lastCycle

object

Último cycle da assinatura. Sempre presente nas respostas individuais (GET, CREATE, UPDATE), pode ser null se não houver cycles.

Show child attributes

lastCycle.id

string<uuid>

Identificador do cycle

Example:

"01985cf8-9877-7c09-bbf6-2cceb3384a61"

lastCycle.customerId

string<uuid>

Identificador do cliente

Example:

"2a8b64ce-904c-4256-b79a-49525808609c"

lastCycle.merchantId

string<uuid>

Identificador do merchant

Example:

"225d39bc-1fbb-480a-90bd-f0caad05d2d0"

lastCycle.cycle

integer

Número do cycle

Example:

1

lastCycle.status

enum<string>

Status do cycle

Available options:

scheduled,

pending,

authorized,

failed,

retrying,

canceled

Example:

"authorized"

lastCycle.createdAt

string<date-time>

Data de criação do cycle

Example:

"2025-07-30T20:14:12.599715Z"

lastCycle.paymentHistory

object[]

Histórico de pagamentos do cycle

Show child attributes

lastCycle.paymentHistory.id

string<uuid>

Identificador do payment history

Example:

"84ec50c5-1fb4-4d6b-bbff-fedc47ba9fa3"

lastCycle.paymentHistory.createdAt

string<date-time>

Data de criação do payment history

Example:

"2025-07-30T20:14:12.608115Z"

lastCycle.paymentHistory.chargeId

string<uuid>

Identificador da cobrança

Example:

"6f2a0713-c4cd-4e2d-8603-69855902676d"

lastCycle.paymentHistory.status

enum<string>

Status da cobrança. pending quando criada, authorized quando bem-sucedida, failed quando falhou

Available options:

pending,

authorized,

failed

Example:

"authorized"

createdAt

string<date-time>

Example:

"2025-07-31T13:36:40.118822Z"

updatedAt

string<date-time>

Example:

"2025-07-31T13:36:40.118822Z"

Recupera sessão com os dados das configurações da empresa Listagem de assinaturas

⌘I

Visão Geral

Client-token

Cards

Tokens

Charges

Sessions

Subscriptions

Customers

Merchants

Providers

Vendors

Sellers

Flows

Webhooks

Reports

Settings

Criação de uma nova assinatura

Authorizations

Body

Response