Skip to main content
POST
/
v1
/
subscriptions
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",
  "referenceKey": "SUB-PREMIUM-001",
  "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,
        "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
  },
  "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",
      "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,
        "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,
  "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
​
recurrence
object
required
​
paymentMethod
object
required
​
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)

​
splitRules
object[]

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

Response

201 - application/json

Created

​
id
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[]
​
recurrence
object
​
paymentMethod
object
​
trial
object

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

​
splitRules
object[]

Regras de divisão de valores entre recebedores

​
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

​
createdAt
string<date-time>
Example:

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

​
updatedAt
string<date-time>
Example:

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

⌘I