How to Add Payment Gateway to Your Web App

 

The 30-Second Summary

 

Adding a payment gateway to your web app isn't just a technical task—it's a business decision that impacts user experience, conversion rates, and your bottom line. In this guide, I'll walk you through integrating payment processing that balances security, user experience, and development resources.

 

Choosing the Right Payment Gateway

 

Not all payment gateways are created equal. Your choice should align with your business model, target audience, and growth plans.

 

• Popular options and their sweet spots:
  • Stripe - Developer-friendly with extensive documentation and flexibility. Ideal for custom checkout experiences and subscription models.
  • PayPal - High consumer trust and wide adoption. Great for international audiences.
  • Square - Excellent for businesses with both online and physical presence.
  • Braintree - Owned by PayPal but with more customization options.
  • Adyen - Enterprise-grade solution with global payment method support.

 

Decision factors that actually matter:

 

• Transaction fees - Typically 2-3% + a fixed fee per transaction. These add up quickly at scale.
• Payment methods - Credit cards are standard, but consider digital wallets, ACH/bank transfers, and local payment methods for your target markets.
• Developer experience - Quality documentation and SDKs can save weeks of development time.
• Settlement period - How quickly funds reach your bank account (ranges from 1-7 business days).

 

Integration Approaches: The Three Paths

 

Depending on your requirements, you have three main integration approaches:

 

1. Hosted Payment Pages (Easiest)

 

What it is: The payment gateway handles the entire checkout process on their servers.

 

Implementation example with Stripe Checkout:

 

// Server-side code (Node.js with Express)
const stripe = require('stripe')('sk_test_YOUR_SECRET_KEY');
const express = require('express');
const app = express();

app.post('/create-checkout-session', async (req, res) => {
  const session = await stripe.checkout.sessions.create({
    payment_method_types: ['card'],
    line_items: [
      {
        price_data: {
          currency: 'usd',
          product_data: {
            name: 'Premium Subscription',
          },
          unit_amount: 2000, // $20.00
        },
        quantity: 1,
      },
    ],
    mode: 'payment',
    success_url: 'https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
    cancel_url: 'https://yoursite.com/cancel',
  });

  res.json({ id: session.id });
});

 

// Client-side code
document.getElementById('checkout-button').addEventListener('click', async () => {
  const response = await fetch('/create-checkout-session', {
    method: 'POST',
  });
  
  const session = await response.json();
  
  // Redirect to Stripe Checkout
  const stripe = Stripe('pk_test_YOUR_PUBLISHABLE_KEY');
  stripe.redirectToCheckout({ sessionId: session.id });
});

 

Pros:

 

• Minimizes PCI DSS compliance scope
• Faster implementation (days instead of weeks)
• Reduced security responsibility

 

Cons:

 

• Limited customization of the checkout experience
• Customer leaves your site during checkout
• Less control over the conversion funnel

 

2. Embedded Forms/Components (Balanced Approach)

 

What it is: Payment form elements are embedded in your site, but sensitive data is sent directly to the gateway.

 

Implementation example with Stripe Elements:

 

<!-- Client-side HTML -->
<form id="payment-form">
  <div id="card-element">
    <!-- Stripe Elements will insert the card input here -->
  </div>
  <div id="card-errors" role="alert"></div>
  <button type="submit">Pay Now</button>
</form>

 

// Client-side JavaScript
const stripe = Stripe('pk_test_YOUR_PUBLISHABLE_KEY');
const elements = stripe.elements();
const cardElement = elements.create('card');
cardElement.mount('#card-element');

const form = document.getElementById('payment-form');
form.addEventListener('submit', async (event) => {
  event.preventDefault();
  
  const {paymentMethod, error} = await stripe.createPaymentMethod({
    type: 'card',
    card: cardElement,
  });
  
  if (error) {
    // Show error to customer
    const errorElement = document.getElementById('card-errors');
    errorElement.textContent = error.message;
  } else {
    // Send paymentMethod.id to your server
    const response = await fetch('/process-payment', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        payment_method_id: paymentMethod.id,
        amount: 2000, // $20.00
      }),
    });
    
    const result = await response.json();
    handleServerResponse(result);
  }
});

function handleServerResponse(response) {
  if (response.error) {
    // Show error
  } else if (response.requires_action) {
    // Handle 3D Secure authentication if needed
    stripe.handleCardAction(response.payment_intent_client_secret)
      .then(handleStripeJsResult);
  } else {
    // Payment successful!
    window.location.href = '/success';
  }
}

 

// Server-side code (Node.js with Express)
app.post('/process-payment', async (req, res) => {
  const {payment_method_id, amount} = req.body;
  
  try {
    // Create a PaymentIntent with the payment method
    const paymentIntent = await stripe.paymentIntents.create({
      amount,
      currency: 'usd',
      payment_method: payment_method_id,
      confirmation_method: 'manual',
      confirm: true,
    });
    
    if (paymentIntent.status === 'requires_action') {
      // 3D Secure is required
      res.json({
        requires_action: true,
        payment_intent_client_secret: paymentIntent.client_secret
      });
    } else {
      // Payment successful
      res.json({success: true});
    }
  } catch (err) {
    res.json({error: err.message});
  }
});

 

Pros:

 

• Better user experience (checkout happens on your site)
• Moderate customization possibilities
• Still relatively simple PCI compliance

 

Cons:

 

• More complex implementation than hosted pages
• Requires front-end and back-end coordination

 

3. Direct API Integration (Most Control)

 

What it is: You build the entire payment flow and communicate directly with the payment gateway's API.

 

Implementation example with Stripe API:

 

// This approach requires a secure, PCI-compliant environment
// I'm providing a simplified example with Stripe.js to maintain security

// Client-side: Create a token instead of handling card data directly
const tokenizeCard = async (cardDetails) => {
  const stripe = Stripe('pk_test_YOUR_PUBLISHABLE_KEY');
  const {token, error} = await stripe.createToken('card', {
    number: cardDetails.number,
    exp_month: cardDetails.expMonth,
    exp_year: cardDetails.expYear,
    cvc: cardDetails.cvc
  });
  
  if (error) {
    throw new Error(error.message);
  }
  
  return token.id;
};

// Then send this token to your server
const processPayment = async (tokenId, amount) => {
  const response = await fetch('/api/process-direct-payment', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      token: tokenId,
      amount: amount
    })
  });
  
  return response.json();
};

 

// Server-side API endpoint
app.post('/api/process-direct-payment', async (req, res) => {
  const {token, amount} = req.body;
  
  try {
    const charge = await stripe.charges.create({
      amount,
      currency: 'usd',
      source: token,
      description: 'Custom payment flow charge'
    });
    
    // Store transaction details in your database
    await saveTransactionToDatabase({
      id: charge.id,
      amount: charge.amount,
      status: charge.status,
      customer: req.user.id // Assuming authenticated user
    });
    
    res.json({success: true, transaction: charge.id});
  } catch (error) {
    res.status(400).json({error: error.message});
  }
});

 

Pros:

 

• Complete control over the user experience
• Deeper integration with your business logic
• Can optimize conversion rate with custom flows

 

Cons:

 

• Highest development effort
• Full PCI DSS compliance may be required
• Increased security responsibility

 

Testing Your Integration

 

Test cards are your friends. Most payment gateways provide test card numbers that simulate different scenarios:

 

• Successful payments
• Failed authorizations
• 3D Secure challenges
• Card declines for various reasons

 

Example test cards for Stripe:

 

Successful payment: 4242 4242 4242 4242
Requires authentication: 4000 0027 6000 3184
Insufficient funds: 4000 0000 0000 9995

 

Implement webhook handling for asynchronous events:

 

// Webhook handler for Stripe events
app.post('/webhook', express.raw({type: 'application/json'}), async (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;
  
  try {
    // Verify the event came from Stripe
    event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      'whsec_YOUR_WEBHOOK_SECRET'
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }
  
  // Handle the event
  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      // Update order status in your database
      await updateOrderStatus(paymentIntent.metadata.order_id, 'paid');
      break;
    case 'payment_intent.payment_failed':
      const failedPayment = event.data.object;
      // Notify customer of failed payment
      await notifyCustomerOfFailure(failedPayment.metadata.customer_id);
      break;
    // Handle other event types
    default:
      console.log(`Unhandled event type ${event.type}`);
  }
  
  res.status(200).send({received: true});
});

 

Security Considerations (The Non-Negotiables)

 

Payment security isn't a feature—it's a foundation. Regardless of your integration approach:

 

• Always use HTTPS for all payment-related pages and API endpoints
• Implement proper authentication and authorization for payment processing endpoints
• Never log complete card details in your application logs
• Keep your API keys secure and use separate keys for production and testing

 

Error Handling and Recovery

 

Payment failures happen. Your integration should gracefully handle these scenarios:

 

// Client-side error handling example
try {
  const result = await processPayment(paymentDetails);
  if (result.success) {
    // Show success message and redirect
    showSuccessUI();
    redirectToOrderConfirmation(result.orderId);
  } else {
    // Payment was processed but declined
    handleDeclinedPayment(result.declineCode);
  }
} catch (error) {
  // Something went wrong with the API request
  if (error.isNetworkError) {
    // Connection issue - save payment intent for retry
    savePaymentIntentToLocalStorage();
    showRetryMessage("Connection issue. Your card wasn't charged.");
  } else {
    // Other API error
    logErrorToMonitoring(error);
    showGenericErrorMessage();
  }
}

// Function to handle specific decline reasons
function handleDeclinedPayment(declineCode) {
  switch(declineCode) {
    case 'insufficient_funds':
      showMessage("Your card has insufficient funds. Please try another payment method.");
      highlightPaymentMethodSelector();
      break;
    case 'expired_card':
      showMessage("This card has expired. Please update your card details.");
      focusOnCardExpiryField();
      break;
    default:
      showMessage("Your payment was declined. Please try another payment method.");
  }
}

 

Beyond Basic Integration: The Full Picture

 

A complete payment system is more than just collecting money. Consider these additional components:

 

• Order management - Track order status and connect payments to orders
• Subscription management - For recurring billing models
• Refund handling - Both full and partial refunds
• Dispute/chargeback management - Processes for when customers dispute charges
• Analytics - Track conversion rates and payment method performance

 

Example refund implementation:

 

// Server-side refund endpoint
app.post('/api/refunds', async (req, res) => {
  const {order_id, amount, reason} = req.body;
  
  // Retrieve the payment ID from your database
  const order = await db.orders.findOne({id: order_id});
  if (!order) {
    return res.status(404).json({error: 'Order not found'});
  }
  
  try {
    // Process refund through Stripe
    const refund = await stripe.refunds.create({
      payment_intent: order.payment_intent_id,
      amount: amount || undefined, // If undefined, refunds the full amount
      reason: reason || 'requested_by_customer'
    });
    
    // Update order status in your database
    await db.orders.update({
      id: order_id,
      status: amount ? 'partially_refunded' : 'refunded',
      refund_id: refund.id,
      refunded_amount: refund.amount
    });
    
    // Notify customer about the refund
    await sendRefundNotification(order.customer_email, {
      order_id,
      amount: refund.amount,
      reason
    });
    
    res.json({success: true, refund_id: refund.id});
  } catch (error) {
    res.status(400).json({error: error.message});
  }
});

 

Making the Business Case: Real-World Impact

 

Quantify the ROI of your payment integration:

 

• Every 0.1% improvement in payment success rate can mean thousands in additional revenue
• A streamlined checkout flow can reduce cart abandonment by 10-20%
• Supporting local payment methods can open new markets with 15-30% higher conversion rates

 

Final Thoughts: It's an Ongoing Process

 

Payment gateway integration isn't a one-and-done project. As your business grows, you'll need to:

 

• Optimize conversion rates with A/B testing
• Add payment methods based on customer demand
• Scale your infrastructure as transaction volume grows
• Stay current with payment security standards

 

Start with the simplest integration that meets your needs, then iterate based on customer feedback and business metrics. The best payment experience is one that customers barely notice because it works so smoothly.