Fiserv CardPointe Environment Switching

Overview

The Fiserv CardPointe integration now supports switching between sandbox (UAT) and production environments using a single environment variable. This allows you to test in sandbox and then switch to production without changing multiple configuration values.

Changes Made

1. Environment Variable Structure

Old Structure (conflicting):

CARDPOINTE_API_URL=...
CARDPOINTE_MERCHANT_ID=...
CARDPOINTE_API_USERNAME=...
CARDPOINTE_API_PASSWORD=...

New Structure (environment-aware):

# Control which environment to use
FISERV_ENVIRONMENT="sandbox"  # or "production"

# Sandbox credentials
FISERV_SANDBOX_API_URL="https://fts-uat.cardconnect.com"
FISERV_SANDBOX_MERCHANT_ID="490000000069"
FISERV_SANDBOX_API_USERNAME="testing"
FISERV_SANDBOX_API_PASSWORD="testing123"

# Production credentials
FISERV_PRODUCTION_API_URL="https://fts.cardconnect.com"
FISERV_PRODUCTION_MERCHANT_ID="496501158885"
FISERV_PRODUCTION_API_USERNAME="quarryllc"
FISERV_PRODUCTION_API_PASSWORD="CmAC4h5J4R3%m9Iktw5clxAv"

2. Files Updated

`app/services/payment_processors/fiserv_adapter.rb`

Added 4 class-level helper methods that check FISERV_ENVIRONMENT:
- self.fiserv_api_url - Returns sandbox or production API URL
- self.fiserv_merchant_id - Returns sandbox or production merchant ID
- self.fiserv_api_username - Returns sandbox or production username
- self.fiserv_api_password - Returns sandbox or production password
Replaced all hardcoded ENV["CARDPOINTE_*"] references with helper method calls
All adapter methods now automatically use the correct environment

`.kamal/secrets`

Renamed all CARDPOINTE_* variables to FISERV_SANDBOX_* and FISERV_PRODUCTION_*
Added FISERV_ENVIRONMENT variable (defaults to "sandbox" for safety)

`config/deploy.yml`

Updated secret environment variable list to include new variable names
Added all sandbox and production variables
Added FISERV_ENVIRONMENT control variable

`app/controllers/fiserv_validation_controller.rb`

Updated UAT check to use PaymentProcessors::FiservAdapter.fiserv_api_url

`lib/tasks_scripts/fiserv_validation_test.rb`

Updated error message to reference new environment variable names

Usage

Testing in Sandbox (Current State)

The system is currently configured to use sandbox by default:

# In .kamal/secrets
export FISERV_ENVIRONMENT="sandbox"

All transactions will use the UAT environment with test credentials.

Switching to Production

When ready to go live:

Update .kamal/secrets:
```
export FISERV_ENVIRONMENT="production"
```

Deploy:

source .kamal/secrets && \
export KAMAL_REGISTRY_PASSWORD && \
export RAILS_MASTER_KEY && \
export POSTGRES_PASSWORD && \
kamal deploy

All transactions will now use production credentials automatically.

Switching Back to Sandbox

To test new features or troubleshoot issues:

Update .kamal/secrets:
```
export FISERV_ENVIRONMENT="sandbox"
```

Deploy:

source .kamal/secrets && \
export KAMAL_REGISTRY_PASSWORD && \
export RAILS_MASTER_KEY && \
export POSTGRES_PASSWORD && \
kamal deploy

Testing Before Production

Before switching to production, verify sandbox still works:

Ensure .kamal/secrets has FISERV_ENVIRONMENT="sandbox"
Load the secrets:
```
source .kamal/secrets
```

Test the validation page:

Visit: https://admin.quarryrents.com/fiserv-validation

Run a few test transactions:
- Card Not Present: $22.75
- CIT Token Storage: $55.25
- MIT Token Storage: $40.25
- MIT Recurring: $26.50
Verify all tests complete successfully

Security Notes

Default is Sandbox: The system defaults to sandbox if FISERV_ENVIRONMENT is not set or has an invalid value
Single Point of Control: Only one variable (FISERV_ENVIRONMENT) needs to be changed to switch environments
No Code Changes: Switching environments requires no code changes, only configuration
Kamal Secrets: All credentials are stored in .kamal/secrets and deployed as environment variables

Validation Page Access

The Fiserv validation page (/fiserv-validation) is only accessible when:

Running in development environment, OR
The API URL contains "uat" (sandbox environment)

This prevents accidental production testing and ensures the validation page is only used in appropriate environments.

Production Credentials

Production credentials are already configured in .kamal/secrets:

API URL: https://fts.cardconnect.com
Merchant ID: 496501158885
Username: quarryllc
Password: CmAC4h5J4R3%m9Iktw5clxAv

Troubleshooting

Check Current Environment

# In production server via Kamal
kamal app exec -i "bin/rails runner 'puts \"Environment: #{ENV[\"FISERV_ENVIRONMENT\"]}\"; puts \"API URL: #{PaymentProcessors::FiservAdapter.fiserv_api_url}\"; puts \"Merchant ID: #{PaymentProcessors::FiservAdapter.fiserv_merchant_id}\"'"

Verify Environment Variables

# Check what's loaded in .kamal/secrets
source .kamal/secrets
echo "Environment: $FISERV_ENVIRONMENT"
echo "Sandbox URL: $FISERV_SANDBOX_API_URL"
echo "Production URL: $FISERV_PRODUCTION_API_URL"

Test Adapter Methods

bin/rails runner "puts PaymentProcessors::FiservAdapter.fiserv_api_url"

Future Enhancements

Potential future improvements:

Admin UI toggle to switch environments without redeployment
Environment indicator in the admin interface
Automated testing across both environments
Transaction mirroring for validation