CardPointe Gateway - Production Ready

Date: October 9, 2025 Status: ✅ UAT Validation Complete - Awaiting Production Credentials

🎉 Executive Summary

All Fiserv CardPointe validation requirements have been completed successfully. The integration is production-ready and awaiting production credentials from Fiserv.

What's Ready

✅ All 10 validation retrefs generated and submitted ✅ Stored Credential Framework fully implemented (COF/cofscheduled) ✅ All 4 Fiserv compliance requirements met (postal, cvv2, ecomind, tokenization) ✅ PCI SAQ-A compliant (card data never touches our servers) ✅ Commerce Hub code removed (clean CardPointe-only implementation) ✅ UAT testing scripts created for future regression testing

📋 Validation Test Results

All 10 Required Retrefs Generated

Section 1: Card Not Present (4 retrefs)

Test Scenario	Retref	Status
Visa - $9.32	`282494749400`	✅ Approved
Visa - $1,100.35	`282244049402`	✅ Declined
American Express - $9.32	`282496749403`	✅ Approved
American Express - $1,100.35	`282245049404`	✅ Declined

Validates: postal, cvv2, ecomind, tokenization

Section 2: Customer Initiated Transactions (3 retrefs)

Test Scenario	Retref	Status
Token storage w/ transaction ($55.25)	`282588750465`	✅ Success
Token storage, no transaction ($0)	`282590750467`	✅ Success
Stored token usage, CIT ($100.25)	`282591750468`	✅ Success

Validates: Customer-initiated stored credential framework (cof='C')

Section 3: Merchant Initiated Transactions (3 retrefs)

Test Scenario	Retref	Status
Token storage w/ transaction, for future recurring ($40.25)	`282566150686`	✅ Success
Stored token usage, for recurring transaction ($26.50)	`282354050700`	✅ Success
Stored token usage, for MIT ($150.00)	`282609750702`	✅ Success

Validates: Merchant-initiated stored credential framework (cof='M', cofscheduled='Y/N')

🔧 Technical Implementation

Architecture Overview

Production Flow:
┌─────────────────────────────────────────────────────────────┐
│ 1. Customer enters card into CardPointe HIT iframe         │
│    (https://fts.cardconnect.com/itoke/ajax-tokenizer.html) │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. CardPointe tokenizes card (SAQ-A compliant)             │
│    Returns token + expiry via postMessage                   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Our backend receives token (never sees raw card)        │
│    POST /cardconnect/rest/auth                              │
│    - account: token                                         │
│    - ecomind: "E" (e-commerce)                             │
│    - postal: ZIP (for AVS/fraud prevention)                │
│    - cvv2: included in token                               │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. CardPointe processes authorization                       │
│    Returns retref + payment token for future use            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. We save PaymentProfile + PaymentTransaction             │
│    Order marked as "pending"                                │
└─────────────────────────────────────────────────────────────┘

Files Modified/Created

Core Adapter (Cleaned)

app/services/payment_processors/fiserv_adapter.rb
- ✅ All Commerce Hub code removed
- ✅ CardPointe Gateway only (369 lines, down from 656)
- ✅ Stored Credential Framework support (cof, cofscheduled)
- ✅ Methods: authorize_with_token, capture_authorization, void_authorization, refund_transaction

UAT Testing Scripts (New)

lib/scripts/fiserv_validation_test.rb - Card Not Present tests
lib/scripts/fiserv_cit_validation_test.rb - Customer-Initiated tests
lib/scripts/fiserv_mit_validation_test.rb - Merchant-Initiated tests

To re-run: source .kamal/secrets && bin/rails runner lib/scripts/fiserv_validation_test.rb

Frontend Integration

app/views/app/quotes/payment.html.erb
- CardPointe HIT iframe (line 194)
- Origin validation (line 212)
- Token capture via postMessage
- Billing postal code field

Controller

app/controllers/app/quotes_controller.rb
- Routes to FiservAdapter for CardPointe payments
- Parses expiry from HIT iframe
- Saves PaymentProfile with token

🚀 Production Deployment Checklist

Step 1: Receive Production Credentials from Fiserv

Expected from Ryan McDonnell (integrationdelivery@fiserv.com):

[ ] Production Merchant ID (MID)
[ ] Production API Username
[ ] Production API Password
[ ] Production approval confirmation

Step 2: Update Environment Variables

File: .kamal/secrets

# Change from UAT:
export CARDPOINTE_API_URL="https://fts-uat.cardconnect.com"
export CARDPOINTE_MERCHANT_ID="490000000069"
export CARDPOINTE_API_USERNAME="testing"
export CARDPOINTE_API_PASSWORD="testing123"

# To Production:
export CARDPOINTE_API_URL="https://fts.cardconnect.com"
export CARDPOINTE_MERCHANT_ID="<PRODUCTION_MID_FROM_FISERV>"
export CARDPOINTE_API_USERNAME="<PRODUCTION_USERNAME>"
export CARDPOINTE_API_PASSWORD="<PRODUCTION_PASSWORD>"

Step 3: Update Frontend Iframe URL

File: app/views/app/quotes/payment.html.erb

Line 194 - Change iframe source:

// 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'

Line 212 - Change origin validation:

// FROM (UAT):
if (!/fts-uat\.cardconnect\.com$/.test(new URL(event.origin).host)) {

// TO (Production):
if (!/fts\.cardconnect\.com$/.test(new URL(event.origin).host)) {

Step 4: Deploy to Production

source .env && \
export KAMAL_REGISTRY_PASSWORD && \
export RAILS_MASTER_KEY && \
export POSTGRES_PASSWORD && \
kamal deploy

Step 5: Production Smoke Tests

Test a real transaction in production:

Create a test order with a small amount (e.g., $1.00)
Use a real card (or test card if Fiserv provides production test cards)
Complete checkout flow
Verify:
- [ ] Authorization successful (respstat: "A")
- [ ] Retref returned and saved
- [ ] PaymentProfile created correctly
- [ ] Order status updated to "pending"
- [ ] Email notifications sent
Test capture flow when order is delivered
Test void/refund flows if needed

🔐 Security & Compliance

PCI DSS Compliance

✅ SAQ-A Level (simplest - only 22 questions)
✅ Zero card data on our servers
✅ CardPointe HIT handles all sensitive data
✅ Tokenization before any backend processing

Stored Credential Framework Compliance

Per Visa/Mastercard mandate (effective October 2022):

Customer-Initiated Transactions (CIT):

Customer is present (e-commerce, phone, in-person)
Uses cof: "C" parameter
Initial transaction establishes token

Merchant-Initiated Transactions (MIT):

Customer NOT present (recurring, autopay)
Uses cof: "M" parameter
Uses cofscheduled: "Y" for recurring, "N" for one-time

Implementation in adapter:

# app/services/payment_processors/fiserv_adapter.rb
def authorize_with_card_data_uat_only(
  cof: nil,           # "C" or "M"
  cofscheduled: nil,  # "Y" or "N"
  # ... other params
)
  payload[:cof] = cof if cof.present?
  payload[:cofscheduled] = cofscheduled if cofscheduled.present?
end

📊 Database Schema

PaymentProfile

- processor              # 'fiserv' (for CardPointe)
- processor_customer_id  # Local ID: 'cardpointe_<MID>_<type>_<id>'
- processor_token_id     # CardPointe token (e.g., '9418594164541111')
- card_type              # Visa, Mastercard, Amex, etc.
- last_four              # Last 4 digits of card
- expiration_month       # 1-12
- expiration_year        # Full year (e.g., 2027)
- company_id             # NULLABLE - polymorphic
- contact_id             # NULLABLE - polymorphic
- is_default             # Boolean

PaymentTransaction

- processor                # 'fiserv'
- processor_transaction_id # CardPointe retref
- transaction_type         # 'authorization', 'capture', 'refund', 'void'
- status                   # 'approved', 'declined', 'pending'
- amount                   # Decimal
- response_code            # CardPointe respcode
- response_text            # Human-readable message
- metadata (jsonb)         # Extra processor data

🧪 Testing in Production

Test Cards (if provided by Fiserv)

Confirm with Fiserv if production test cards are available. In UAT:

Visa: 4111111111111111
Amex: 371449635398431 (CVV: 4 digits)

Amount-Driven Responses (UAT only)

These work in UAT but NOT production:

$9.32 → Approval
$1,100.35 → "Do not honor" decline

In production, use real transactions or Fiserv-provided test cards.

🐛 Troubleshooting

Common Issues

401 Unauthorized

Cause: Wrong credentials Fix: Verify CARDPOINTE_API_USERNAME and CARDPOINTE_API_PASSWORD in .kamal/secrets

Token not received from iframe

Cause: Wrong iframe URL or origin mismatch Fix: Check iframe URL matches environment (UAT vs Production)

"Payment declined: Non-numeric expiry"

Cause: Expiry not passed from frontend Fix: Verify cardpointe_expiry hidden field is populated

"Invalid merchant"

Cause: Wrong merchant ID Fix: Verify CARDPOINTE_MERCHANT_ID matches Fiserv-provided MID

📞 Support Contacts

Fiserv Integration Team

Email: integrationdelivery@fiserv.com
Contact: Ryan McDonnell, Sr. Project Manager
Phone: 412.317.6456

CardPointe Documentation

Developer Portal: https://developer.cardpointe.com/
API Reference: https://developer.cardpointe.com/cardconnect-api
HIT Guide: https://developer.cardpointe.com/hosted-iframe-tokenizer

✅ Production Readiness Checklist

Pre-Deployment

[x] All validation tests passed
[x] All 10 retrefs submitted to Fiserv
[ ] Production credentials received from Fiserv
[ ] .kamal/secrets updated with production credentials
[ ] payment.html.erb iframe URL updated
[ ] payment.html.erb origin check updated

Post-Deployment

[ ] Smoke test with real transaction
[ ] Test authorization flow
[ ] Test capture flow (when order delivered)
[ ] Test void flow
[ ] Test refund flow
[ ] Verify email notifications work
[ ] Monitor first week of production transactions

Optional

[ ] Set up transaction monitoring/alerts
[ ] Document internal processes for handling declines
[ ] Train support staff on CardPointe-specific issues
[ ] Update customer-facing documentation if needed

🎯 Next Actions

Wait for Fiserv production approval (in progress)
Receive production credentials from Ryan McDonnell
Update environment variables in .kamal/secrets
Update iframe URLs in payment.html.erb
Deploy to production via Kamal
Run smoke tests with small real transactions
Monitor production for first few days

📝 Change Log

October 9, 2025

✅ All validation tests completed (10/10 retrefs)
✅ Stored Credential Framework implemented
✅ Commerce Hub code removed
✅ UAT testing scripts created
✅ Documentation updated for production deployment

October 8, 2025

✅ Added postal code field (Fiserv compliance requirement)
✅ Verified cvv2, ecomind, tokenization requirements

October 6, 2025

✅ CardPointe HIT integration completed
✅ End-to-end UAT testing successful
✅ Polymorphic PaymentProfile fixed

Status: Ready for production deployment pending Fiserv credentials Last Updated: October 9, 2025