A comprehensive collection of AI-optimized upgrade rules and guidelines for popular APIs and platforms. These rules are designed to work seamlessly with AI code assistants like Cursor IDE and Claude Code to provide intelligent, context-aware code suggestions and upgrades.
- Available Upgrade Rules
- How to Use
- Key Benefits
- Upgrade Scenarios
- Customization
- Security First
- Feedback
- Contributing
- Resources
- License
Location: paypal-checkout/standard-checkout/
Standard PayPal checkout integration with Smart Payment Buttons.
Features:
- PayPal branded checkout button integration
- Server-side order creation and capture
- Multi-language support (Node.js, Python, PHP, Java, .NET, Ruby)
- Security best practices and PCI compliance
- Sandbox testing and debugging patterns
Location: paypal-checkout/expanded-checkout/
Expanded checkout with advanced card fields and additional payment methods.
Features:
- Advanced card field integration (hosted fields)
- 3D Secure authentication support
- Custom card form styling and validation
- Multi-payment method support
- PCI-compliant card processing patterns
Location: paypal-checkout/enterprise-checkout/
Enterprise-level checkout integration for platforms and marketplaces.
Features:
- Braintree Direct and Multiparty integration
- Platform and marketplace payment flows
- Vault and recurring payment patterns
- Advanced fraud protection and risk management
- PCI Level 1 compliance guidance
Location: paypal-bnpl-us/
Buy Now Pay Later integration for US merchants.
Features:
- Pay Later messaging and button integration
- Pay in 4 and Pay Monthly options
- Upstream messaging placement guidance
- Eligibility and merchant configuration
Location: nvp-soap-to-rest-migration/
Complete upgrade guide for transitioning from PayPal legacy APIs (NVP/SOAP) to modern REST APIs.
Features:
- Automatic legacy code pattern detection
- REST API endpoint mappings with official documentation links
- Multi-language support (Node.js, Python, PHP, Java, .NET, Ruby)
- Security best practices and vulnerability detection
- Side-by-side code transformation examples
- Webhook implementation patterns
- Environment configuration templates
Location: upgrade-to-v6-migration/v5-to-v6-upgrade/
Upgrade guide for transitioning from PayPal v5 Web SDK to PayPal v6 Web SDK with updated patterns and features.
Features:
- Interactive Upgrade Detection: Analysis of existing v5 implementations
- Pattern-Based Conversion: Detection and transformation of v5 patterns to v6
- Save Payment/Vault Operations: Implementation of payment method storage and reuse
- Payment Methods: Support for Venmo, Pay Later, and Credit messaging
- Security Implementation: Server-side token generation and credential management
- TypeScript Support: TypeScript definitions and type-safe implementations
- Error Handling: Debug IDs and operational patterns
- Upgrade Strategies: Parallel testing and phased rollout approaches
Location: upgrade-to-v6-migration/v4-to-v6-upgrade/
Upgrade guide for transitioning from PayPal checkout.js v4 to PayPal v6 Web SDK.
Features:
- Terminology Mapping: Complete v4 to v6 button label and funding source mapping
- Pattern-Based Conversion: Detection and transformation of v4 patterns to v6
- Component Migration: Checkout.js to web components migration
- Payment Methods: Venmo, Pay Later, and additional funding sources
- Server Integration: Updated server-side order and capture flows
- Error Handling: Debug IDs and v6 error patterns
Interactive CLI that copies only the rule pack you need into your project.
Setup (one-time):
# Clone the repo
git clone https://github.com/paypal/ruleshub.git
# Link it globally
cd ruleshub
npm link
# Then from any project folder:
cd your-project
ruleshubThe CLI will prompt you to:
- Select a rule pack
- Select a target (Cursor IDE or Claude Code)
Files are copied to the appropriate location automatically.
You can also use flags for non-interactive mode:
ruleshub --pack 4 --target 1Copy the relevant rules file to your project:
# Choose the appropriate upgrade rules for your project
cp [upgrade-folder]/rules.md your-project/.cursor/rules/CURSOR.mdc # For Cursor IDE
cp [upgrade-folder]/rules.md your-project/CLAUDE.md # For Claude CodeAdd RulesHub as a submodule to your project:
cd your-project
git submodule add https://github.com/paypal/ruleshub.git rulesAdd references in your existing CURSOR.mdc or CLAUDE.md:
# Upgrade Rules
Apply upgrade patterns from RulesHub/[upgrade-folder]/rules.md- Pattern Recognition: AI assistants detect legacy code patterns (NVP/SOAP calls, v5 SDK implementations)
- Context-Aware Suggestions: Upgrade suggestions based on code context
- Security Scanning: Detection of security vulnerabilities and practices
- Setup Analysis: Detection of current PayPal integration patterns through code analysis
- Multi-Language Support: Rules work across JavaScript, TypeScript, Python, PHP, Java, .NET, and more
- Upgrade Paths: From authentication to webhooks, various aspects covered
- Payment Methods: Support for save payments, Venmo, Pay Later, and credit messaging
- Best Practices: Industry-standard security and performance practices included
- Cursor IDE Integration: Integration with Cursor's AI capabilities
- Claude Code Compatible: Works with Claude Code's context understanding
- Documentation: Includes links to official API documentation and examples
- Upgrade Support: Enables parallel testing and phased rollouts
- TypeScript Definitions: Type safety and IntelliSense support
When beginning a fresh integration, AI assistants will:
- Suggest API patterns from the start (REST APIs, v6 SDK)
- Provide configuration templates
- Include error handling
- Recommend current practices
- Guide toward implementations
When working with existing legacy code:
- Detect outdated patterns (NVP/SOAP, v5 SDK)
- Suggest equivalents (REST APIs, v6 SDK)
- Provide step-by-step upgrade guidance
- Support backward compatibility during transition
- Support parallel testing strategies
During development and review:
- Flag potential security issues
- Suggest performance optimizations
- Recommend API version upgrades (v5 → v6 SDK)
- Support compliance with platform guidelines
- Validate error handling and debug patterns
Each upgrade folder can be extended with project-specific rules:
## Custom Project Rules
- Your specific business logic patterns
- Internal coding standards
- Company-specific security requirements
- Custom payment flow implementations
- Environment-specific SDK configurationsModify rules for different deployment environments:
## Development Environment
- Enable verbose logging
- Use sandbox/test endpoints
- Include debugging information
- Enable PayPal Debug IDs for troubleshooting
- Use development SDK configurations
## Production Environment
- Minimize sensitive data logging
- Use production endpoints
- Enhanced security validation
- Implement proper error handlingAll upgrade rules prioritize security:
- Credential Management: Environment variable recommendations
- HTTPS Enforcement: Secure communication patterns only
- Data Protection: No logging of sensitive information
- Vulnerability Detection: Automatic flagging of security issues
- Compliance: Platform-specific compliance requirements
- Server-Side Token Generation: Client token patterns
- Webhook Signature Verification: Webhook security implementation
We'd love to hear about your experience with RulesHub.
- PayPal Documentation - Official guides and API references: https://developer.paypal.com/
Help improve RulesHub by:
- Testing Rules: Use the rules in your projects and provide feedback
- Documenting Gaps: Report missing patterns or edge cases
- Adding New Upgrades: Contribute rules for other platforms
- Improving Examples: Enhance code examples and documentation
- Test all rules thoroughly before submitting
- Include comprehensive documentation
- Follow existing file structure and naming conventions
- Ensure security best practices are maintained
- API Documentation: Links to official platform documentation
- Upgrade Guides: Platform-specific upgrade resources
- Community Support: Developer community forums and support
- Best Practices: Industry-standard implementation patterns
- TypeScript Definitions: Official type definitions for v6 SDK
See LICENSE for details.
Note: Start with sandbox/test environments when using upgrade rules. Validate all implementations against your specific business requirements before deploying to production.
v5 to v6 Upgrade: If you're currently using PayPal v5 Web SDK, consider upgrading to v6 for updated features and TypeScript support. The v6 SDK provides TypeScript definitions, save payment capabilities, and support for payment methods like Venmo and Pay Later.