#Introduction

Accept payments with a modern, TypeScript-first SDK — without handling sensitive card data yourself.

Bloque Payments gives you:

• A server SDK to create payment links (shopping carts or subscriptions)
• A hosted checkout (iframe) you embed in your app (React supported)
• Direct payments (server-side only) for card, PSE, and cash when you need it
• Webhooks for payment finality and reconciliation

#Choose your integration path

Most teams should start with Hosted Checkout. It’s the fastest to ship and keeps PCI scope low.

#Hosted Checkout (recommended)

1) Server: create checkout with secretKey
2) Server → Client: send checkoutId + clientSecret
3) Client: render <BloqueCheckout> with publishableKey + clientSecret
4) User pays (3DS handled automatically when needed)
5) Your webhook endpoint receives payment.status.updated for finality

#Direct Payments (server-side only)

Use direct payments if you need a fully server-driven flow (e.g. kiosk, call center, or an existing backend checkout UI).

• card: returns an approval/pending/rejection status (optionally 3DS challenge data)
• pse: returns checkout_url for redirect
• cash: returns a payment_code (10-digit)

#Packages

@bloque/payments        Server SDK (Node.js/Bun)
@bloque/payments-core   Vanilla JS embed + types (browser)
@bloque/payments-react  React wrapper for hosted checkout

#Quick preview (end-to-end)

#Server (create a 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: 'My first checkout',
  items: [{ name: 'Starter plan', amount: 2999, quantity: 1 }],
  success_url: 'https://yourapp.com/success',
});

// Send these to the client
console.log(checkout.id, checkout.client_secret);

#Client (render hosted checkout)

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)}
    />
  );
}

#Next steps

• Getting started — ship your first payment in minutes
• Checkout API — shopping cart vs subscription checkouts
• Payment methods — card, PSE, and cash
• Webhooks — handle payment.status.updated reliably