feat: add option to pass a reference, tidy up callbacks #6
Conversation
WalkthroughRenamed PaymentWidget callbacks from onSuccess/onError to onPaymentSuccess/onPaymentError, added optional onComplete, and introduced paymentConfig.reference. Propagated these changes through types, context/provider, components, utils, examples, and documentation; included reference in API payout payloads. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant Widget as PaymentWidget
participant Provider as PaymentWidgetProvider
participant Modal as PaymentModal
participant Confirm as PaymentConfirmation
participant API as Backend API
User->>Widget: open()
Widget->>Provider: init(props: paymentConfig{reference?}, onPaymentSuccess?, onPaymentError?, onComplete?)
Provider->>Modal: render
User->>Modal: confirm payment
Modal->>Confirm: prepare params (amount, recipient, reference?)
Confirm->>API: executePayment(params with reference?)
alt success
API-->>Confirm: requestId, receipts
Confirm->>Provider: await onPaymentSuccess?(requestId, receipts)
User->>Modal: close success
Modal->>Provider: onComplete?()
else error
API-->>Confirm: PaymentError
Confirm->>Provider: onPaymentError?(PaymentError)
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (1)
🧰 Additional context used🧠 Learnings (2)📚 Learning: 2025-09-17T12:08:58.198ZApplied to files:
📚 Learning: 2025-09-17T12:08:58.198ZApplied to files:
🔇 Additional comments (9)
Comment |
bassgeta
force-pushed
the
fix/payment-reference
branch
from
6836c1e to
c31d25f
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
registry/default/payment-widget/payment-widget.tsx (1)
87-97: Pass onComplete to the provider.The
onCompletecallback is defined inPaymentWidgetPropsbut is not destructured from props or passed toPaymentWidgetProvider. This means the callback will never fire even if a consumer provides it.Apply this diff to fix the issue:
export function PaymentWidget({ amountInUsd, recipientWallet, paymentConfig, receiptInfo, onPaymentSuccess, onPaymentError, + onComplete, uiConfig, walletAccount, children, }: PaymentWidgetProps) { return ( <Web3Provider walletConnectProjectId={paymentConfig.walletConnectProjectId}> <PaymentWidgetProvider amountInUsd={amountInUsd} recipientWallet={recipientWallet} walletAccount={walletAccount} paymentConfig={paymentConfig} uiConfig={uiConfig} receiptInfo={receiptInfo} onPaymentSuccess={onPaymentSuccess} onPaymentError={onPaymentError} + onComplete={onComplete} > <PaymentWidgetInner>{children}</PaymentWidgetInner> </PaymentWidgetProvider> </Web3Provider> ); }
🧹 Nitpick comments (1)
registry/default/payment-widget/payment-widget.types.ts (1)
69-70: Clarify the onComplete callback timing.The comment states "Callback when the widget is closed from the success step", but based on the implementation in
payment-modal.tsx(lines 79-86), this callback fires when the modal closes from the success step. Consider clarifying whether this fires only on user-initiated close or also programmatic close.Apply this diff to improve the comment:
- // Callback when the widget is closed from the success step + // Callback invoked when the modal is closed after reaching the payment success step onComplete?: () => void | Promise<void>;
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
app/components/homepage.tsx(4 hunks)app/components/payment-widget-wrapper.tsx(1 hunks)public/r/payment-widget.json(6 hunks)registry/default/payment-widget/README.md(5 hunks)registry/default/payment-widget/components/payment-confirmation.tsx(3 hunks)registry/default/payment-widget/components/payment-modal.tsx(3 hunks)registry/default/payment-widget/context/payment-widget-context/index.ts(2 hunks)registry/default/payment-widget/context/payment-widget-context/payment-widget-provider.tsx(5 hunks)registry/default/payment-widget/payment-widget.tsx(2 hunks)registry/default/payment-widget/payment-widget.types.ts(2 hunks)registry/default/payment-widget/utils/payment.ts(2 hunks)
🧰 Additional context used
🧬 Code graph analysis (3)
registry/default/payment-widget/payment-widget.types.ts (1)
registry/default/payment-widget/types/index.ts (1)
PaymentError(8-11)
registry/default/payment-widget/context/payment-widget-context/index.ts (1)
registry/default/payment-widget/types/index.ts (1)
PaymentError(8-11)
registry/default/payment-widget/context/payment-widget-context/payment-widget-provider.tsx (1)
registry/default/payment-widget/types/index.ts (1)
PaymentError(8-11)
🔇 Additional comments (33)
registry/default/payment-widget/payment-widget.types.ts (2)
8-8: LGTM! Optional reference field added correctly.The addition of the optional
referencefield toPaymentConfigallows consumers to pass custom payment references while maintaining backward compatibility.
63-68: LGTM! Callback renames improve API clarity.Renaming
onSuccess→onPaymentSuccessandonError→onPaymentErrormakes the API more explicit and aligns with the introduction of the newonCompletelifecycle callback.registry/default/payment-widget/context/payment-widget-context/index.ts (2)
14-14: LGTM! Reference field added to context.The optional
referencefield is correctly added to the context'spaymentConfig, maintaining consistency with the public API.
27-32: LGTM! Context callbacks updated correctly.The context value type correctly reflects the renamed callbacks (
onPaymentSuccess,onPaymentError) and the newonCompletelifecycle hook, maintaining signature compatibility.registry/default/payment-widget/context/payment-widget-context/payment-widget-provider.tsx (4)
21-26: LGTM! Provider props updated correctly.The provider interface correctly reflects the renamed callbacks and maintains backward compatibility by keeping all callbacks optional.
56-56: LGTM! Reference field threaded through context.The
referencefield frompaymentConfigis correctly extracted and included in the context value, enabling downstream components to access it.
66-68: LGTM! Callbacks properly wired through context.The renamed callbacks (
onPaymentSuccess,onPaymentError) and newonCompletecallback are correctly included in the context value.
79-85: LGTM! Dependency array correctly updated.All new and renamed props (
paymentConfig.reference,onPaymentSuccess,onPaymentError,onComplete) are correctly added to theuseMemodependency array, preventing stale closures.registry/default/payment-widget/utils/payment.ts (2)
10-10: LGTM! Reference parameter added correctly.The optional
referencefield is properly added toPaymentParams, maintaining consistency with the interface design pattern used for other optional fields.
147-147: LGTM! Reference forwarded to API.The
referencefield is correctly included in the payout API request payload, enabling the backend to associate payments with custom references.registry/default/payment-widget/payment-widget.tsx (1)
92-93: LGTM! Callback props renamed correctly.The destructured props correctly use the new callback names
onPaymentSuccessandonPaymentError, maintaining consistency with the type definitions.registry/default/payment-widget/components/payment-confirmation.tsx (3)
35-35: LGTM! Reference extracted from context.The
referencefield is correctly destructured frompaymentConfigin the context, making it available for the payment flow.
61-61: LGTM! Reference included in payment payload.The
referenceis correctly passed toexecutePayment, ensuring it's included in the API request to associate the payment with the custom reference.
37-37: LGTM! Error callback correctly updated.The error handling correctly uses the renamed
onPaymentErrorcallback from the context (line 37) and invokes it appropriately (line 101).Also applies to: 101-101
app/components/payment-widget-wrapper.tsx (1)
82-83: LGTM! Wrapper updated with renamed callbacks.The wrapper correctly uses the renamed callback props
onPaymentSuccessandonPaymentError, maintaining consistency with the updated public API.registry/default/payment-widget/components/payment-modal.tsx (3)
30-31: LGTM! Modal uses renamed callbacks from context.The modal correctly destructures
onPaymentSuccessandonCompletefrom the context, enabling the new lifecycle hooks.
57-67: LGTM! Payment success handler awaits callback.The
onPaymentSuccesscallback is correctly awaited, allowing consumers to perform async operations (e.g., analytics, logging) before the UI transitions to the success state.
79-86: LGTM! onComplete fires on modal close from success.The
onCompletecallback is correctly invoked when the modal closes from the payment success step, providing consumers with a lifecycle hook to react to payment completion and modal dismissal.app/components/homepage.tsx (4)
58-58: LGTM: Reference field correctly added.The
referencefield is properly placed inpaymentConfigwith an appropriate placeholder value for documentation purposes.
84-89: LGTM: Callback props correctly renamed.The callback props have been renamed from
onSuccess/onErrortoonPaymentSuccess/onPaymentError, maintaining the correct signatures and usage.
108-109: LGTM: Reference field consistently added.The
referencefield is correctly added to thePaymentWithWalletexample, maintaining consistency with theBasicPaymentexample.
138-143: LGTM: Callbacks consistently renamed.The callback props are correctly renamed to
onPaymentSuccess/onPaymentError, maintaining consistency with theBasicPaymentexample and the updated API.registry/default/payment-widget/README.md (5)
77-78: LGTM: Basic usage example correctly updated.The callbacks in the basic usage example correctly demonstrate the renamed
onPaymentSuccessandonPaymentErrorprops with appropriate parameters.
215-221: LGTM: Event handlers correctly documented.The event handlers section properly documents
onPaymentSuccessandonPaymentErrorwith accurate signatures and descriptions.
237-264: LGTM: New features well documented.The new
onCompletecallback andPaymentConfig.referencefield are clearly documented with appropriate examples and descriptions that explain their purpose and usage.
312-313: LGTM: Wagmi example correctly updated.The Wagmi example correctly uses the renamed callback props, maintaining consistency with other documentation examples.
365-365: LGTM: Error handling section correctly updated.The reference to the error callback has been properly updated to use
onPaymentError.public/r/payment-widget.json (6)
98-98: LGTM: Type definitions correctly updated.The
PaymentWidgetPropsandPaymentConfigtypes correctly reflect the API changes:
referencefield added as optional string- Callbacks renamed to
onPaymentSuccessandonPaymentErrorwith correct signatures- New
onCompletecallback added
32-32: LGTM: Context types correctly updated.The
PaymentWidgetContextValueinterface properly includes thereferencefield inpaymentConfigand all three callback props with correct signatures.
38-38: LGTM: Provider correctly propagates new props.The
PaymentWidgetProviderproperly:
- Accepts and destructures the new callback props and reference field
- Includes
referencein the context'spaymentConfigobject- Adds all new fields to the
useMemodependency array
62-62: LGTM: PaymentModal correctly handles callbacks.The
PaymentModalcomponent properly:
- Retrieves
onPaymentSuccessandonCompletefrom context- Calls
onPaymentSuccesswhen payment succeeds- Calls
onCompletewhen the modal is closed from the success step
80-80: LGTM: PaymentConfirmation correctly uses reference and callbacks.The
PaymentConfirmationcomponent properly:
- Extracts
referencefrompaymentConfigvia context- Passes
referenceto the payment execution flow- Uses
onPaymentErrorfor error handling
116-116: LGTM: Payment utils correctly handle reference field.The
PaymentParamsinterface includes the optionalreferencefield, and thecreatePayoutfunction properly includes it in the API request payload sent to the backend.
There was a problem hiding this comment.
Pull Request Review Report
Overview
This PR introduces several enhancements to the Payment Widget component, focusing on improved callback naming consistency, payment reference tracking, and post-payment flow handling.
Summary of Changes
🔄 Callback Prop Renaming
- Changed:
onSuccess→onPaymentSuccess - Changed:
onError→onPaymentError - Impact: Improves API clarity and consistency across the component
✨ New Features
1. Payment Reference Tracking
- Added:
reference?: stringfield toPaymentConfiginterface - Purpose: Allows associating custom tracking identifiers with payment requests
- Usage: Optional field for internal payment tracking and reconciliation
2. Post-Payment Completion Callback
- Added:
onComplete?: () => void | Promise<void>prop - Purpose: Handles cleanup or navigation after payment flow completion
- Trigger: Called when user closes the payment widget from the success screen
Detailed Changes by File
Type Definitions (payment-widget.types.ts)
// Added to PaymentConfig
reference?: string;
// Renamed in PaymentWidgetProps
onPaymentSuccess?: (requestId: string, receipts: TransactionReceipt[]) => void | Promise<void>;
onPaymentError?: (error: PaymentError) => void | Promise<void>;
// Added to PaymentWidgetProps
onComplete?: () => void | Promise<void>;Context Layer Updates
- Context Interface: Updated to include new
referenceandonCompleteproperties - Provider: Properly passes through all new props to context consumers
- Hook: Maintains backward compatibility while exposing new functionality
Payment Logic (utils/payment.ts)
- PaymentParams Interface: Added
reference?: stringfield - API Integration: Reference field properly included in payout creation request
- Backward Compatibility: Reference field is optional, maintaining existing integrations
Payment Execution (hooks/use-payment.ts)
- Parameter Passing: Reference field correctly propagated through payment execution chain
- Type Safety: All type definitions updated consistently
UI Components
- Payment Modal: Integrated
onCompletecallback with modal close handling - Success Flow: Proper callback invocation when user completes payment flow
Documentation (README.md)
- Updated Examples: All code examples use new callback names
- New Props Documentation: Comprehensive documentation for
referenceandonCompleteprops - Migration Guide: Clear guidance on new prop usage
Code Quality Assessment
✅ Strengths
- Consistent Naming: The renaming from
onSuccess/onErrortoonPaymentSuccess/onPaymentErrorprovides better semantic clarity - Type Safety: All changes maintain strict TypeScript typing
- Backward Compatibility: New features are optional and don't break existing implementations
- Comprehensive Updates: Changes are consistently applied across all layers (types, context, hooks, components)
- Documentation: README thoroughly updated with examples and usage guidance
✅ Implementation Quality
- Proper Context Flow: New props correctly flow through the context system
- Optional Fields: All new features are optional, maintaining API stability
- Error Handling: Existing error handling patterns preserved
- Clean Integration: Reference field cleanly integrated into payment API calls
Testing Considerations
✅ Verified Functionality
- Type definitions are consistent across all files
- Context properly propagates new props
- Payment API correctly includes reference field
- Modal properly handles completion callback
🔍 Recommended Testing
- Integration Tests: Verify
onCompletecallback fires correctly on modal close from success state - API Tests: Confirm
referencefield is properly sent to Request Network API - Backward Compatibility: Ensure existing implementations without new props continue working
- Type Checking: Verify TypeScript compilation with both old and new prop patterns
Migration Impact
🟢 Low Risk Changes
- All new features are optional
- Existing implementations will continue working without modification
- No breaking changes to core functionality
📝 Developer Migration
Developers can optionally update their implementations:
// Before
<PaymentWidget
onSuccess={(requestId) => console.log('Success:', requestId)}
onError={(error) => console.error('Error:', error)}
/>
// After (optional migration)
<PaymentWidget
onPaymentSuccess={(requestId, receipts) => console.log('Success:', requestId, receipts)}
onPaymentError={(error) => console.error('Error:', error)}
onComplete={() => console.log('Payment flow completed')}
paymentConfig={{
// ... other config
reference: "invoice-12345" // Optional tracking reference
}}
/>Recommendations
✅ Approve
This PR is well-implemented and ready for merge:
- Clean Implementation: All changes are consistently applied across the codebase
- Maintains Compatibility: No breaking changes for existing users
- Adds Value: New features provide useful functionality for payment tracking and flow management
- Good Documentation: README properly updated with examples and guidance
- Type Safety: All TypeScript definitions are properly maintained
🔧 Minor Suggestions
- Consider adding JSDoc comments to new interface properties for better IDE support
- Could add validation for
referencefield length/format if API has constraints
Conclusion
This is a solid enhancement PR that improves the Payment Widget's API consistency and adds valuable new features. The implementation is clean, well-documented, and maintains backward compatibility. The changes follow good software engineering practices and are ready for production use.
Recommendation: ✅ APPROVE AND MERGE
Problem
Even though we allow our users to pass their own payment reference via the API, I completely forgot to add that when initially developing the widget 🫠
Solution
Add the
referencevariable under thepaymentConfigprop.Changes
referenceapp wideonError->onPaymentErroronSuccess->onPaymentSuccessonCompletecallback to fire when the modal is closedSummary by CodeRabbit
New Features
Documentation