#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 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

#Clave API

Para usar Bloque Payments, necesitarás una clave API. Puedes obtener una desde el Panel de Bloque.

:::tip Claves API Bloque proporciona dos tipos de claves API:

• Public API Key: Puede usarse de forma segura en el cliente (frontend) para inicializar el SDK.
• Secret API Key: Solo debe usarse en el backend. Nunca la expongas en código del lado del cliente. :::

#Cómo Funciona

1. Tu backend crea una sesión de checkout usando @bloque/payments
   ↓
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 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
const bloque = new Bloque({
  accessToken: process.env.BLOQUE_ACCESS_TOKEN!,
  mode: 'production', // o 'sandbox' para pruebas
});

// Endpoint de checkout
app.post('/api/create-checkout', async (req, res) => {
  try {
    // Configura los datos del checkout en el backend
    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',
    });

    res.json({ id: checkout.id, url: checkout.url });
  } 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({
  publicApiKey: 'pk_live_...',
  mode: 'production',
});

interface CheckoutPageProps {
  // El checkoutId se genera en el backend usando @bloque/payments
  checkoutId: string;
}

function CheckoutPage({ checkoutId }: CheckoutPageProps) {
  return (
    <BloqueCheckout
      checkoutId={checkoutId}
      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_ACCESS_TOKEN=tu_access_token_aqui

Cárgalas en tu aplicación:

import 'dotenv/config';

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

#Opciones de Configuración

#Configuración del SDK (Backend)

#Modos

• sandbox: Para pruebas y desarrollo. Sin transacciones reales.
• production: Para operaciones en vivo con pagos reales.

#Props del Componente React

#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({
  accessToken: process.env.BLOQUE_ACCESS_TOKEN!,
  mode: 'sandbox', // Modo de prueba
});

// Frontend
init({
  publicApiKey: '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
• Webhooks - Configura webhooks para notificaciones de pago
• Manejo de Errores - Maneja errores con gracia

#¿Necesitas Ayuda?

• GitHub Issues
• Contactar Soporte