#Introducción

Acepta pagos con un SDK moderno, TypeScript-first — sin manejar datos sensibles de tarjeta por tu cuenta.

Bloque Payments te da:

• Un SDK de servidor para crear links de pago (carrito o suscripción)
• Un checkout alojado (iframe) para embeber en tu app (React soportado)
• Pagos directos (solo servidor) para card, PSE y cash cuando lo necesites
• Webhooks para finalización y conciliación

#Elige tu camino de integración

La mayoría de equipos deberían comenzar con Checkout Alojado. Es el camino más rápido y reduce el alcance PCI.

#Checkout Alojado (recomendado)

1) Servidor: crear checkout con secretKey
2) Servidor → Cliente: enviar checkoutId + clientSecret
3) Cliente: renderizar <BloqueCheckout> con publishableKey + clientSecret
4) Usuario paga (3DS se maneja automáticamente si aplica)
5) Tu endpoint recibe payment.status.updated para finalización

#Pagos Directos (solo servidor)

Usa pagos directos si necesitas un flujo totalmente controlado por backend (por ejemplo: kiosko, call center, o UI propia).

• card: devuelve estado approved/pending/rejected (y opcionalmente un challenge 3DS)
• pse: devuelve checkout_url para redirección
• cash: devuelve payment_code (10 dígitos)

#Paquetes

@bloque/payments        SDK de servidor (Node.js/Bun)
@bloque/payments-core   Embed en JS + tipos (browser)
@bloque/payments-react  Wrapper React para checkout alojado

#Vista rápida (end-to-end)

#Servidor (crear checkout)

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

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

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

console.log(checkout.id, checkout.client_secret);

#Cliente (renderizar checkout alojado)

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

export function CheckoutPage({ checkoutId, clientSecret }: { checkoutId: string; clientSecret?: string }) {
  return (
    <BloqueCheckout
      checkoutId={checkoutId}
      clientSecret={clientSecret}
      publishableKey="pk_live_..."
      onSuccess={(data) => console.log('Approved', data.payment_id)}
      onPending={(data) => console.log('Pending', data.payment_id)}
      onError={(err) => console.error(err)}
    />
  );
}

#Próximos pasos

• Comenzando — tu primer pago en minutos
• Checkout API — carrito vs suscripciones
• Métodos de pago — card, PSE y cash
• Webhooks — maneja payment.status.updated