Building Integrated Payments in Craft CMS 5

This comprehensive guide walks you through building efficient eCommerce solutions with integrated payments using Craft CMS 5, covering everything from setup to advanced implementations for high-converting online stores.

Why Choose Craft CMS for Integrated Payment Solutions?

Craft CMS stands out as a content management system built for developers who need flexibility without sacrificing ease of use. When combined with Craft Commerce, it creates a robust eCommerce platform that gives you complete control over the checkout experience.

Our team regularly works with businesses that need custom payment flows, and Craft's approach consistently delivers results. Unlike rigid platforms that force you into predefined checkout templates, Craft lets you design payment experiences that match your brand and customer needs exactly.

The platform supports multiple payment gateways out of the box, handles complex product catalogs, and scales from small businesses to enterprise-level operations. Based on project work, we've seen businesses increase their conversion rates by 15-25% simply by implementing properly integrated payments through Craft Commerce.

Current Payment Gateway Options for Craft Commerce 5

Craft Commerce 5 offers expanded gateway support with improved performance and security features. Here's what's available:

Popular Gateway Options:

• Stripe: Most widely used, supports Apple Pay, Google Pay, and Strong Customer Authentication
• Quickpay: Flexible European-focused gateway with extensive payment method support
• Authorize.Net: Essential for high-risk merchants (CBD, vape, alcohol industries)
• Mollie: European gateway with Buy Now, Pay Later options
• PayPal Checkout: Widely recognized, easy customer adoption
• Square: Good for businesses with physical locations
• Braintree: PayPal-owned gateway with advanced features

When working with clients, we typically recommend Stripe for most standard eCommerce operations due to its reliability and feature set. However, businesses in regulated industries often need Authorize.Net or NMI for their specialized merchant account requirements.

Setting Up Integrated Payments: Complete Step-by-Step Process

1. Install Craft CMS and Commerce Plugin

Start with a fresh Craft CMS installation and add Commerce:

composer create-project craftcms/craft my-ecommerce-project
cd my-ecommerce-project
composer require craftcms/commerce
php craft plugin/install commerce

2. Choose Your Payment Gateway Integration

Select a gateway plugin based on your business needs:

# For Stripe (most common)
composer require craftcms/commerce-stripe
php craft plugin/install commerce-stripe

# For Quickpay (European businesses)
composer require craftcms/commerce-quickpay
php craft plugin/install commerce-quickpay

# For Authorize.Net (high-risk merchants)
composer require craftcms/commerce-authorize
php craft plugin/install commerce-authorize

3. Configure Gateway Settings for Maximum Security

Navigate to Commerce > Settings > Gateways in your Craft admin panel. Add your chosen gateway and configure these critical settings:

• API Credentials: Use environment variables for security
• Payment Mode: Set to "Accept payments on site" for integrated checkout
• Security Features: Enable 3D Secure, AVS, and CVV checks
• Webhook URLs: Configure for real-time payment status updates

Our approach involves setting up separate gateways for testing and production environments. This allows thorough testing without affecting live transactions.

4. Create Custom Checkout Templates with Integrated Payment Forms

Craft Commerce provides complete control over checkout design. Here's a basic integrated payment form using Stripe:

{# checkout.twig #}

5. Handle Payment Intents and Strong Customer Authentication

For gateways like Stripe that require Strong Customer Authentication (SCA), implement Payment Intents:

// In your payment controller
public function actionProcessPayment()
{
    $request = Craft::$app->getRequest();
    $paymentMethodId = $request->getBodyParam('paymentMethodId');
    
    $order = Commerce::getInstance()->getCarts()->getCart();
    $gateway = $order->getGateway();
    
    // Create payment intent
    $paymentIntent = $gateway->createPaymentIntent($order, $paymentMethodId);
    
    if ($paymentIntent->requiresAction()) {
        // Return client secret for 3D Secure authentication
        return $this->asJson([
            'requiresAction' => true,
            'clientSecret' => $paymentIntent->client_secret
        ]);
    }
    
    // Process successful payment
    return $this->redirect('checkout/complete');
}

Advanced Implementation Examples for Complex Payment Scenarios

Multi-Gateway Setup for International Sales

Many businesses need different payment methods for different regions. Here's how we configure multi-gateway setups:

// In your checkout template
{% set userCountry = craft.app.request.getIpAddress() | country %}
{% if userCountry in ['DE', 'NL', 'BE'] %}
    {% set gateway = craft.commerce.gateways.getGatewayByHandle('mollie') %}
{% elseif userCountry in ['DK', 'SE', 'NO'] %}
    {% set gateway = craft.commerce.gateways.getGatewayByHandle('quickpay') %}
{% else %}
    {% set gateway = craft.commerce.gateways.getGatewayByHandle('stripe') %}
{% endif %}

High-Risk Merchant Implementation

For businesses selling regulated products, proper gateway configuration is crucial:

// Configure Authorize.Net for high-risk processing
$gateway = new AuthorizeNetGateway([
    'apiLoginId' => App::env('AUTHNET_API_LOGIN_ID'),
    'transactionKey' => App::env('AUTHNET_TRANSACTION_KEY'),
    'testMode' => App::env('AUTHNET_TEST_MODE'),
    'developerMode' => App::env('AUTHNET_DEVELOPER_MODE'),
    'enableAvs' => true,
    'enableCvv' => true,
    'requireAvs' => true,
    'requireCvv' => true
]);

Subscription Payment Integration

For recurring payments, implement subscription handling:

{# subscription-checkout.twig #}

Security Best Practices for Integrated Payment Processing

Working with payments requires strict security measures. Here's what we implement for every project:

PCI Compliance Requirements

• Use gateway-hosted payment fields (like Stripe Elements)
• Never store raw card data in your database
• Tokenize payment methods for future use
• Implement proper SSL/TLS encryption

Environment Configuration

Store sensitive credentials securely:

// .env file
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
AUTHNET_API_LOGIN_ID=your_login_id
AUTHNET_TRANSACTION_KEY=your_transaction_key

Fraud Prevention Measures

Enable all available security features:

• 3D Secure authentication
• Address Verification System (AVS)
• CVV verification
• Velocity checking
• IP geolocation validation

Common Implementation Challenges and Solutions

Webhook Handling for Payment Status Updates

Payment gateways send webhooks to update order status. Here's proper webhook handling:

// WebhookController.php
public function actionStripeWebhook()
{
    $payload = Craft::$app->getRequest()->getRawBody();
    $sig = Craft::$app->getRequest()->getHeaders()->get('stripe-signature');
    
    try {
        $event = \Stripe\Webhook::constructEvent($payload, $sig, $this->endpointSecret);
    } catch (\Exception $e) {
        return $this->asJson(['error' => 'Webhook signature verification failed']);
    }
    
    // Handle the event
    switch ($event->type) {
        case 'payment_intent.succeeded':
            $this->handlePaymentSuccess($event->data->object);
            break;
        case 'payment_intent.payment_failed':
            $this->handlePaymentFailure($event->data->object);
            break;
        default:
            return $this->asJson(['error' => 'Unhandled event type']);
    }
    
    return $this->asJson(['status' => 'success']);
}

Currency and Localization Management

Configure multiple currencies and payment methods:

// In your Commerce settings
$primaryCurrency = 'USD';
$allowedCurrencies = ['USD', 'EUR', 'GBP', 'CAD'];

// Gateway-specific currency handling
if ($gateway->handle === 'mollie' && $order->currency === 'USD') {
    // Mollie doesn't support USD, convert to EUR
    $convertedAmount = $this->convertCurrency($order->total, 'USD', 'EUR');
}

Performance Optimization for Payment Processing

Caching Payment Forms

Cache payment form generation for better performance:

// Use Craft's caching system
$cache = Craft::$app->getCache();
$cacheKey = 'payment_form_' . $gateway->id . '_' . $order->id;

$paymentForm = $cache->getOrSet($cacheKey, function() use ($gateway, $order) {
    return $gateway->getPaymentFormHtml($order);
}, 300); // Cache for 5 minutes

Async Payment Processing

Handle payment processing asynchronously for better user experience:

// Process payment without blocking UI
async function processPayment(paymentData) {
    const loadingIndicator = document.getElementById('payment-loading');
    loadingIndicator.style.display = 'block';
    
    try {
        const response = await fetch('/payments/process', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(paymentData)
        });
        
        const result = await response.json();
        
        if (result.success) {
            window.location.href = '/checkout/complete';
        } else {
            displayError(result.error);
        }
    } catch (error) {
        displayError('Payment processing failed. Please try again.');
    } finally {
        loadingIndicator.style.display = 'none';
    }
}

Testing and Deployment Strategies

Comprehensive Testing Strategy

Test all payment scenarios before going live:

• Successful payments with different card types
• Failed payments (insufficient funds, expired cards)
• 3D Secure authentication flows
• Partial refunds and cancellations
• Subscription creation and management
• Webhook delivery and processing

Monitoring and Alerts

Set up monitoring for payment-related issues:

// PaymentMonitor.php
public function checkPaymentHealth()
{
    $failedPayments = Order::find()
        ->where(['status' => 'failed'])
        ->andWhere(['>', 'dateCreated', new \DateTime('-1 hour')])
        ->count();
    
    if ($failedPayments > 10) {
        $this->sendAlert('High payment failure rate detected');
    }
}

Choosing the Right Payment Gateway for Your Business

The best payment integration depends on your specific needs. We recommend Stripe for most businesses due to its reliability and feature set. However, businesses in regulated industries should consider Authorize.Net or NMI, while European companies might prefer Quickpay or Mollie.

For complex requirements like multi-gateway setups, subscription management, or high-risk merchant processing, working with experienced developers ensures proper implementation and ongoing maintenance.

Craft CMS provides the flexibility to build exactly the payment experience your business needs, from simple checkouts to complex multi-step payment flows. With proper planning and implementation, integrated payments can significantly improve your conversion rates and customer satisfaction.

Ready to implement integrated payments in your Craft CMS project? Start with a clear understanding of your payment requirements, choose the appropriate gateway, and focus on creating a smooth, secure checkout experience for your customers.