One-Time Payments

PaymentKit offers several flexible ways to handle one-time charges for goods or services. This guide will walk you through the three primary methods available in the Node.js SDK, helping you choose the best approach for your specific needs.

Each method caters to a different use case, from fully-hosted payment pages to deeply integrated custom payment flows.

Checkout Sessions#

A Checkout Session is the easiest way to accept payments. It creates a secure, hosted payment page that takes care of the entire checkout process. You simply create a session, redirect your customer to the provided URL, and PaymentKit handles the rest.

This approach is ideal for standard e-commerce flows, donation buttons, or any scenario where you want a fast, secure, and fully-featured checkout experience without building the UI yourself.

How It Works#

1. Create the Session: Your server uses the SDK to create a session, specifying line items, success and cancellation URLs, and other details.
2. Redirect the Customer: The API returns a session object containing a url. You redirect your customer to this URL.
3. Customer Pays: The customer completes the payment on the hosted page.
4. Redirect Back: PaymentKit redirects the customer back to your success_url or cancel_url.

Example: Creating a Checkout Session#

Here’s how to create a session for a one-time payment.

import payment from '@blocklet/payment-js';

async function createCheckoutSession() {
  try {
    const session = await payment.checkout.sessions.create({
      mode: 'payment', // Specifies a one-time payment
      success_url: 'https://your-site.com/payment-success?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: 'https://your-site.com/payment-cancelled',
      line_items: [
        {
          price_id: 'price_xxxxxxxxxxxxxx', // Replace with your Price ID
          quantity: 1,
        },
      ],
      expires_at: Math.floor(Date.now() / 1000) + (30 * 60), // Session expires in 30 minutes
    });

    console.log('Checkout Session URL:', session.url);
    // Now, redirect your user to session.url
  } catch (error) {
    console.error('Error creating session:', error.message);
  }
}

createCheckoutSession();

After creating the session, the session.url should be used to redirect the customer to the payment page. For a complete list of parameters and options, see the Checkout Sessions API Reference.

Payment Links#

Payment Links provide a way to create a reusable link to a checkout page for a specific product. Once created, you can share this link across multiple channels like email, social media, or embed it in a simple "Buy Now" button on your website. They are perfect for selling a single item or service without requiring a full shopping cart integration.

How It Works#

1. Create the Link: Use the SDK to create a Payment Link, specifying one or more line items.
2. Share the URL: The API returns a permanent url for the link.
3. Customer Pays: Any customer who visits the URL can complete the payment.

Example: Creating a Payment Link#

import payment from '@blocklet/payment-js';

async function createPaymentLink() {
  try {
    const paymentLink = await payment.paymentLinks.create({
      line_items: [
        {
          price_id: 'price_xxxxxxxxxxxxxx', // Replace with your Price ID
          quantity: 1,
        },
      ],
      metadata: {
        campaign: 'summer_sale_2024'
      }
    });

    console.log('Shareable Payment Link:', paymentLink.url);
  } catch (error) {
    console.error('Error creating payment link:', error.message);
  }
}

createPaymentLink();

You can also update a payment link, for example, to archive it when it's no longer needed using payment.paymentLinks.archive(id). For more details, visit the Payment Links API Reference.

Payment Intents#

The Payment Intent object is the backbone of any transaction in PaymentKit. It tracks the lifecycle of a payment from creation to completion, handling various authentication steps and status changes along the way. While Checkout Sessions and Payment Links create and manage Payment Intents for you automatically, you can interact with them directly for more advanced use cases, such as building a custom payment form or handling post-payment actions.

Direct interaction with Payment Intents is typically for managing existing payments, like issuing refunds.

Example: Refunding a Payment#

After a payment is successful (e.g., via a Checkout Session), you can retrieve the associated Payment Intent ID and use it to process a refund.

import payment from '@blocklet/payment-js';

// The Payment Intent ID is typically obtained from a completed Checkout Session
// or through a webhook event.
const paymentIntentId = 'pi_xxxxxxxxxxxxxx'; 

async function refundPayment(pi_id) {
  try {
    const refund = await payment.paymentIntents.refund(pi_id, {
      amount: '10.00', // The amount to refund
      reason: 'requested_by_customer',
      description: 'Customer was not satisfied with the product.',
    });

    console.log('Refund processed successfully:', refund.id);
  } catch (error) {
    console.error(`Error refunding payment ${pi_id}:`, error.message);
  }
}

refundPayment(paymentIntentId);

This gives you granular control over the payment lifecycle after the initial charge has been made. For a full list of management capabilities, see the Payment Intents API Reference.

Now that you understand how to create one-time charges, you may want to learn how to implement Subscriptions for recurring billing or set up Webhooks to receive real-time notifications about payment events.