CardPointe Gateway Integration Complete

✅ What's Been Completed

1. CardPointe Adapter - app/services/payment_processors/fiserv_adapter.rb

2. Updated Payment View - app/views/app/quotes/payment.html.erb

3. Updated Quotes Controller - app/controllers/app/quotes_controller.rb

4. Database Migrations

5. Accounts Controller Fix - app/controllers/app/accounts_controller.rb

6. CardPointe Credentials - .kamal/secrets

7. Fiserv Validation Testing - ✅ COMPLETED

🚀 How It Works

Payment Flow with CardPointe HIT

Customer → Payment Page
           ↓
        [Frontend JavaScript]
           ↓ (Load CardPointe HIT iframe)
        https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html
           ↓ (Customer enters card data in iframe)
        CardPointe tokenizes card data
           ↓ (postMessage returns token + expiry)
        JavaScript captures token and expiry
           ↓ (Submit form)
        POST /order/:token/process_payment
           ↓
        PaymentProcessorFactory.for_order(@order)
           ↓
        FiservAdapter.authorize_with_token
           ↓
        1. Create customer profile ID (local)
        2. POST /cardconnect/rest/auth (CardPointe API)
        3. Parse expiry (MMYY/MMYYY/MMYYYY → month/year)
           ↓
        Save PaymentProfile + Order status
           ↓
        Send email notifications
           ↓
        Redirect to complete page

Key Differences from Original Plan

Original Plan (Commerce Hub) What We Actually Built (CardPointe)
Fiserv Commerce Hub CardPointe Gateway (Fiserv subsidiary)
Hosted Fields Hosted iFrame Tokenizer (HIT)
HMAC authentication Basic authentication
Payment session API Direct iframe tokenization
SessionID flow Token + expiry via postMessage
/ch/payments/v1/charges /cardconnect/rest/auth

🔐 PCI Compliance - SAQ A Achieved

CardPointe HIT Benefits

🧪 Testing Results

✅ Completed Tests

🚧 Pending Tests

📊 Database Schema

PaymentProfile

- processor              # 'fiserv' (for CardPointe)
- processor_customer_id  # Local customer ID (e.g., 'fiserv_490000000069_contact_3')
- processor_token_id     # CardPointe token (e.g., '9418594164541111')
- card_type              # Parsed from response
- last_four              # Last 4 digits
- expiration_month       # Parsed from expiry (1-12)
- expiration_year        # Parsed from expiry (full year, e.g., 2027)
- company_id             # NULLABLE - belongs to company
- contact_id             # NULLABLE - OR belongs to contact
- is_default             # Default payment method flag

PaymentTransaction

- processor                # 'fiserv'
- processor_transaction_id # CardPointe retref (e.g., '279971160962')
- transaction_type         # 'authorization', 'capture', 'refund'
- status                   # 'approved', 'declined'
- amount                   # Decimal amount
- response_code            # CardPointe respcode
- metadata (jsonb)         # Processor-specific data

🚨 Issues Encountered & Fixed

1. PaymentProfile Creation Error

2. Non-numeric Expiry Error

3. Expiration Validation Failed

4. Expiry Format Variations

5. Unknown Attribute Error

6. NOT NULL Constraint Violation

7. Account Creation Page 500 Error

📁 Files Changed/Created

Created:

Modified:

🎯 Next Steps

1. Production Approval (In Progress)

2. Implement Stored Credential Framework (Required for Production)

Per Visa/Mastercard mandate, we need to add these parameters to production requests:

# In FiservAdapter.authorize_with_token
payload = {
  # ... existing fields ...
  cof: "C",              # C = Customer-initiated, M = Merchant-initiated
  cofscheduled: "N"      # Y = Recurring, N = One-time
}

Action items:

3. Code Cleanup

4. Additional Testing

5. Documentation Updates

🔑 Production Environment Setup

Required Environment Variables

# CardPointe Production
CARDPOINTE_API_URL=https://fts.cardconnect.com  # Production URL (not UAT)
CARDPOINTE_MERCHANT_ID=<production_merchant_id>
CARDPOINTE_API_USERNAME=<production_username>
CARDPOINTE_API_PASSWORD=<production_password>

# Payment Processor Selection
DEFAULT_PAYMENT_PROCESSOR=fiserv

# Authorize.Net (keep as backup if needed)
AUTHORIZENET_API_LOGIN_ID=<your_api_login_id>
AUTHORIZENET_TRANSACTION_KEY=<your_transaction_key>
AUTHORIZENET_SIGNATURE_KEY=<your_signature_key>
AUTHORIZENET_PUBLIC_CLIENT_KEY=<your_public_client_key>

Production Iframe URL

Update in app/views/app/quotes/payment.html.erb:

// Change from UAT:
iframe.src = 'https://fts-uat.cardconnect.com/itoke/ajax-tokenizer.html'

// To Production:
iframe.src = 'https://fts.cardconnect.com/itoke/ajax-tokenizer.html'

🤝 Benefits Achieved

✅ PCI SAQ-A Compliance - Reduced from SAQ A-EP (175+ questions) ✅ Payment Security - Card data never touches our servers ✅ Processor Agnostic - Can switch between CardPointe and Authorize.Net ✅ Backwards Compatible - Existing Authorize.Net profiles still work ✅ Cost Savings - Lower processing fees with CardPointe ✅ Flexible Expiry Handling - Works with any expiry format from CardPointe ✅ Polymorphic Profiles - Supports both company and contact payments ✅ Validation Complete - Ready for production approval

📞 Support Resources

CardPointe Documentation:

Fiserv Support:

Test Cards (UAT):

Amount-Driven Response Codes (UAT):

✨ Success Metrics

Last Updated: 2025-10-06 Status: UAT Complete, Awaiting Production Credentials