Bloque Docs
  • Español

      • Introducción

      Bienvenido a la documentación de Bloque Payments. Bloque proporciona una infraestructura de pagos integral que permite a los desarrolladores aceptar pagos a través de múltiples métodos, incluyendo tarjetas, PSE (banca en línea colombiana) y pagos en efectivo.

      ¿Qué es Bloque Payments?

      Bloque Payments es una plataforma de procesamiento de pagos con TypeScript como lenguaje principal, que simplifica la integración de pagos en tus aplicaciones web y móviles. Proporciona tanto SDKs de backend para el procesamiento seguro de pagos como componentes de frontend para experiencias de usuario fluidas.

      Características Principales

      💳 Múltiples Métodos de Pago

      Acepta pagos a través de varios canales:

      • Pagos con Tarjeta: Tarjetas de crédito y débito
      • PSE: Sistema de banca en línea colombiana
      • Pagos en Efectivo: Genera recibos para puntos de pago físicos

      ⚛️ Integración con React

      Componentes React pre-construidos para integración rápida:

      import { BloqueCheckout } from '@bloque/payments-react';

<BloqueCheckout
  config={config}
  appearance={appearance}
  onSuccess={(response) => {
    console.log('¡Pago exitoso!', response.id);
  }}
  onError={(error) => {
    console.error('Pago fallido:', error.message);
  }}
/>

      🔒 Seguro por Defecto

      Infraestructura compatible con PCI con:

      • Cifrado de extremo a extremo
      • Gestión segura de claves API
      • Verificación de firma de webhooks
      • Sin datos sensibles almacenados en tus servidores

      🎨 UI Personalizable

      Personaliza la experiencia de pago para que coincida con tu marca:

      const appearance = {
  primaryColor: '#10b981',
  borderRadius: '12px',
  fontFamily: 'Inter, system-ui, sans-serif',
};

      📱 Type-Safe

      Construido con TypeScript desde cero:

      • Definiciones de tipos completas incluidas
      • Tipos de unión discriminada para métodos de pago
      • Soporte IntelliSense en editores modernos
      • Verificación de tipos en tiempo de compilación

      Arquitectura

      Bloque Payments sigue un patrón de arquitectura seguro donde los datos sensibles de pago nunca tocan tu backend:

      ┌─────────────────┐      ┌─────────────────┐      ┌──────────────┐
│ Componente React│─────▶│   Tu Backend    │─────▶│  API Bloque  │
│   (Frontend)    │      │  (Uso del SDK)  │      │              │
└─────────────────┘      └─────────────────┘      └──────────────┘
      1. Frontend captura datos de pago de forma segura
      2. Tu Backend procesa pagos usando el SDK de Bloque
      3. API de Bloque gestiona el procesamiento y verificación de pagos

      Casos de Uso

      Plataformas de E-commerce

      Construye tiendas en línea con experiencias de checkout fluidas y soporte para múltiples métodos de pago.

      Aplicaciones SaaS

      Acepta pagos de suscripciones y compras únicas directamente en tu aplicación.

      Plataformas Marketplace

      Permite que vendedores y compradores transaccionen de forma segura con procesamiento de pagos instantáneo y liquidación automatizada.

      Aplicaciones Móviles

      Integra pagos en aplicaciones React Native usando los mismos componentes y API.

      Paquetes

      El ecosistema de Bloque Payments consiste en tres paquetes principales:

      @bloque/payments          # SDK de backend para Node.js/Bun
@bloque/payments-react    # Componentes React
@bloque/payments-elements # Web Components (independiente)

      SDK de Backend (@bloque/payments)

      SDK del lado del servidor para crear checkouts y procesar pagos:

      import { Bloque } from '@bloque/payments';

const bloque = new Bloque({
  apiKey: process.env.BLOQUE_API_KEY!,
  mode: 'production',
});

const payment = await bloque.payments.create({
  payment: payload,
});

      Componentes React (@bloque/payments-react)

      Componentes React pre-construidos para formularios de pago:

      import { BloqueCheckout } from '@bloque/payments-react';

<BloqueCheckout
  config={config}
  onSubmit={handleSubmit}
  onSuccess={handleSuccess}
/>

      Web Components (@bloque/payments-elements)

      Web components independientes del framework para JavaScript vanilla, Vue, Svelte y más.

      ¿Por qué Bloque Payments?

      Experiencia del Desarrollador

      • Documentación clara y completa
      • Ejemplos prácticos para casos de uso comunes
      • Diseño de API intuitivo
      • Enfoque TypeScript-first

      Listo para Producción

      • Probado en batalla en producción
      • Manejo integral de errores
      • Soporte detallado de logging y depuración
      • Soporte de webhooks para actualizaciones en tiempo real

      Integración Flexible

      • Funciona con cualquier framework de JavaScript
      • Soporta Node.js, Bun y Deno
      • Compatible con navegadores y React Native
      • Dependencias mínimas

      Enfoque en el Mercado Colombiano

      Soporte nativo para métodos de pago colombianos:

      • Integración PSE para banca en línea
      • Integración con red de pagos en efectivo
      • Soporte para pesos colombianos (COP)
      • Requisitos de cumplimiento locales

      Próximos Pasos

      ¿Listo para integrar pagos? Sigue nuestra Guía de Inicio Rápido para aceptar tu primer pago en minutos.