Comenzando

Comienza a usar Bloque Payments en minutos. Esta guía te llevará a través de la configuración tanto del componente React en el frontend como del SDK en el backend.

Instalación

Frontend (React)

Instala el paquete de componentes React:

npm

yarn

pnpm

bun

deno

npm add @bloque/payments-react

Backend (Node.js/Bun)

Instala el SDK de backend:

npm

yarn

pnpm

bun

deno

npm add @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:

Credencial	Prefijo	Dónde	Propósito
Secret key	`sk_test_` / `sk_live_`	Solo servidor	Se intercambia por un JWT de corta duración vía `/origins/api-keys/exchange`
Publishable key	`pk_test_` / `pk_live_`	Navegador	Identifica al comercio; seguro para exponer en código del cliente
Client secret	JWT	Navegador	JWT con alcance de checkout, devuelto al crear un checkout con secret key

Seguridad del Secret Key

Tu secret key (sk_live_...) nunca debe exponerse en código del lado del cliente. Solo debe usarse en el servidor.

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

Inicio Rápido: Integración Completa

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 {
    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',
    });

    // Devolver checkout id y client secret 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}
      appearance={{
        primaryColor: '#10b981',
        borderRadius: '12px',
      }}
      onSuccess={(data) => {
        console.log('¡Pago exitoso!', data.payment_id);
        window.location.href = '/success';
      }}
      onError={(error) => {
        console.error('Pago fallido:', error);
      }}
    />
  );
}

export default CheckoutPage;

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)

Opción	Tipo	Requerido	Por Defecto	Descripción
`secretKey`	`string`	Sí*	-	Tu secret key de Bloque (`sk_test_...` / `sk_live_...`)
`mode`	`'production' \| 'sandbox'`	Sí	-	Modo de entorno
`webhookSecret`	`string`	No	-	Secreto para verificación de webhooks
`timeout`	`number`	No	-	Timeout de request en milisegundos
`maxRetries`	`number`	No	-	Número máximo de reintentos

* 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

Prop	Tipo	Requerido	Descripción
`checkoutId`	`string`	Sí	ID de sesión de checkout de tu backend
`clientSecret`	`string`	No	JWT con alcance de checkout de la respuesta de crear checkout
`onSuccess`	`function`	No	Llamado en pago exitoso
`onError`	`function`	No	Llamado en error de pago
`onPending`	`function`	No	Llamado cuando el pago está pendiente
`onReady`	`function`	No	Llamado cuando el iframe está listo
`onThreeDSChallenge`	`function`	No	Llamado cuando inicia un challenge 3D Secure
`appearance`	`AppearanceConfig`	No	Personalización de UI
`iframeStyles`	`Record<string, string>`	No	Estilos personalizados del iframe

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:

Número de Tarjeta	Resultado
4111111111111111	Éxito
4000000000000002	Rechazada
4000000000000259	Fondos insuficientes

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

#Comenzando

#Instalación

#Frontend (React)

#Backend (Node.js/Bun)

#Claves API

#Cómo Funciona

#Inicio Rápido: Integración Completa

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

#Configuración Frontend (React)

#Variables de Entorno

#Opciones de Configuración

#Configuración del SDK (Backend)

#Modos

#Props del Componente React

#Configuración de Apariencia

#Soporte TypeScript

#Pruebas en Modo Sandbox

#Números de Tarjeta de Prueba

#Próximos Pasos

#¿Necesitas Ayuda?