Configurable Cardstream Gateway URL

As of v1.0.68, the Cardstream gateway base URL is configurable at runtime via the CARDSTREAM_GATEWAY_URL environment variable. This removes the previously hardcoded URL constants and makes it straightforward to route traffic to a sandbox, staging, or custom Cardstream endpoint without code changes.

Default behaviour

If CARDSTREAM_GATEWAY_URL is not set, the client continues to use https://gateway.cardstream.com/ as the base URL — identical to the behaviour before this change. No action is needed for live production deployments.

Setting a custom gateway URL

Add the variable to your environment (e.g. .env, a secrets manager, or your hosting platform's config):

# .env
CARDSTREAM_GATEWAY_URL=https://sandbox.cardstream.com

The client normalises a trailing slash automatically, so both of the following are equivalent:

CARDSTREAM_GATEWAY_URL=https://sandbox.cardstream.com
CARDSTREAM_GATEWAY_URL=https://sandbox.cardstream.com/

URL resolution summary

`CARDSTREAM_GATEWAY_URL` value	`directUrl`	`hostedUrl`
(not set)	`https://gateway.cardstream.com/direct/`	`https://gateway.cardstream.com/hosted/`
`https://sandbox.cardstream.com`	`https://sandbox.cardstream.com/direct/`	`https://sandbox.cardstream.com/hosted/`
`https://staging.example.com/pay`	`https://staging.example.com/pay/direct/`	`https://staging.example.com/pay/hosted/`

Per-instance override (advanced)

For cases where a single process needs to talk to multiple gateway endpoints simultaneously, the CardstreamClient constructor accepts an optional gatewayUrl field that overrides the environment variable for that specific instance:

import { CardstreamClient } from "@/lib/calmony-pay/cardstream/client";

// Uses CARDSTREAM_GATEWAY_URL env var (or default)
const liveClient = new CardstreamClient({ /* ...credentials */ });

// Overrides the base URL for this instance only
const sandboxClient = new CardstreamClient({
  // ...credentials
  gatewayUrl: "https://sandbox.cardstream.com",
});

You can read back the resolved base URL from any instance via the gatewayUrl accessor:

console.log(liveClient.gatewayUrl);
// → "https://gateway.cardstream.com/"

console.log(sandboxClient.gatewayUrl);
// → "https://sandbox.cardstream.com/"

Backward compatibility

The CardstreamClient constructor signature is fully backward-compatible. Existing instantiations that do not pass gatewayUrl continue to work without modification.