🚧 Bloque documentation is under development
close
Bloque Docs
  • English

      • Checkout API

      The Checkout API allows you to create hosted payment pages for your customers.

      Creating a Checkout

      Create a checkout session with items and redirect URLs:

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

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

const checkout = await bloque.checkout.create({
  name: 'React Course',
  description: 'Learn React from scratch',
  image_url: 'https://example.com/course.jpg',
  items: [
    {
      name: 'React Course',
      amount: 2999,
      quantity: 1,
      image_url: 'https://example.com/course.jpg',
    },
  ],
  success_url: 'https://yourapp.com/success',
});

console.log('Checkout URL:', checkout.url);
console.log('Client Secret:', checkout.client_secret);
// Redirect customer to checkout.url or pass id + client_secret to frontend

      Checkout Parameters

      Required Parameters

      {
  name: string;              // Checkout name
  items: CheckoutItem[];     // Items to purchase
  success_url: string;       // Redirect URL after success
}

      Optional Parameters

      {
  description?: string;      // Checkout description
  image_url?: string;        // Checkout image URL
  metadata?: Record<string, string | number | boolean>;
  expires_at?: string;       // Expiration date (ISO 8601)
}

      Checkout Items

      Each item in the checkout:

      {
  name: string;        // Item name
  amount: number;      // Price in smallest currency unit
  quantity: number;    // Quantity
  image_url?: string;  // Item image URL
}

      Complete Example

      const checkout = await bloque.checkout.create({
  name: 'Shopping Cart',
  description: 'Your selected items',
  image_url: 'https://example.com/cart.jpg',
  items: [
    {
      name: 'Wireless Mouse',
      amount: 999,
      quantity: 1,
      image_url: 'https://example.com/mouse.jpg',
    },
    {
      name: 'USB Cable',
      amount: 499,
      quantity: 2,
      image_url: 'https://example.com/cable.jpg',
    },
  ],
  success_url: 'https://yourapp.com/success?session_id={CHECKOUT_SESSION_ID}',
  metadata: {
    user_id: '12345',
    campaign: 'summer_sale',
    discount_applied: true,
  },
  expires_at: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(), // 24 hours
});

// Redirect user
res.redirect(checkout.url);

      Retrieving a Checkout

      Get checkout details:

      const checkout = await bloque.checkout.retrieve('checkout_123');

console.log('Status:', checkout.status);
console.log('Amount:', checkout.amount_total);

      Canceling a Checkout

      Cancel an active checkout:

      const checkout = await bloque.checkout.cancel('checkout_123');

console.log('Status:', checkout.status); // 'canceled'

      Checkout Response

      {
  id: string;                // Checkout ID
  urn: string;               // Checkout URN (e.g. did:bloque:payments:...)
  object: 'checkout';
  url: string;               // Payment URL
  client_secret?: string;    // Checkout-scoped JWT for browser-side auth (when using secretKey)
  status: string;            // Checkout status
  amount_total: number;      // Total amount
  amount_subtotal: number;   // Subtotal
  currency: 'USD';
  items: CheckoutItem[];
  metadata?: Metadata;
  created_at: string;
  updated_at: string;
  expires_at: string;
}
      Client Secret

      When creating a checkout with a secretKey, the response includes a client_secret field. This is a checkout-scoped JWT that should be passed to the frontend along with the checkoutId for browser-side authentication.

      Next Steps