PaymentSummary
The PaymentSummary component displays a detailed overview of an order within the checkout flow. It lists all line items, shows any applicable trial periods or staking requirements, and calculates the total amount due. It is designed to give customers a clear and transparent breakdown of their purchase before they complete the payment.
This component works in conjunction with ProductItem to render individual items and can adapt its display for various scenarios, including cross-sells, upsells, and donations.
Props#
The PaymentSummary component accepts the following props to customize its behavior and the information it displays.
Prop | Type | Description |
|---|---|---|
|
| Required. An array of line item objects to be displayed in the summary. |
|
| Required. The currency object used for formatting amounts. |
|
| The number of days for a trial period. Defaults to |
|
| A Unix timestamp indicating when the trial ends. |
|
| The billing threshold for staking calculations. |
|
| If |
|
| Callback function triggered when a user accepts an upsell offer. |
|
| Callback function triggered when a user reverts an upsell offer. |
|
| Callback function for when the quantity of an item is changed. |
|
| Callback function for when a custom donation amount is changed. |
|
| Callback function to add a cross-sell item to the cart. |
|
| Callback function to remove a cross-sell item from the cart. |
|
| The ID of the current checkout session, used to fetch available cross-sell offers. |
|
| Defines the behavior of the cross-sell offer. Defaults to |
|
| Configuration object for donation items. |
|
| A custom title to display at the top of the summary box (e.g., "Renew Subscription"). Defaults to "Order Summary". |
|
| If |
Usage#
The PaymentSummary component is typically placed within a checkout page to provide a persistent view of the order details. It should be wrapped by a PaymentProvider to access necessary context, such as livemode status.
Basic Order Summary#
Here is a basic example of rendering a payment summary for a list of products. The component will automatically calculate totals and display item details.
import React from 'react';
import { PaymentSummary } from '@blocklet/payment-react';
const items = [
{
price_id: 'price_123',
quantity: 2,
price: {
product: { name: 'Standard Plan', images: ['/logo.png'] },
type: 'recurring',
recurring: { interval: 'month' },
unit_amount: '10.00',
},
},
];
const currency = {
id: 'usd',
symbol: '$',
decimal: 2,
};
function MyCheckoutPage() {
return (
<PaymentSummary
items={items}
currency={currency}
trialInDays={14}
/>
);
}Displaying Staking and Totals#
When showStaking is set to true, the component calculates and displays the required staking amount separately from the payment amount. The final total combines both values.
<PaymentSummary
items={recurringItems} // items with recurring prices
currency={currency}
showStaking={true}
billingThreshold={50} // Optional: Sets a fixed staking amount
/>Handling Cross-Sells#
By providing a checkoutSessionId, the component can fetch and display cross-sell offers. The crossSellBehavior prop determines if the offer is optional or required. User interactions are handled via the onApplyCrossSell and onCancelCrossSell callbacks.
const handleApplyCrossSell = async (crossSellId) => {
console.log('Applying cross-sell:', crossSellId);
// API call to update the checkout session
};
const handleCancelCrossSell = async () => {
console.log('Canceling cross-sell');
// API call to update the checkout session
};
<PaymentSummary
items={items}
currency={currency}
checkoutSessionId="cs_12345"
crossSellBehavior="required"
onApplyCrossSell={handleApplyCrossSell}
onCancelCrossSell={handleCancelCrossSell}
/>Mobile Responsiveness#
On mobile devices, the component automatically renders a collapsible section for the product list to save screen space. The list is initially collapsed if it contains three or more items. This behavior is handled internally using the useMobile hook and requires no extra configuration.