Skip to main content

API - Stripe Pagos y Suscripciones

Visión General​

Endpoints para la gestión de pagos y suscripciones utilizando Stripe. Incluye productos de suscripción, creación de payment intents y gestión de webhooks.

GET /stripe/products/​

Obtener productos de suscripción disponibles.

Response Success (200)​

{
  "success": true,
  "data": [
    {
      "id": "prod_basic",
      "name": "Plan Básico",
      "description": "Perfecto para propietarios con pocas propiedades",
      "images": ["https://stripe-images.com/basic.jpg"],
      "metadata": {
        "properties_limit": "5",
        "features": "basic_features"
      },
      "prices": [
        {
          "id": "price_basic_monthly",
          "amount": 29000,
          "currency": "cop",
          "interval": "month",
          "interval_count": 1
        },
        {
          "id": "price_basic_yearly",
          "amount": 290000,
          "currency": "cop",
          "interval": "year",
          "interval_count": 1
        }
      ]
    },
    {
      "id": "prod_pro",
      "name": "Plan Profesional",
      "description": "Para propietarios con múltiples propiedades",
      "prices": [
        {
          "id": "price_pro_monthly",
          "amount": 49000,
          "currency": "cop",
          "interval": "month",
          "interval_count": 1
        }
      ]
    }
  ]
}

POST /stripe/create-payment-intent​

Crear intención de pago para suscripción.

Request​

{
  "amount": 49000,
  "currency": "cop",
  "price_id": "price_pro_monthly",
  "customer_email": "usuario@email.com",
  "metadata": {
    "plan_name": "Plan Profesional",
    "user_id": "124"
  }
}

Response Success (200)​

{
  "success": true,
  "data": {
    "client_secret": "pi_1234567890_secret_xyz",
    "payment_intent_id": "pi_1234567890",
    "publishable_key": "pk_test_...",
    "amount": 49000,
    "currency": "cop"
  }
}

GET /stripe/user-subscriptions​

Obtener suscripciones del usuario autenticado.

Response Success (200)​

{
  "success": true,
  "data": [
    {
      "id": "sub_1234567890",
      "status": "active",
      "current_period_start": "2024-01-15T00:00:00Z",
      "current_period_end": "2024-02-15T00:00:00Z",
      "plan": {
        "id": "price_pro_monthly",
        "name": "Plan Profesional",
        "amount": 49000,
        "currency": "cop",
        "interval": "month"
      },
      "customer": {
        "email": "usuario@email.com"
      },
      "cancel_at_period_end": false,
      "trial_end": null
    }
  ]
}

GET /stripe/user-subscription-status​

Verificar estado de suscripción del usuario.

Response Success (200)​

{
  "success": true,
  "data": {
    "has_active_subscription": true,
    "subscription_status": "active",
    "plan_name": "Plan Profesional",
    "current_period_end": "2024-02-15T00:00:00Z",
    "features": {
      "properties_limit": 20,
      "contracts_enabled": true,
      "chatbot_enabled": true,
      "analytics_enabled": true
    }
  }
}

GET /stripe/user-subscription-simple​

Verificación simple de suscripción activa.

Response Success (200)​

{
  "success": true,
  "data": {
    "is_active": true,
    "plan_name": "Plan Profesional"
  }
}

POST /stripe/webhook​

Webhook para eventos de Stripe.

Request Headers​

Stripe-Signature: t=1234567890,v1=hash_signature

Request Body​

{
  "id": "evt_1234567890",
  "object": "event",
  "type": "customer.subscription.created",
  "data": {
    "object": {
      "id": "sub_1234567890",
      "customer": "cus_1234567890",
      "status": "active"
    }
  }
}

Response Success (200)​

{
  "status": "success"
}

Planes Disponibles​

Plan Básico ($29.000 COP/mes)​

  • Hasta 5 propiedades
  • Gestión básica de inquilinos
  • Reportes simples
  • Soporte por email

Plan Profesional ($49.000 COP/mes)​

  • Hasta 20 propiedades
  • Gestión avanzada
  • Contratos digitales
  • ChatBot incluido
  • Reportes avanzados

Plan Empresarial ($99.000 COP/mes)​

  • Propiedades ilimitadas
  • Múltiples usuarios
  • API personalizada
  • Soporte prioritario
  • Análisis predictivo

Eventos de Webhook​

Eventos Manejados​

  • payment_intent.succeeded: Pago exitoso
  • customer.subscription.created: Nueva suscripción
  • customer.subscription.updated: Actualización de suscripción
  • customer.subscription.deleted: Cancelación de suscripción
  • invoice.payment_succeeded: Pago de factura exitoso
  • invoice.payment_failed: Fallo en pago de factura

Seguridad de Webhooks​

  • Verificación de firma Stripe
  • Validación de timestamp
  • Procesamiento idempotente
  • Logging de todos los eventos

Configuración Frontend​

Stripe Elements​

import { loadStripe } from '@stripe/stripe-js';

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY);

Payment Intent​

const { client_secret } = await fetch('/stripe/create-payment-intent', {
  method: 'POST',
  body: JSON.stringify({ amount: 49000, currency: 'cop' })
}).then(res => res.json());

const { error } = await stripe.confirmCardPayment(client_secret, {
  payment_method: {
    card: elements.getElement(CardElement),
    billing_details: { name: 'Usuario' }
  }
});

Métodos de Pago Soportados​

  • Tarjetas de crédito (Visa, Mastercard, Amex)
  • Tarjetas de débito
  • PSE (Pagos Seguros en Línea)
  • Efecty
  • Baloto