All Docs
FeaturesCalmony PayUpdated March 14, 2026

Cardstream Client Library — v1.0.2 Release

Cardstream Client Library — v1.0.2 Release

Published with v1.0.2

Calmony Pay now ships a fully typed TypeScript client for the Cardstream payment gateway. This client is the foundation of Calmony Pay's card-charging infrastructure and handles everything from authentication and request signing to test/live environment routing — so application code never has to.

What Was Built

A Unified Client for Two Integration Modes

Cardstream exposes two distinct integration patterns, and the new client supports both:

Direct API (server-to-server) Charge a card directly from your backend without any browser redirect. Suitable for server-side flows where you have already collected and tokenised card data.

Hosted API (redirect-based) Generate a redirect URL to Cardstream's hosted payment page. The cardholder completes payment on Cardstream's infrastructure, and the result is returned to your callback URL. Ideal for browser-based checkout where you want to minimise PCI scope.

Automatic Request Signing

Every request sent through the client is signed using a HMAC signature derived from your CARDSTREAM_SIGNATURE_KEY. This ensures that Cardstream can verify the authenticity and integrity of every API call. Signing is handled transparently — you never need to construct or attach signatures manually.

Test Mode Routing

The client inspects your API key at runtime. If the key begins with sk_test_, all requests are automatically routed to the Cardstream test environment. Switch to a live key and requests go to production — no conditional logic, no environment flags in your own code.

sk_test_...   →  Cardstream test environment
sk_live_...   →  Cardstream live environment

Configuration

The client requires two environment variables to be set before use:

# Your Cardstream merchant account identifier
CARDSTREAM_MERCHANT_ID=your_merchant_id

# Secret key used to sign outbound API requests
CARDSTREAM_SIGNATURE_KEY=your_signature_key

Both values are available from your Cardstream merchant portal.

What This Enables

With this client in place, Calmony Pay can now:

  • Process one-off card payments via the Direct API
  • Redirect customers to a hosted payment page via the Hosted API
  • Run end-to-end payment flows in the test environment without touching live funds
  • Cryptographically authenticate every request sent to Cardstream

This is the core building block on top of which invoice generation, recurring billing, and Stripe-compatible API endpoints will be layered in subsequent releases.