Payment System

Overview

Zafira's payment system provides a comprehensive solution for creating payment requests, generating QR codes, and managing payment charges with real-time tracking and notifications.

Payment Charge Creation

Creating Charges

• Unique UUIDs: Each charge gets a unique identifier for tracking
• QR Code Generation: Automatic QR code creation for easy payments
• Expiration Management: Configurable expiration times
• Dynamic/Static Modes: Flexible payment amount handling

Charge Types

• Dynamic Charges: Payer can adjust the amount
• Static Charges: Fixed amount that cannot be changed
• Recurring Charges: Set up recurring payment requests
• Bulk Charges: Create multiple charges at once

QR Code Integration

QR Code Content

The system generates QR codes with URI format:

ethereum:0x0b88b41fdc5b2127c4082145fc34828b7d20a301@97?data=0xa9059cbb...

Payment Link Generation

Use the UUID to generate payment links:

https://zafira-app.domain.com/wallet/pay/{uuid}

QR Code Libraries

// Example QR code generation
const QRCode = require('qrcode');
const qrContent = charge.data.content;
const qrCodeImage = await QRCode.toDataURL(qrContent);

Payment Processing

Automatic Detection

• Blockchain Monitoring: Automatic payment detection on blockchain
• Real-time Updates: Instant payment confirmation
• Status Tracking: Monitor payment status in real-time

Payment Status

• pending: Payment request created but not yet paid
• confirmed: Payment confirmed on blockchain
• failed: Payment failed or reverted
• expired: Payment request expired without payment

Failed Payment Handling

• Automatic Retry: Retry failed payments with adjusted gas
• Error Logging: Comprehensive error logging and tracking
• User Notifications: Notify users of payment failures

Integration Features

Webhook Integration

Charges trigger webhook events:

• charge.created: When charge is created
• charge.paid: When payment is confirmed
• charge.expired: When charge expires
• charge.failed: When payment fails

API Integration

• RESTful Endpoints: Complete API for charge management
• Real-time Updates: Live payment status updates
• Bulk Operations: Create and manage multiple charges
• Search and Filter: Find charges by various criteria

Security Features

Payment Security

• Signature Verification: Optional HMAC-SHA256 signatures
• Input Validation: Comprehensive validation of payment data
• Rate Limiting: Prevent abuse of payment endpoints
• Audit Trail: Complete audit trail of all payment activities

Data Protection

• Encrypted Storage: Sensitive payment data encrypted at rest
• Secure Transmission: HTTPS for all payment communications
• Access Control: Role-based access to payment functions
• Privacy Protection: Protect user payment information

Best Practices

Charge Management

• Set appropriate expiration times based on use case
• Use descriptive charge information for tracking
• Monitor charge status through webhooks
• Implement proper error handling for expired charges

User Experience

• Provide clear payment instructions
• Show payment status in real-time
• Handle payment failures gracefully
• Offer multiple payment methods when possible

Security Considerations

• Validate all incoming payment data
• Use HTTPS for payment links
• Implement rate limiting for charge creation
• Monitor for suspicious payment patterns

Common Use Cases

E-commerce Integration

• Product Payments: Create charges for product purchases
• Service Payments: Handle service-based payments
• Subscription Payments: Manage recurring payments
• Refund Processing: Handle payment refunds

Business Applications

• Invoice Payments: Generate payment requests for invoices
• Donation Systems: Accept donations with QR codes
• Event Payments: Handle event registration payments
• Subscription Services: Manage subscription payments

Mobile Applications

• In-app Payments: Integrate payments in mobile apps
• QR Code Scanning: Scan QR codes for payments
• Push Notifications: Notify users of payment status
• Offline Support: Handle payments when offline

Troubleshooting

Common Issues

• Charge Not Found: Verify charge ID and wallet access
• Payment Not Detected: Check blockchain connectivity
• QR Code Not Working: Verify QR code content format
• Expired Charges: Handle expiration gracefully

Debug Tools

• Payment Logs: View detailed payment processing logs
• Blockchain Explorer: Verify payments on blockchain
• Webhook Logs: Check webhook delivery status
• API Testing: Test payment endpoints

Next Steps

• API Documentation - Complete API reference
• Webhook System - Set up payment notifications
• Security Features - Security and compliance