@blocklet/payment-react

# OverdueInvoicePayment The `OverdueInvoicePayment` component is a specialized tool designed to handle the payment of overdue invoices for a specific customer or subscription. It simplifies the process by automatically fetching overdue invoices and presenting users with a clear interface to settle their outstanding payments. This component can operate in two modes: a default mode that displays a pre-built dialog for quick integration, and a custom mode that provides the flexibility to build a unique user interface using a render prop. It must be wrapped within a `PaymentProvider` to function correctly. ## Props The `OverdueInvoicePayment` component accepts the following props to customize its behavior: <x-field-group> <x-field data-name="subscriptionId" data-type="string" data-required="false"> <x-field-desc markdown>The ID of the subscription to check for overdue invoices. Either `subscriptionId` or `customerId` must be provided.</x-field-desc> </x-field> <x-field data-name="customerId" data-type="string" data-required="false"> <x-field-desc markdown>The ID or DID of the customer. Use this to handle all overdue invoices for a specific customer.</x-field-desc> </x-field> <x-field data-name="mode" data-type="'default' | 'custom'" data-default="default" data-required="false"> <x-field-desc markdown>The rendering mode. `'default'` shows a pre-built dialog. `'custom'` uses the `children` render prop for a custom UI.</x-field-desc> </x-field> <x-field data-name="onPaid" data-type="function" data-required="false"> <x-field-desc markdown>An optional callback function that is triggered after payment for a specific currency is successfully completed. It receives `(id, currencyId, type)`, where `id` is the `subscriptionId` or `customerId`, and `type` is `'subscription'` or `'customer'`.</x-field-desc> <x-field data-name="parameters" data-type="object"> <x-field data-name="id" data-type="string" data-desc="The subscriptionId or customerId."></x-field> <x-field data-name="currencyId" data-type="string" data-desc="The ID of the currency used for payment."></x-field> <x-field data-name="type" data-type="'subscription' | 'customer'" data-desc="Indicates if the payment was for a subscription or a customer."></x-field> </x-field> </x-field> <x-field data-name="dialogProps" data-type="object" data-required="false"> <x-field-desc markdown>Optional props to pass to the underlying Material-UI `Dialog` component in `default` mode. For example, `{ open: true, title: 'Custom Title', onClose: handleClose }`.</x-field-desc> </x-field> <x-field data-name="detailLinkOptions" data-type="object" data-required="false"> <x-field-desc markdown>Optional settings for the "View Details" link. Can be used to disable the link, change its text, or provide a custom `onClick` handler.</x-field-desc> <x-field data-name="enabled" data-type="boolean" data-required="false" data-desc="Whether the link is enabled."></x-field> <x-field data-name="onClick" data-type="(e: React.MouseEvent) => void" data-required="false" data-desc="Custom click handler."></x-field> <x-field data-name="title" data-type="string" data-required="false" data-desc="Custom link text."></x-field> </x-field> <x-field data-name="successToast" data-type="boolean" data-default="true" data-required="false"> <x-field-desc markdown>If `true`, a success toast notification is shown upon successful payment.</x-field-desc> </x-field> <x-field data-name="alertMessage" data-type="string" data-required="false"> <x-field-desc markdown>An optional message to append to the default title text when in customer mode.</x-field-desc> </x-field> <x-field data-name="children" data-type="function" data-required="false"> <x-field-desc markdown>A render prop function used only when `mode` is `'custom'`. It receives a `handlePay` function and a `data` object.</x-field-desc> <x-field data-name="parameters" data-type="object"> <x-field data-name="handlePay" data-type="(item: SummaryItem) => void" data-desc="Function to initiate the payment process for a specific currency group."></x-field> <x-field data-name="data" data-type="object" data-desc="An object containing the fetched payment information."></x-field> </x-field> </x-field> <x-field data-name="authToken" data-type="string" data-required="false"> <x-field-desc markdown>An optional authentication token for API requests, useful for server-to-server or cross-origin scenarios.</x-field-desc> </x-field> </x-field-group> ### `children` Render Prop Data When using `mode="custom"`, the `data` object passed to the `children` function contains the following fields: <x-field-group> <x-field data-name="subscription" data-type="Subscription" data-required="false"> <x-field-desc markdown>The subscription details, if `subscriptionId` was provided.</x-field-desc> </x-field> <x-field data-name="summary" data-type="{ [key: string]: SummaryItem }" data-required="true"> <x-field-desc markdown>An object where each key is a currency ID. The value contains the total amount, currency details, and payment method for that currency.</x-field-desc> </x-field> <x-field data-name="invoices" data-type="Invoice[]" data-required="true"> <x-field-desc markdown>An array of all overdue invoice objects.</x-field-desc> </x-field> <x-field data-name="subscriptionCount" data-type="number" data-required="false"> <x-field-desc markdown>The number of subscriptions with overdue invoices (for customer mode).</x-field-desc> </x-field> <x-field data-name="detailUrl" data-type="string" data-required="true"> <x-field-desc markdown>The URL to view detailed invoice information.</x-field-desc> </x-field> </x-field-group> ## Usage Examples All examples assume you have `PaymentProvider` set up in your application as detailed in the [PaymentProvider documentation](./providers-payment-provider.md). ### 1. Default Mode for a Subscription This is the simplest way to handle overdue payments for a specific subscription. The component will automatically render a dialog if any overdue invoices are found. ```javascript SubscriptionOverdue.jsx icon=logos:react import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react'; import { useSessionContext } from '../hooks/session'; // Your custom session hook function SubscriptionPage({ subscriptionId }) { const { session, connect } = useSessionContext(); const handlePaymentSuccess = (id, currencyId, type) => { console.log(`Payment successful for ${type} ${id} with currency ${currencyId}`); // You can refetch subscription data here to update its status }; return ( <PaymentProvider session={session} connect={connect}> {/* This component will be null if there are no overdue invoices */} <OverdueInvoicePayment subscriptionId={subscriptionId} onPaid={handlePaymentSuccess} /> {/* Other subscription details can be rendered here */} </PaymentProvider> ); } ``` ### 2. Default Mode for a Customer Use this to create a centralized place for a customer to pay all their overdue invoices across multiple subscriptions. ```javascript CustomerDashboard.jsx icon=logos:react import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react'; import { useSessionContext } from '../hooks/session'; // Your custom session hook function CustomerDashboard() { const { session, connect } = useSessionContext(); return ( <PaymentProvider session={session} connect={connect}> <h2>Payment Center</h2> <p>Please settle any outstanding payments to ensure uninterrupted service.</p> <OverdueInvoicePayment customerId={session.user.did} onPaid={() => { console.log('All customer overdue invoices paid for a currency!'); // Refresh customer account status }} /> {/* The rest of the customer dashboard */} </PaymentProvider> ); } ``` ### 3. Custom UI Mode For full control over the user experience, use `mode="custom"`. This allows you to integrate the payment functionality directly into your existing UI instead of using a dialog. ```javascript CustomOverdueUI.jsx icon=logos:react import { OverdueInvoicePayment, PaymentProvider } from '@blocklet/payment-react'; import { useSessionContext } from '../hooks/session'; // Your custom session hook import { Card, CardContent, Typography, Button, Stack } from '@mui/material'; function CustomOverdueUI({ subscriptionId }) { const { session, connect } = useSessionContext(); // A simple Amount component for formatting const Amount = ({ amount, decimal, symbol }) => { const formattedAmount = (parseInt(amount, 10) / 10 ** (decimal || 0)).toFixed(2); return ( <strong> {formattedAmount} {symbol} </strong> ); }; return ( <PaymentProvider session={session} connect={connect}> <OverdueInvoicePayment subscriptionId={subscriptionId} mode="custom" onPaid={() => console.log('Custom UI payment successful!')}> {(handlePay, { summary, invoices }) => { const summaryList = Object.values(summary); if (invoices.length === 0) { return <Typography>No overdue payments. All clear!</Typography>; } return ( <Card variant="outlined"> <CardContent> <Typography variant="h6" color="error" gutterBottom> You have {invoices.length} overdue invoice(s). </Typography> <Stack spacing={2} mt={2}> {summaryList.map(item => ( <Stack key={item.currency.id} direction="row" justifyContent="space-between" alignItems="center"> <Typography> Total Due:{' '} <Amount amount={item.amount} decimal={item.currency.decimal} symbol={item.currency.symbol} /> </Typography> <Button variant="contained" color="primary" onClick={() => handlePay(item)}> Pay with {item.currency.symbol} </Button> </Stack> ))} </Stack> </CardContent> </Card> ); }} </OverdueInvoicePayment> </PaymentProvider> ); } ```  ![OverdueInvoicePayment](assets/diagram/components-business-overdue-invoice-payment-01.jpg)