All Docs
FeaturesCalmony PayUpdated March 15, 2026

Cardstream Gateway URL Configuration

Cardstream Gateway URL Configuration

As of v1.0.78, the Cardstream client respects the CARDSTREAM_GATEWAY_URL environment variable to determine the base URL used for all Direct and Hosted API calls. Previously, these URLs were hardcoded inside client.ts and could not be overridden without a code change.

Why this matters

  • Environment flexibility — You can point the client at a staging gateway, a mock server, or a custom proxy without touching application code.
  • Spec compliance — The Cardstream Payment Gateway Integration spec mandates CARDSTREAM_GATEWAY_URL as the canonical configuration point for the gateway base URL.
  • Auditability — All runtime configuration lives in the environment, not the codebase.

Configuration

Add CARDSTREAM_GATEWAY_URL to your environment. A minimal .env.example entry looks like:

# Base URL for the Cardstream payment gateway.
# Production:  https://gateway.cardstream.com/
# Sandbox/test: use the test gateway URL provided by Cardstream.
CARDSTREAM_GATEWAY_URL=https://gateway.cardstream.com/

Note: The client appends the appropriate path segment (direct/ or hosted/) to the base URL you provide. Ensure the value you set ends with a trailing slash, or verify against your Cardstream account documentation.

Behaviour

ScenarioURL used
CARDSTREAM_GATEWAY_URL setBase URL taken from the env var; paths appended by the client
CARDSTREAM_GATEWAY_URL not setClient will throw a configuration error at startup

Migration from v1.0.77 and earlier

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

  1. Add CARDSTREAM_GATEWAY_URL to every environment where Calmony Pay runs (local, staging, production).
  2. Copy the example entry from .env.example as a starting point.
  3. Confirm the value matches the gateway URL your Cardstream account was previously resolving to (default was https://gateway.cardstream.com/).
  4. Redeploy — no code changes are required beyond setting the variable.

Related