Cardstream Gateway URL Configuration

Calmony Pay connects to the Cardstream payment gateway for both Direct (server-to-server) and Hosted (redirect-based) payment flows. The base URL for the Cardstream gateway is configurable via the CARDSTREAM_GATEWAY_URL environment variable.

Why this matters

Hardcoding gateway URLs makes it impossible to:

• Point a staging or development environment at a Cardstream test endpoint without changing source code.
• Adapt to any future gateway URL changes without a full redeployment of application code.
• Comply with the Cardstream Payment Gateway Integration specification, which requires runtime configurability of the gateway base URL.

Environment variable

Variable	Required	Description
CARDSTREAM_GATEWAY_URL	Yes	Base URL for the Cardstream gateway. Used to construct both the Direct API and Hosted API endpoint paths.

Example .env entries

# Production (live gateway)
CARDSTREAM_GATEWAY_URL=https://gateway.cardstream.com/

# Staging / development (test gateway)
CARDSTREAM_GATEWAY_URL=https://test.cardstream.com/

Note: The value should be a base URL (with a trailing slash). The CardstreamClient appends the appropriate path segments (direct/, hosted/, etc.) when constructing request URLs.

How CardstreamClient uses this variable

Internally, CardstreamClient reads CARDSTREAM_GATEWAY_URL at initialisation time and derives the Direct and Hosted endpoint URLs from it:

const gatewayBase = process.env.CARDSTREAM_GATEWAY_URL;

// Direct API (server-to-server)
const directUrl = `${gatewayBase}direct/`;

// Hosted API (redirect-based)
const hostedUrl = `${gatewayBase}hosted/`;

This replaces the previous hardcoded constants and ensures all gateway traffic is routed through the configured URL without requiring code changes.

Migration

If you were relying on the previously hardcoded URLs:

1. Add CARDSTREAM_GATEWAY_URL to your .env file (and any CI/CD secret stores).
2. For production, set it to https://gateway.cardstream.com/.
3. For test/staging, set it to the appropriate Cardstream test gateway URL.
4. Redeploy the application.

No changes to your application code are required beyond setting the environment variable.