This guide explains how to configure and use the Stripe payment integration in the Commerce application.
\`\`\`
#### 2. Create Order with Payment
When creating an order, include the payment information:
\`\`\`javascript
const orderData = {
// ... order details (items, shipping, etc.)
payment: {
paymentMethodToken: "pm_xxx", // From Stripe.js createPaymentMethod()
providerName: "stripe" // Optional: defaults to active provider
}
};
// POST /api/orders with payment data
fetch('/api/orders', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify(orderData)
});
\`\`\`
### Backend API
The payment processing is integrated into the order creation flow through the \`OrderPaymentService\`.
#### Key Methods:
\`\`\`java
// Process payment for an order
PaymentTransaction processOrderPayment(
Order order,
String paymentMethodToken,
String providerName
);
// Refund an order
PaymentTransaction refundOrder(
Order order,
BigDecimal amount,
String reason
);
\`\`\`
### Webhook Setup
Stripe uses webhooks to notify your application about asynchronous events (like successful payments, failed payments, refunds).
#### 1. Configure Webhook Endpoint
In Stripe Dashboard:
1. Go to Developers → Webhooks
2. Click "Add endpoint"
3. Enter your webhook URL: \`https://your-domain.com/api/webhooks/stripe\`
4. Select events to listen for:
- \`payment_intent.succeeded\`
- \`payment_intent.payment_failed\`
- \`payment_intent.canceled\`
- \`charge.refunded\`
5. Copy the **Signing secret** (starts with \`whsec_\`)
#### 2. Update Configuration
Update your database configuration with the webhook secret:
\`\`\`sql
UPDATE payment_processor_config
SET configuration_json = '{"webhook_secret": "whsec_YOUR_WEBHOOK_SECRET"}'
WHERE processor_name = 'stripe';
\`\`\`
## Testing
### Test with Stripe Test Cards
Stripe provides test card numbers:
- **Success**: \`4242 4242 4242 4242\`
- **Decline**: \`4000 0000 0000 0002\`
- **Requires authentication**: \`4000 0025 0000 3155\`
Use any future expiry date, any 3-digit CVC, and any billing ZIP code.
### Test Webhooks Locally
Use Stripe CLI to forward webhooks to your local development environment:
\`\`\`bash
# Install Stripe CLI
brew install stripe/stripe-cli/stripe
# Login
stripe login
# Forward webhooks
stripe listen --forward-to localhost:8080/api/webhooks/stripe
# Trigger test events
stripe trigger payment_intent.succeeded
\`\`\`
## Extending with Additional Payment Providers
To add another payment provider (e.g., PayPal, Square):
1. **Create Provider Implementation**:
\`\`\`java
public class PayPalPaymentProvider implements PaymentProvider {
@Override
public String getProviderName() {
return "paypal";
}
@Override
public PaymentResponse processPayment(PaymentRequest request) {
// Implement PayPal integration
}
// Implement other methods...
}
\`\`\`
2. **Register the Provider**:
Add to \`META-INF/services/com.ststsi.commerce.extensions.payment.spi.PaymentProvider\`:
\`\`\`
com.ststsi.commerce.extensions.payment.stripe.StripePaymentProvider
com.ststsi.commerce.extensions.payment.paypal.PayPalPaymentProvider
\`\`\`
3. **Configure in Database**:
\`\`\`sql
INSERT INTO payment_processor_config (processor_type, processor_name, api_key, ...)
VALUES ('PAYPAL', 'paypal', 'your-paypal-credentials', ...);
\`\`\`
## Security Considerations
1. **Never expose secret keys**: Keep API keys secure and never commit them to version control
2. **Use HTTPS**: Always use HTTPS in production for API endpoints and webhooks
3. **Verify webhooks**: The webhook controller verifies Stripe signatures to prevent tampering
4. **PCI Compliance**: By using Stripe Elements/Stripe.js, card data never touches your servers, reducing PCI compliance scope
5. **Environment separation**: Use test keys for development/staging and live keys only for production
## Troubleshooting
### Payment fails with "Payment provider not found"
- Ensure Stripe configuration is inserted in database with \`is_active = true\`
- Verify \`processor_name\` is set to \`'stripe'\` (lowercase)
### Webhook signature verification fails
- Check that \`webhook_secret\` in configuration_json matches your Stripe webhook signing secret
- Ensure webhook URL is correct and accessible from internet
### "Stripe API key is required" error
- Verify api_key is set in payment_processor_config table
- Ensure the key starts with \`sk_test_\` or \`sk_live_\`
## Database Schema
### payment_transactions
Stores all payment transaction records:
- Links to orders via \`order_id\`
- Stores provider name, transaction ID, status
- Includes payment method details and error information
- Timestamps for tracking
### payment_processor_config
Configuration for payment providers:
- \`processor_type\`: Enum (STRIPE, SQUARE, MONERIS)
- \`processor_name\`: String identifier for SPI lookup
- \`api_key\`: Encrypted API key
- \`configuration_json\`: Additional configuration (webhooks, etc.)
- \`is_active\`: Enable/disable provider
## Support
For issues or questions:
1. Check Stripe API documentation: https://stripe.com/docs/api
2. Review stripe-java SDK docs: https://github.com/stripe/stripe-java
3. Check application logs for detailed error messages
`;
// Render markdown to HTML
document.getElementById('markdown-content').innerHTML = marked.parse(markdownContent);