#Introducción

Bienvenido a la documentación de Bloque Payments. Bloque proporciona una infraestructura de pagos integral que permite a los desarrolladores aceptar pagos con tarjetas de crédito y débito.

#¿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. Proporciona un SDK de backend para el procesamiento seguro de pagos y componentes React para experiencias de checkout fluidas usando una página de checkout alojada.

#Características Principales

#Checkout Alojado

Bloque utiliza un enfoque de checkout alojado seguro donde los pagos se procesan a través de un iframe. Esto garantiza el cumplimiento de PCI sin manejar datos sensibles de tarjetas en tus servidores.

1. Tu backend crea una sesión de checkout
   ↓
2. Backend recibe checkout_id
   ↓
3. Pasa checkout_id al componente React
   ↓
4. El componente renderiza iframe con el checkout
   ↓
5. Usuario completa el pago
   ↓
6. Se disparan los callbacks

#Integración con React

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

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

init({
  publicApiKey: 'pk_live_...',
  mode: 'production',
});

<BloqueCheckout
  checkoutId={checkoutId}
  onSuccess={(data) => {
    console.log('¡Pago exitoso!', data.payment_id);
  }}
  onError={(error) => {
    console.error('Pago fallido:', error);
  }}
/>

#Seguro por Defecto

Infraestructura compatible con PCI con:

• Iframe de checkout alojado (datos de tarjeta nunca tocan tus servidores)
• Gestión segura de claves API
• Verificación de firma de webhooks
• Cifrado de extremo a extremo

#UI Personalizable

Personaliza la apariencia del checkout 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
• Soporte IntelliSense en editores modernos
• Verificación de tipos en tiempo de compilación

#Arquitectura

Bloque Payments sigue un patrón de arquitectura seguro:

┌─────────────────┐      ┌─────────────────┐      ┌──────────────┐
│ Tu Backend      │─────▶│  API Bloque     │─────▶│ Checkout ID  │
│ (@bloque/pay)   │      │                 │      │              │
└─────────────────┘      └─────────────────┘      └──────────────┘
                                                         │
                                                         ▼
                         ┌─────────────────────────────────────────┐
                         │  Componente React + Checkout Alojado    │
                         │  (@bloque/payments-react)               │
                         └─────────────────────────────────────────┘

1. Tu Backend crea sesiones de checkout usando el SDK de Bloque
2. API de Bloque devuelve un checkout ID
3. Frontend renderiza el checkout alojado en un iframe
4. Usuario completa el pago de forma segura

#Paquetes

El ecosistema de Bloque Payments consiste en dos paquetes principales:

@bloque/payments          # SDK de backend para Node.js/Bun
@bloque/payments-react    # Componentes React con checkout alojado

#SDK de Backend (@bloque/payments)

SDK del lado del servidor para crear checkouts:

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

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

const checkout = await bloque.checkout.create({
  name: 'Mi Producto',
  items: [{ name: 'Producto', amount: 2999, quantity: 1 }],
  success_url: 'https://tuapp.com/success',
});

console.log('Checkout ID:', checkout.id);

#Componentes React (@bloque/payments-react)

Componente de checkout alojado para React:

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

init({
  publicApiKey: 'pk_live_...',
  mode: 'production',
});

<BloqueCheckout
  checkoutId={checkoutId}
  onSuccess={handleSuccess}
/>

#¿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 React y Next.js
• Soporta Node.js y Bun
• Dependencias mínimas

#Próximos Pasos

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

• Inicio Rápido - Ponte en marcha rápidamente
• Integración React - Usa el componente BloqueCheckout
• API de Checkout - Crea páginas de checkout alojadas
• Webhooks - Maneja eventos de pago