feat: add option to pass a reference, tidy up callbacks

app/components/homepage.tsx

@@ -55,6 +55,7 @@ export function BasicPayment() {
       amountInUsd="25.00"
       recipientWallet="0x742d35Cc6639C0532c29e54F3D4B48E4d7d5f1E0"
       paymentConfig={{
+        reference: "your_payment_reference",
         rnApiClientId: <YOUR_CLIENT_ID>,
         supportedCurrencies: ["ETH-sepolia-sepolia", "FAU-sepolia", "USDC-mainnet"],
       }}
@@ -80,10 +81,10 @@ export function BasicPayment() {
           totalTax: "0.00",
         },
       }}
-      onSuccess={(requestId) => {
+      onPaymentSuccess={(requestId) => {
         console.log("Payment successful:", requestId);
       }}
-      onError={(error) => {
+      onPaymentError={(error) => {
         console.error("Payment failed:", error);
       }}
     >
@@ -104,7 +105,8 @@ export function PaymentWithWallet() {
       recipientWallet="0x742d35Cc6639C0532c29e54F3D4B48E4d7d5f1E0"
       walletAccount={walletClient} // Pass existing wallet
       paymentConfig={{
-         rnApiClientId: <YOUR_CLIENT_ID>,
+        reference: "your_payment_reference",
+        rnApiClientId: <YOUR_CLIENT_ID>,
         supportedCurrencies: ["ETH-sepolia-sepolia", "FAU-sepolia", "USDC-mainnet"],
       }}
       receiptInfo={{
@@ -133,10 +135,10 @@ export function PaymentWithWallet() {
         showRequestScanUrl: true,
         showReceiptDownload: true,
       }}
-      onSuccess={(requestId) => {
+      onPaymentSuccess={(requestId) => {
         console.log("Payment successful:", requestId);
       }}
-      onError={(error) => {
+      onPaymentError={(error) => {
         console.error("Payment failed:", error);
       }}
     >

app/components/payment-widget-wrapper.tsx

@@ -79,8 +79,8 @@ export function PaymentWidgetWrapper({
           totalUSD: "10.0",
         },
       }}
-      onSuccess={handleSuccess}
-      onError={handleError}
+      onPaymentSuccess={handleSuccess}
+      onPaymentError={handleError}
     >
       <div className="flex p-3 bg-blue-500 items-center rounded-2xl text-white">
         Pay using crypto

registry/default/payment-widget/README.md

@@ -74,8 +74,8 @@ function App() {
           totalTax: 0.00,
         },
       }}
-      onSuccess={(requestId, transactionReceipts) => console.log("Payment successful:", requestId, transactionReceipts)}
-      onError={(error) => console.error("Payment failed:", error)}
+      onPaymentSuccess={(requestId, transactionReceipts) => console.log("Payment successful:", requestId, transactionReceipts)}
+      onPaymentError={(error) => console.error("Payment failed:", error)}
     />
   );
 }
@@ -212,11 +212,11 @@ function App() {
 
 ### Event Handlers
 
-#### `onSuccess` (optional)
+#### `onPaymentSuccess` (optional)
 - **Type**: `(requestId: string) => void | Promise<void>`
 - **Description**: Callback function called when payment is successfully completed. Receives the Request Network request ID.
 
-#### `onError` (optional)
+#### `onPaymentError` (optional)
 - **Type**: `(error: PaymentError) => void | Promise<void>`
 - **Description**: Callback function called when payment fails. Receives detailed error information.
 
@@ -234,6 +234,35 @@ function App() {
 </PaymentWidget>
 ```
 
+## PaymentWidget Props
+
+### onComplete
+Optional callback that fires when the user closes the payment widget from the success screen. Use this to handle post-payment cleanup or navigation.
+
+```tsx
+<PaymentWidget
+  // ... other props
+  onComplete={() => {
+    // Close modal, redirect user, etc.
+    console.log("Payment flow completed");
+  }}
+/>
+```
+
+### PaymentConfig.reference
+Optional string to associate with the payment request for your own tracking purposes. This reference will be stored with the Request Network payment data.
+
+```tsx
+<PaymentWidget
+  paymentConfig={{
+    rnApiClientId: "your-client-id",
+    reference: "invoice-12345", // Your internal reference
+    supportedCurrencies: ["ETH-sepolia-sepolia"]
+  }}
+  // ... other props
+/>
+```
+
 ## Styling and Theming
 
 The Payment Widget uses Tailwind CSS and respects your application's design system through CSS custom properties. The following variables can be customized:
@@ -280,8 +309,8 @@ function PaymentWithExistingWallet() {
       receiptInfo={{
         // ... your receipt info
       }}
-      onSuccess={(requestId) => console.log("Payment successful:", requestId)}
-      onError={(error) => console.error("Payment failed:", error)}
+      onPaymentSuccess={(requestId) => console.log("Payment successful:", requestId)}
+      onPaymentError={(error) => console.error("Payment failed:", error)}
     >
       Pay with My Connected Wallet
     </PaymentWidget>
@@ -333,7 +362,7 @@ The widget includes comprehensive error handling for common scenarios:
 - **Invalid wallet addresses**
 - **API rate limiting**
 
-All errors are passed to the `onError` callback with detailed error information for debugging and user feedback.
+All errors are passed to the `onPaymentError` callback with detailed error information for debugging and user feedback.
 
 ## Browser Support
 

registry/default/payment-widget/components/payment-confirmation.tsx

@@ -32,9 +32,9 @@ export function PaymentConfirmation({
     amountInUsd,
     recipientWallet,
     connectedWalletAddress,
-    paymentConfig: { rnApiClientId, feeInfo },
+    paymentConfig: { rnApiClientId, feeInfo, reference },
     receiptInfo: { companyInfo: { name: companyName } = {} },
-    onError,
+    onPaymentError,
     walletAccount,
   } = usePaymentWidgetContext();
   const { isExecuting, executePayment } = usePayment(
@@ -58,6 +58,7 @@ export function PaymentConfirmation({
           amountInUsd,
           recipientWallet,
           paymentCurrency: selectedCurrency.id,
+          reference,
           feeInfo,
           customerInfo: {
             email: buyerInfo.email,
@@ -97,7 +98,7 @@ export function PaymentConfirmation({
       }
       setLocalError(errorMessage);
 
-      onError?.(paymentError);
+      onPaymentError?.(paymentError);
     }
   };
 

registry/default/payment-widget/components/payment-modal.tsx

@@ -27,7 +27,7 @@ export function PaymentModal({
   isOpen,
   handleModalOpenChange,
 }: PaymentModalProps) {
-  const { isWalletOverride, receiptInfo, onSuccess } =
+  const { isWalletOverride, receiptInfo, onPaymentSuccess, onComplete } =
     usePaymentWidgetContext();
 
   const [activeStep, setActiveStep] = useState<
@@ -63,7 +63,7 @@ export function PaymentModal({
       transactionReceipts[transactionReceipts.length - 1].transactionHash,
     );
     setActiveStep("payment-success");
-    await onSuccess?.(requestId, transactionReceipts);
+    await onPaymentSuccess?.(requestId, transactionReceipts);
   };
 
   const reset = () => {
@@ -80,6 +80,7 @@ export function PaymentModal({
         // reset modal state when closing from success step
         if (!isOpen && activeStep === "payment-success") {
           reset();
+          onComplete?.();
         }
         handleModalOpenChange(isOpen);
       }}

registry/default/payment-widget/context/payment-widget-context/index.ts

@@ -11,6 +11,7 @@ export interface PaymentWidgetContextValue {
   isWalletOverride: boolean;
 
   paymentConfig: {
+    reference?: string;
     rnApiClientId: string;
     feeInfo?: FeeInfo;
     supportedCurrencies: string[];
@@ -23,11 +24,12 @@ export interface PaymentWidgetContextValue {
 
   receiptInfo: ReceiptInfo;
 
-  onSuccess?: (
+  onPaymentSuccess?: (
     requestId: string,
     transactionReceipts: TransactionReceipt[],
   ) => void | Promise<void>;
-  onError?: (error: PaymentError) => void | Promise<void>;
+  onPaymentError?: (error: PaymentError) => void | Promise<void>;
+  onComplete?: () => void | Promise<void>;
 }
 
 export const PaymentWidgetContext =

registry/default/payment-widget/context/payment-widget-context/payment-widget-provider.tsx

@@ -18,11 +18,12 @@ interface PaymentWidgetProviderProps {
   >;
   uiConfig?: PaymentWidgetProps["uiConfig"];
   receiptInfo: ReceiptInfo;
-  onSuccess?: (
+  onPaymentSuccess?: (
     requestId: string,
     transactionReceipts: TransactionReceipt[],
   ) => void | Promise<void>;
-  onError?: (error: PaymentError) => void | Promise<void>;
+  onPaymentError?: (error: PaymentError) => void | Promise<void>;
+  onComplete?: () => void | Promise<void>;
 }
 
 export function PaymentWidgetProvider({
@@ -33,8 +34,9 @@ export function PaymentWidgetProvider({
   paymentConfig,
   uiConfig,
   receiptInfo,
-  onSuccess,
-  onError,
+  onPaymentSuccess,
+  onPaymentError,
+  onComplete,
 }: PaymentWidgetProviderProps) {
   const { address } = useAccount();
 
@@ -51,6 +53,7 @@ export function PaymentWidgetProvider({
       connectedWalletAddress,
       isWalletOverride,
       paymentConfig: {
+        reference: paymentConfig.reference,
         rnApiClientId: paymentConfig.rnApiClientId,
         feeInfo: paymentConfig.feeInfo,
         supportedCurrencies: paymentConfig.supportedCurrencies,
@@ -60,8 +63,9 @@ export function PaymentWidgetProvider({
         showRequestScanUrl: uiConfig?.showRequestScanUrl ?? true,
       },
       receiptInfo,
-      onSuccess,
-      onError,
+      onPaymentSuccess,
+      onPaymentError,
+      onComplete,
     }),
     [
       amountInUsd,
@@ -72,11 +76,13 @@ export function PaymentWidgetProvider({
       paymentConfig.rnApiClientId,
       paymentConfig.feeInfo,
       paymentConfig.supportedCurrencies,
+      paymentConfig.reference,
       uiConfig?.showReceiptDownload,
       uiConfig?.showRequestScanUrl,
       receiptInfo,
-      onSuccess,
-      onError,
+      onPaymentSuccess,
+      onPaymentError,
+      onComplete,
     ],
   );
 

registry/default/payment-widget/payment-widget.tsx

@@ -89,8 +89,8 @@ export function PaymentWidget({
   recipientWallet,
   paymentConfig,
   receiptInfo,
-  onSuccess,
-  onError,
+  onPaymentSuccess,
+  onPaymentError,
   uiConfig,
   walletAccount,
   children,
@@ -104,8 +104,8 @@ export function PaymentWidget({
         paymentConfig={paymentConfig}
         uiConfig={uiConfig}
         receiptInfo={receiptInfo}
-        onSuccess={onSuccess}
-        onError={onError}
+        onPaymentSuccess={onPaymentSuccess}
+        onPaymentError={onPaymentError}
       >
         <PaymentWidgetInner>{children}</PaymentWidgetInner>
       </PaymentWidgetProvider>

registry/default/payment-widget/payment-widget.types.ts

@@ -5,6 +5,7 @@ import type { FeeInfo, ReceiptInfo, PaymentError } from "./types";
 export interface PaymentConfig {
   walletConnectProjectId?: string;
   rnApiClientId: string;
+  reference?: string;
   feeInfo?: FeeInfo;
   supportedCurrencies: string[]; // an array of currency  ids
 }
@@ -59,10 +60,12 @@ export interface PaymentWidgetProps extends PropsWithChildren {
   // Receipt information
   receiptInfo: ReceiptInfo;
   // On success callback when the payment is completed
-  onSuccess?: (
+  onPaymentSuccess?: (
     requestId: string,
     receipts: TransactionReceipt[],
   ) => void | Promise<void>;
   // On error callback when the payment fails
-  onError?: (error: PaymentError) => void | Promise<void>;
+  onPaymentError?: (error: PaymentError) => void | Promise<void>;
+  // Callback when the widget is closed from the success step
+  onComplete?: () => void | Promise<void>;
 }

registry/default/payment-widget/utils/payment.ts

@@ -7,6 +7,7 @@ export interface PaymentParams {
   payerWallet: string;
   recipientWallet: string;
   paymentCurrency: string;
+  reference?: string;
   feeInfo?: FeeInfo;
   customerInfo: {
     // This matches the API spec
@@ -143,6 +144,7 @@ export const createPayout = async (
       feePercentage: feeInfo?.feePercentage || undefined,
       feeAddress: feeInfo?.feeAddress || undefined,
       customerInfo: params.customerInfo,
+      reference: params.reference,
     }),
   });