#Comenzando

Envía tu primer pago end-to-end (servidor + frontend + webhook) en minutos.

#Instalación

#Frontend (React)

Instala el paquete de componentes React:

npm add @bloque/payments-react

yarn add @bloque/payments-react

pnpm add @bloque/payments-react

bun add @bloque/payments-react

deno add npm:@bloque/payments-react

#Backend (Node.js/Bun)

Instala el SDK de backend:

npm add @bloque/payments

yarn add @bloque/payments

pnpm add @bloque/payments

bun add @bloque/payments

deno add npm:@bloque/payments

#Claves API

Para usar Bloque Payments, necesitarás claves API. Puedes obtenerlas desde el Panel de Bloque.

Bloque usa un modelo de tres credenciales:

#Cómo Funciona

1. Tu backend crea una sesión de checkout usando @bloque/payments (secret key)
   ↓
2. Backend recibe checkout_id + client_secret
   ↓
3. Pasa checkout_id y client_secret al componente React
   ↓
4. El componente renderiza iframe con el checkout (publishable key + client secret)
   ↓
5. Usuario completa el pago (con 3D Secure si es requerido)
   ↓
6. Se disparan callbacks onSuccess/onError/onPending
7. Tu webhook recibe payment.status.updated para finalización

#Inicio Rápido: Integración Completa (Checkout Alojado)

Aquí hay un ejemplo completo que muestra cómo integrar Bloque Payments con React en el frontend y Node.js/Bun en el backend.

#Configuración Backend (Node.js/Bun)

Primero, crea un endpoint para generar sesiones de checkout:

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

const app = express();
app.use(express.json());

// Inicializar SDK de Bloque con tu secret key
const bloque = new Bloque({
  secretKey: process.env.BLOQUE_SECRET_KEY!,
  mode: 'production', // o 'sandbox' para pruebas
});

// Endpoint de checkout
app.post('/api/create-checkout', async (req, res) => {
  try {
    // 1) Crear un checkout (link de pago)
    const checkout = await bloque.checkout.create({
      name: 'Mi Producto',
      description: 'Descripción del producto',
      items: [
        {
          name: 'Producto',
          amount: 2999, // Monto en la unidad más pequeña (ej: centavos)
          quantity: 1,
        },
      ],
      success_url: 'https://tuapp.com/success',
    });

    // 2) Devolver checkoutId + clientSecret al frontend
    res.json({
      id: checkout.id,
      url: checkout.url,
      clientSecret: checkout.client_secret,
    });
  } catch (error) {
    console.error('Error de checkout:', error);
    res.status(500).json({
      success: false,
      error: error.message,
    });
  }
});

app.listen(3000, () => {
  console.log('Servidor corriendo en http://localhost:3000');
});

#Configuración Frontend (React)

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

// Inicializar SDK (hacer esto una vez al inicio de la app)
init({
  publishableKey: 'pk_live_...',
  mode: 'production',
});

interface CheckoutPageProps {
  checkoutId: string;
  clientSecret: string;
}

function CheckoutPage({ checkoutId, clientSecret }: CheckoutPageProps) {
  return (
    <BloqueCheckout
      checkoutId={checkoutId}
      clientSecret={clientSecret}
      // Opcional: limitar tabs de pago visibles en el checkout alojado
      paymentMethods={['card', 'pse', 'cash']}
      appearance={{
        primaryColor: '#10b981',
        borderRadius: '12px',
      }}
      onSuccess={(data) => {
        console.log('¡Pago exitoso!', data.payment_id);
        window.location.href = '/success';
      }}
      onPending={(data) => {
        console.log('Pago pendiente:', data.payment_id);
        // Común en PSE: trata como pendiente hasta finalización por webhook
      }}
      onError={(error) => {
        console.error('Pago fallido:', error);
      }}
    />
  );
}

export default CheckoutPage;

#Webhook (Recomendado)

Para estado final confiable (especialmente métodos asíncronos como PSE), configura un webhook y maneja el evento payment.status.updated.

Ver Configuración de Webhooks.

#Variables de Entorno

Crea un archivo .env en tu proyecto backend:

# .env
BLOQUE_SECRET_KEY=sk_live_tu_secret_key_aqui
BLOQUE_WEBHOOK_SECRET=tu_webhook_secret_aqui

Y para tu frontend:

# .env
NEXT_PUBLIC_BLOQUE_PUBLISHABLE_KEY=pk_live_tu_publishable_key_aqui

Cárgalas en tu aplicación:

import 'dotenv/config';

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

#Opciones de Configuración

#Configuración del SDK (Backend)

* Se requiere secretKey (recomendado) o el legacy accessToken.

#Modos

• sandbox: Para pruebas y desarrollo. Sin transacciones reales. Usa claves sk_test_ / pk_test_.
• production: Para operaciones en vivo con pagos reales. Usa claves sk_live_ / pk_live_.

#Props del Componente React

#Cuándo usar Pagos Directos

Checkout Alojado es la integración recomendada. Usa Pagos Directos (solo servidor) cuando necesites enviar card/PSE/cash desde tu backend.

Ver Pagos Directos.

#Configuración de Apariencia

Personaliza el look and feel:

const appearance = {
  primaryColor: '#10b981',     // Color de marca
  borderRadius: '12px',        // Radio de borde para inputs
  fontFamily: 'Inter, system-ui, sans-serif', // Familia de fuente
};

#Soporte TypeScript

El SDK está completamente tipado con TypeScript. Importa tipos para mejor experiencia de desarrollo:

import { BloqueCheckout, init } from '@bloque/payments-react';
import type {
  BloqueCheckoutProps,
  AppearanceConfig,
  PaymentResult,
} from '@bloque/payments-react';

const handleSuccess = (result: PaymentResult) => {
  console.log('ID de Pago:', result.payment_id);
  console.log('Estado:', result.status);
};

#Pruebas en Modo Sandbox

Usa modo sandbox para pruebas sin transacciones reales:

// Backend
const bloque = new Bloque({
  secretKey: process.env.BLOQUE_SECRET_KEY!, // sk_test_...
  mode: 'sandbox',
});

// Frontend
init({
  publishableKey: 'pk_test_...',
  mode: 'sandbox',
});

#Números de Tarjeta de Prueba

Usa estos números de tarjeta de prueba en modo sandbox:

#Próximos Pasos

Ahora que tienes la integración básica funcionando, explora más características:

• Integración React - Guía detallada de configuración React
• API de Checkout - Crea páginas de checkout alojadas
• Métodos de Pago - Aprende sobre los métodos de pago disponibles
• 3D Secure - Agrega autenticación 3D Secure a pagos con tarjeta
• Webhooks - Configura webhooks para notificaciones de pago
• Manejo de Errores - Maneja errores con gracia

#¿Necesitas Ayuda?

• GitHub Issues
• Contactar Soporte