Configuring the Cardstream Gateway URL

From v1.0.64, the Cardstream client no longer hardcodes gateway URLs. Instead, it reads the base URL from the CARDSTREAM_GATEWAY_URL environment variable, giving you full control over which Cardstream environment your application targets.

Why this matters

Previous versions of CardstreamClient embedded the following URLs directly in source code:

Constant	Value
LIVE_DIRECT_URL	https://gateway.cardstream.com/direct/
TEST_DIRECT_URL	(test equivalent)
LIVE_HOSTED_URL	(live hosted endpoint)
TEST_HOSTED_URL	(test hosted endpoint)

Because there was no runtime override, switching between live and test environments — or pointing to a custom gateway — required a code change. CARDSTREAM_GATEWAY_URL removes this constraint.

Setup

1. Add the variable to your environment

Add CARDSTREAM_GATEWAY_URL to your .env file (or your hosting provider's secrets manager):

# .env

# Cardstream gateway base URL.
# Use the live endpoint for production; use the test endpoint for development/staging.
CARDSTREAM_GATEWAY_URL=https://gateway.cardstream.com/direct/

A reference entry is also available in .env.example.

2. Common values

Environment	URL
Live (Direct)	https://gateway.cardstream.com/direct/
Test (Direct)	(refer to your Cardstream merchant portal for the test endpoint)

Note: The CARDSTREAM_GATEWAY_URL value is used by CardstreamClient to construct both the Direct API and Hosted API endpoint paths. Ensure the base URL you supply is correct for the integration type you are using.

3. Verify

Once the variable is set, restart your application. CardstreamClient will read CARDSTREAM_GATEWAY_URL at initialisation time and use it for all subsequent requests to the Cardstream gateway.

Migration from v1.0.63 and earlier

If you are upgrading from a version prior to v1.0.64:

1. Add CARDSTREAM_GATEWAY_URL to every environment where Calmony Pay runs (development, staging, production).
2. Set the value to the appropriate Cardstream gateway base URL for that environment.
3. Deploy. No other code changes are required.

Failure to set the variable will cause CardstreamClient to be misconfigured at startup.