Configurable Cardstream Gateway URL

Available from v1.0.66

Calmony Pay v1.0.66 introduces the CARDSTREAM_GATEWAY_URL environment variable, giving you control over which Cardstream gateway endpoint the client connects to. This is primarily useful for sandbox and staging environments, and resolves a spec drift issue where the gateway base URL was previously hardcoded.

Background

Prior to this release, the Cardstream client contained four hardcoded URL constants covering the live and test direct/hosted endpoints. Changing the target gateway required modifying source code, which made sandbox testing and staged rollouts more difficult than necessary.

How it works

At startup the client calls an internal resolveGatewayBaseUrl() helper, which checks for CARDSTREAM_GATEWAY_URL in the environment. If the variable is not set, it falls back to https://gateway.cardstream.com/, preserving the existing default behaviour exactly.

The directUrl and hostedUrl properties used internally when making requests are derived from the resolved base URL by appending direct/ or hosted/ respectively. This means a single variable controls both endpoint paths.

Configuration

Using the environment variable

Add CARDSTREAM_GATEWAY_URL to your .env file (or your deployment environment):

# Sandbox / staging
CARDSTREAM_GATEWAY_URL=https://sandbox.cardstream.com

# Production (equivalent to omitting the variable)
CARDSTREAM_GATEWAY_URL=https://gateway.cardstream.com

Trailing slashes are normalised automatically — both https://sandbox.cardstream.com and https://sandbox.cardstream.com/ produce the same result.

Per-instance override (advanced)

The CardstreamClient constructor now accepts an optional gatewayUrl field. This is intended for test scenarios where you need to point individual client instances at a mock server without modifying environment variables:

const client = new CardstreamClient({
  merchantId: process.env.CARDSTREAM_MERCHANT_ID,
  sharedSecret: process.env.CARDSTREAM_SHARED_SECRET,
  gatewayUrl: "http://localhost:9000", // override for this instance only
});

console.log(client.gatewayUrl); // http://localhost:9000/

The new gatewayUrl accessor on the instance returns the resolved base URL, which is useful for assertions and diagnostics.

Behaviour summary

Scenario	Gateway base URL
CARDSTREAM_GATEWAY_URL not set	https://gateway.cardstream.com/
CARDSTREAM_GATEWAY_URL=https://sandbox.cardstream.com	https://sandbox.cardstream.com/
new CardstreamClient({ gatewayUrl: "https://mock.example.com" })	https://mock.example.com/

Compatibility

This change is fully backward-compatible. The CardstreamClient constructor signature is unchanged for existing call sites — the gatewayUrl field is optional. No existing API surface has been altered.