LogixPaymentForm Component Documentation

Overview

LogixPaymentForm is a flexible, dynamic payment form component that supports multiple payment providers (Stripe and Shift4). The component automatically detects which payment provider to use based on the API response, making it easy to switch between payment gateways without code changes.

Features

• ✅ Multi-provider support (Stripe and Shift4)
• ✅ Dynamic provider detection from API
• ✅ Fully customizable styling
• ✅ Responsive design
• ✅ 3D Secure support (Shift4)
• ✅ Error handling with custom callbacks
• ✅ Production and development environment support

Installation

Import the component in your React application:

import LogixPaymentForm from './PaymentForm';

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | amount | number | ✅ Yes | - | Payment amount in the smallest currency unit (e.g., cents for USD) | | currency | string | ✅ Yes | - | ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP') | | baseUrl | string | ✅ Yes | - | Base URL of your backend API (e.g., 'https://api.example.com') | | subscriptionId | string | ✅ Yes | - | Unique subscription/payment identifier | | successPage | function | ✅ Yes | - | Callback function called on successful payment | | errorPage | function | ✅ Yes | - | Callback function called on payment error | | description | string | ✅ Yes | - | Payment description/reason | | color | string | ❌ No | '#007bff' | Button background color (hex or valid CSS color) | | formwidth | number | ❌ No | 400 | Form width in pixels | | formborderRadius | number | ❌ No | 20 | Border radius in pixels | | formbackgroundColor | string | ❌ No | '#fff' | Form background color | | inputpadding | number | ❌ No | 12 | Input field padding in pixels |

Usage Example

Basic Implementation

import React from 'react';
import LogixPaymentForm from './PaymentForm';

export default function PaymentPage() {
  const handleSuccess = (message) => {
    console.log('Payment successful:', message);
    // Redirect or show success message
    window.location.href = '/success';
  };

  const handleError = (error) => {
    console.error('Payment failed:', error);
    // Show error message to user
    alert(`Payment failed: ${error}`);
  };

  return (
    <div>
      <h1>Complete Your Payment</h1>
      <LogixPaymentForm
        amount={9999}
        currency="USD"
        baseUrl="https://api.example.com"
        subscriptionId="sub_12345"
        description="Premium Subscription"
        successPage={handleSuccess}
        errorPage={handleError}
      />
    </div>
  );
}

Custom Styling

<LogixPaymentForm
  amount={5000}
  currency="EUR"
  baseUrl="https://api.example.com"
  subscriptionId="sub_67890"
  description="Product Purchase"
  successPage={handleSuccess}
  errorPage={handleError}
  color="#FF6B6B"
  formwidth={500}
  formborderRadius={12}
  formbackgroundColor="#F8F9FA"
  inputpadding={16}
/>

API Requirements

Endpoint: GET /api/Subscription/public/{subscriptionId}

This endpoint must be accessible from the client and return the payment provider configuration.

Response Format:

{
  "publicKeys": "pk_live_xxxxx...",
  "type": "stripe",
  "isProd": true
}

Or for Shift4:

{
  "publicKeys": "sk_live_xxxxx...",
  "type": "shift4",
  "isProd": true
}

Response Fields:

• publicKeys (string, required): Public API key for the payment provider
• type (string, required): Payment provider type - "stripe" or "shift4"
• isProd (boolean, optional): Environment flag - true for production, false for development/sandbox

Endpoint: POST /api/Payment/{subscriptionId}

Called to initialize the payment. This endpoint logs the payment request.

Request Body:

{
  "currency": "USD",
  "amount": 9999,
  "cardId": "tok_xxxx...",
  "description": "Premium Subscription"
}

Endpoint: POST /api/Payment/charge/{subscriptionId}

Called to process the actual payment charge.

Request Body:

{
  "tokenId": "tok_xxxx...",
  "amount": 9999,
  "currency": "USD",
  "description": "Premium Subscription"
}

Response Format (Success):

{
  "message": "Payment processed successfully",
  "transactionId": "txn_12345"
}

Response Format (Failure):

{
  "message": "Card declined"
}

Supported Payment Providers

Stripe

The component automatically loads Stripe.js from https://js.stripe.com/v3/ when type: "stripe" is returned from the API.

Features:

• Card number, expiry, and CVC input fields
• PCI compliant
• Built-in validation

Test Card Numbers:

• Success: 4242 4242 4242 4242
• Decline: 4000 0000 0000 0002
• Requires authentication: 4000 0025 0000 3155

Shift4

The component automatically loads Shift4.js from either:

• Production: https://js.shift4.com/shift4.js
• Development: https://js.dev.shift4.com/shift4.js

When type: "shift4" is returned from the API.

Features:

• Auto-mounting component group
• 3D Secure verification
• PCI compliant

Callback Functions

successPage(message)

Called when the payment is successfully processed.

const handleSuccess = (message) => {
  console.log('Success message:', message);
  // Redirect to success page
  window.location.href = '/payment-success';
};

Parameters:

• message (string): Success message from the server

errorPage(error)

Called when an error occurs during payment processing or initialization.

const handleError = (error) => {
  console.error('Error:', error);
  // Show error to user
  alert(error);
};

Parameters:

• error (string): Error message describing what went wrong

Possible Errors:

• "Failed to fetch public key" - API endpoint not reachable
• "Public key is empty" - Invalid API response
• "Stripe failed to initialize." - Stripe.js failed to load
• "Shift4 failed to initialize." - Shift4.js failed to load
• "Card tokenization failed." - Card details invalid (Stripe)
• "3D Secure verification failed." - 3D Secure verification failed (Shift4)
• "Payment form is not ready yet." - User submitted before script loaded
• Custom error message from server

Component Behavior

Initialization Flow

1. Component mounts and fetches configuration from /api/Subscription/public/{subscriptionId}
2. Determines payment provider type from API response
3. Loads appropriate payment provider script (Stripe or Shift4)
4. Renders payment form UI based on provider type
5. Sets isReady state to true when provider is initialized

Payment Processing Flow

1. User fills in card details
2. User clicks "Buy now" button
3. Component creates token using selected provider:
   • Stripe: createPaymentMethod()
   • Shift4: createToken() → verifyThreeDSecure()
4. Component sends token to /api/Payment/charge/{subscriptionId}
5. On success: calls successPage() callback
6. On error: calls errorPage() callback

UI States

• Loading: Shows disabled "Buy now" button while initializing
• Ready: Form fully loaded and interactive
• Processing: Shows "Processing..." and disables button during payment
• Error: Error message shown via errorPage() callback

Styling Customization

Default Styles

// Container
display: flex
justify-content: center
width: 100%

// Form
display: grid
gap: 14px
width: 400px (customizable)
box-sizing: border-box

// Input Fields
padding: 12px (customizable)
border-radius: 20px (customizable)
border: 1px solid #ccc
background: #fff

// Button
background-color: #007bff (customizable)
color: white
border: none
border-radius: 20px (customizable)
padding: 14px (customizable)
font-weight: 600
cursor: pointer

CSS Classes

The component does not use CSS classes, but you can wrap it with CSS:

<style>
  .payment-container {
    max-width: 600px;
    margin: 0 auto;
    padding: 20px;
  }
</style>

<div className="payment-container">
  <LogixPaymentForm {...props} />
</div>

Error Handling Best Practices

const handleError = (error) => {
  // Log error for debugging
  console.error('Payment error:', error);

  // Show user-friendly message
  if (error.includes('Network')) {
    alert('Network error. Please check your connection and try again.');
  } else if (error.includes('tokenization')) {
    alert('Please check your card details and try again.');
  } else if (error.includes('3D Secure')) {
    alert('3D Secure verification failed. Please try another card.');
  } else {
    alert(`Payment failed: ${error}`);
  }

  // Optional: Log to error tracking service
  // trackError(error);
};

Environment Setup

Stripe Setup

1. Get your public key from Stripe Dashboard
2. Return it in the API response with type: "stripe"
3. Component will auto-load Stripe.js

Shift4 Setup

1. Get your public key from Shift4 Dashboard
2. Return it in the API response with type: "shift4" and isProd: true/false
3. Component will auto-load Shift4.js from production or development URL

Troubleshooting

Form Not Loading

Issue: Form shows blank or no UI appears

Solutions:

• Check that baseUrl is correct and accessible
• Verify API endpoint returns correct JSON structure
• Check browser console for errors
• Ensure CORS is enabled if API is on different domain

Payment Provider Script Fails to Load

Issue: Error like "Stripe failed to initialize" or "Shift4 failed to initialize"

Solutions:

• Check internet connection
• Verify public key is valid
• Check that payment provider service is not blocked
• Clear browser cache and try again

Form Freezes During Payment

Issue: Button stuck in "Processing..." state

Solutions:

• Check that /api/Payment/charge/{subscriptionId} endpoint exists
• Verify endpoint returns valid JSON response
• Check backend logs for errors
• Check network tab in browser DevTools

Card Details Not Validating

Issue: "Card tokenization failed" error

Solutions:

• Verify card format is correct (Stripe requires valid card numbers)
• Check that card is not expired
• Try a different card for testing
• Review payment provider test card numbers

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+
• Mobile browsers (iOS Safari, Chrome Mobile)

Security Considerations

✅ PCI DSS Compliant

• Component uses tokenization (never handles raw card data)
• Card data handled by payment provider (Stripe or Shift4)
• No card data sent to your backend

✅ HTTPS Required

• Component requires HTTPS in production
• Payment provider scripts only load over HTTPS

✅ CORS Configuration

• API endpoints should be CORS-enabled
• Public key endpoint must be accessible from client

✅ Rate Limiting

• Implement rate limiting on payment endpoints
• Prevent brute force attacks

Migration Guide

From Stripe-Only to Multi-Provider

If you previously had a Stripe-only component:

Before:

<PaymentForm
  // Props...
  type="stripe"
/>

After:

// Just update your API endpoint to return type
// No component changes needed!
<LogixPaymentForm
  // Same props, no type prop
/>

The component now automatically detects the provider from your API response.

Version History

| Version | Date | Changes | |---------|------|---------| | 1.0.0 | 2026-05-05 | Initial release with Stripe and Shift4 support |

Support & Issues

For issues or questions:

1. Check the Troubleshooting section above
2. Review browser console for error messages
3. Verify API endpoints are correctly configured
4. Check that payment provider keys are valid

License

Proprietary - Logix Payment System