Quickstart · Compra de créditos (Açaí topup con Mercado Pago)

Precaución

En construcción — Wave A. La integración pública con Mercado Pago para comprar créditos Açaí desde la app del tenant todavía no está GA. Este documento describe el flow planeado para que adaptés tu integración con anticipación.

Estado actual

Componente	Estado	Notas
Modelo Açaí token + ledger	Live	Tablas user_acai_balance + user_acai_ledger (bmonkey global)
Débitos automáticos por operación	Live	KYC, screening, signature, MAU, MFA — todos cobran al tenant
Sandbox con 1000 Açaí simulados	Live	Cualquier tenant dj_test_* arranca con 1000, no se cobra
Compra de créditos desde admin console	Live	platform/frontend/admin-console — operación interna bjungle
Endpoint público de topup	Wave A	TBD — probablemente POST /v1/billing/topup en platform-api
Webhook mp.payment.approved	Wave A	Mercado Pago → platform-worker → ledger credit
Suscripciones recurrentes	Wave A+	Mercado Pago Subscriptions (préapagado mensual)
Conversión COP → Açaí	Wave A	Spot rate vs TRM (decisión pendiente — TRM del día anterior probablemente)

Flow planeado

1. Tenant golpea POST /v1/billing/topup con {amount_cop, return_url}
2. platform-api crea preference en Mercado Pago, devuelve init_point
3. Tenant redirige al user al init_point
4. User paga con Visa/Mastercard/PSE/Nequi
5. MP envía webhook a platform-worker
6. platform-worker verifica firma + acredita Açaí en user_acai_balance
7. Emite evento acai.balance.credited (tenant lo recibe en su webhook endpoint)
8. User vuelve al return_url con ?status=approved

Mientras tanto

• Sandbox funciona sin topup — balance simulado de 1000 Açaí.
• Producción — contactá a bjungle (comercial@bjungle.com) o usá el panel admin para hacer un topup manual mientras tanto.
• Los precios de los bundles están en /precios — desde sandbox (0 USD / 1000 Açaí simulados) hasta scale (1299 USD / 250 000 Açaí).

API surface (preview, sujeto a cambios)

POST /v1/billing/topup
Content-Type: application/json
X-API-Key: dj_live_...

{
  "amount_cop":  100000,
  "bundle":      "starter",     // opcional — usa tabla de bundles del plan
  "return_url":  "https://tu-fintech.co/billing/return",
  "metadata":    { "order_id": "..." }
}

SDK · uso planeado

Cuando el endpoint quede GA, el SDK lo expondrá como dj.platform.billing.topup({...}). Mientras tanto, los handlers de webhook de Mercado Pago vivirán bajo dj.platform.webhooks — ya disponibles para listar/replay las entregas (subject.verified, bseal.signature.completed, etc.) que tu integración produce hoy:

import { BjungleClient } from '@bjungle/sdk';

const dj = new BjungleClient({
  apiKey:  process.env.DJ_API_KEY!,
  baseUrl: 'https://api.qa.bjungle.net',
});

// Hoy disponible: revisar entregas fallidas y reintentar
const failed = await dj.platform.webhooks.listDeliveries({ status: 'failed', limit: 50 });
for (const d of failed.items) {
  await dj.platform.webhooks.replayDelivery(d.id);
}

Nota

Preview del paquete. @bjungle/sdk@0.1.0 está completo en superficie y tests; la publicación a npm pública sigue pendiente (TODO Wave E). El método platform.billing.topup se agregará al SDK en la misma Wave A que el endpoint público.

Respuesta 201:

{
  "preference_id":  "<mp_preference_id>",
  "init_point":     "https://www.mercadopago.com.co/checkout/v1/...",
  "expires_at":     "2026-06-05T15:00:00Z"
}

Evento acai.balance.credited (planeado):

{
  "event_type": "acai.balance.credited",
  "payload": {
    "amount_acai": 8000,
    "amount_cop":  400000,
    "trm_used":    4000,
    "mp_payment_id":"...",
    "balance_after": 12000
  }
}

Siguientes pasos

Precios y bundles

Lista actual de planes Açaí y conversión COP → token.

Ver precios →

Concepto · Suscripción y pagos

Modelo Açaí + revenue share + diseño del ledger.

Concepto →