Integre cobrança e acesso sem acoplar seu SaaS ao processador.

A API Monn Flow centraliza catálogo, checkout hospedado, transações, recorrência, entitlement e eventos. Seus sistemas trabalham com uma interface estável enquanto a camada financeira fica isolada atrás do provider.

Base URL
https://SEU-DOMINIO/api/v1

Content-Type: application/json
Authorization: Bearer mnf_test_...

Fluxo recomendado

Crie seu produto e, para recorrência, um plano. Gere um checkout hospedado passando um external_ref do seu usuário ou pedido. Salve os IDs retornados e trate webhooks como fonte de atualização assíncrona. Para segurança operacional, consulte a API quando precisar reconciliar o estado.

Autenticação

Crie chaves no painel em Integração → Chaves de API. O segredo completo aparece apenas no momento da criação. Use chaves separadas por ambiente e conceda o menor escopo necessário.

curl https://SEU-DOMINIO/api/v1/products \
  -H "Authorization: Bearer mnf_test_SEU_TOKEN"

Produtos e planos

POST /api/v1/products
{
  "name": "Monn Pro",
  "price_cents": 3990,
  "kind": "saas",
  "delivery_mode": "api_webhook",
  "external_ref": "monn-pro"
}

POST /api/v1/plans
{
  "product_id": "prod_uuid",
  "name": "Anual",
  "price_cents": 29900,
  "cycle": "YEARLY",
  "trial_days": 0
}

Checkout hospedado

Este é o ponto de integração recomendado para seus SaaS. O cartão é coletado e tokenizado no checkout seguro, sem passar dados brutos de cartão pela API do seu produto.

POST /api/v1/checkouts
{
  "product_id": "prod_uuid",
  "plan_id": "plan_uuid",
  "external_ref": "user_8472:premium_anual",
  "success_url": "https://app.seusite.com/billing/success",
  "metadata": { "workspace_id": "ws_123" }
}

201 Created
{
  "id": "checkout_uuid",
  "checkout_url": "https://SEU-DOMINIO/pay/...",
  "external_ref": "user_8472:premium_anual"
}

Transações e reembolsos

Assinaturas

A criação da assinatura acontece pelo checkout hospedado, onde o cartão é tokenizado. Depois disso, use a API para consultar ou cancelar e trate os eventos de renovação em tempo real.

Entitlements

A Monn Flow mantém o direito efetivo de acesso separado da interface de entrega. Isso funciona para área de membros, SaaS via API/webhook e outras entregas automatizadas. Compra aprovada, renovação, cancelamento, expiração e estorno atualizam a fonte correta sem remover outro acesso ainda válido.

GET /api/v1/entitlements?customer_id=cus_uuid&product_id=prod_uuid

{
  "data": [{
    "product_id": "prod_uuid",
    "active": true,
    "status": "active",
    "effective_source": {
      "type": "subscription",
      "source_id": "sub_uuid"
    }
  }]
}

Webhooks

Cadastre um endpoint HTTPS no painel. Entregamos eventos com ID único, timestamp, tipo e objeto data. Falhas transitórias entram em retentativa. Seu endpoint deve responder rapidamente com 2xx e processar de forma idempotente.

Headers
x-monnflow-event: subscription.payment.approved
x-monnflow-delivery: ...
x-monnflow-timestamp: 1786363200
x-monnflow-signature: sha256=...

Body
{
  "id": "evt_...",
  "event": "subscription.payment.approved",
  "created_at": "2026-08-10T13:00:00.000Z",
  "data": {
    "subscription_id": "...",
    "product_id": "...",
    "external_ref": "user_8472:premium_anual"
  }
}

Para validar, monte a mensagem timestamp + "." + corpo_json_bruto, calcule HMAC SHA 256 com o secret do endpoint e compare em tempo constante com o header recebido.

import crypto from "node:crypto";

const signed = timestamp + "." + rawBody;
const expected = "sha256=" + crypto
  .createHmac("sha256", webhookSecret)
  .update(signed)
  .digest("hex");

const a = Buffer.from(expected);
const b = Buffer.from(signature);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
  throw new Error("invalid signature");
}

Erros, retries e segurança

Respostas de erro usam {"error":{"code":"...","message":"..."}}. Não faça retry cego de erros 4xx. Para 429 e falhas transitórias, use backoff. Nunca exponha chaves secretas no navegador, nunca registre token completo em logs e sempre associe external_ref a um identificador interno não sensível.