One-Time Payments
PaymentKit provides several flexible methods for accepting one-time payments. The right choice depends on your specific needs, from fully hosted checkout pages to reusable payment links. This guide covers the three primary approaches: Checkout Sessions, Payment Links, and Payment Intents.
Choosing the right method is key to providing a smooth user experience. The following diagram can help you decide which approach best fits your use case.
Using Checkout Sessions#
Checkout Sessions are the easiest way to accept payments. They provide a secure, hosted payment page that handles the entire checkout process. This approach is recommended for most integrations as it minimizes your implementation effort and helps with compliance.
When you create a Checkout Session, PaymentKit generates a unique URL. You simply redirect your customer to this URL to complete the payment.
Example: Create a Checkout Session
import payment from '@blocklet/payment-js';
async function createCheckoutSession() {
try {
const session = await payment.checkout.sessions.create({
success_url: 'https://example.com/success',
cancel_url: 'https://example.com/cancel',
mode: 'payment', // Specifies a one-time payment
line_items: [
{ price_id: 'price_xxx', quantity: 1 }
],
});
console.log('Redirect your customer to:', session.url);
// In a web application, you would typically do:
// window.location.href = session.url;
} catch (error) {
console.error('Error creating session:', error.message);
}
}
createCheckoutSession();After creating the session, redirect your customer to the url provided in the response. PaymentKit handles the payment form, confirmation, and security. For more advanced configurations, see the Checkout Sessions API Reference.
Using Payment Links#
Payment Links are ideal for selling a single product or service with a fixed price. You can create a link once and share it multiple times across different channels, like email, social media, or as a simple button on your website. Each link leads to a pre-configured, hosted checkout page.
Example: Create a Payment Link
import payment from '@blocklet/payment-js';
async function createPaymentLink() {
try {
const paymentLink = await payment.paymentLinks.create({
line_items: [
{
price_id: 'price_xxx', // ID of the price for your product
quantity: 1,
}
],
});
console.log('Share this URL with your customers:', paymentLink.url);
} catch (error) {
console.error('Error creating payment link:', error.message);
}
}
createPaymentLink();This creates a permanent URL that directs customers to a checkout page for the specified item. Explore all available options in the Payment Links API Reference.
Managing Payments with Payment Intents#
While Checkout Sessions and Payment Links are used to initiate payments, the PaymentIntent object tracks the entire lifecycle of a payment from creation to completion. You do not typically create Payment Intents directly with the SDK for one-time payments; they are created automatically when a customer starts a checkout flow via a Session or Payment Link.
However, you can use the Payment Intent API to check the status of a payment or to perform subsequent actions like refunds.
Example: Refund a Payment
import payment from '@blocklet/payment-js';
async function refundPayment(paymentIntentId) {
try {
const refund = await payment.paymentIntents.refund(paymentIntentId, {
amount: '0.001',
reason: 'requested_by_customer',
description: 'Customer requested a refund for order #123.'
});
console.log('Refund successful:', refund.id);
} catch (error) {
console.error('Error processing refund:', error.message);
}
}
// Use the ID of a Payment Intent created by a previous transaction
refundPayment('pi_xxx');This example shows how to refund a charge by referencing its associated Payment Intent ID. For a complete list of management actions, refer to the Payment Intents API Reference.
Next Steps#
Now that you understand how to handle one-time payments, you can explore more advanced topics.
With these tools, you can build a robust payment system tailored to your needs.