Breaking Type Fix: SDK Card Fields Now Match the API

Version: v1.0.67
Affected method: paymentMethods.create()
Affected files: src/lib/calmony-pay/client.ts, src/app/api/v1/payment_methods/route.ts

Overview

In v1.0.67 we corrected a spec drift between the Calmony Pay SDK's TypeScript types and the REST API's actual validation schema. The CreatePaymentMethodParams type now accurately reflects what POST /v1/payment_methods accepts, so type errors are caught at compile time rather than producing 400 responses at runtime.

Background

The SDK's card type previously modelled a Cardstream hosted-page token:

// Old — incorrect
type CreatePaymentMethodParams = {
  type: 'card';
  card: {
    token: string; // ❌ Not accepted by the API
  };
};

The REST API at POST /v1/payment_methods has always required raw card fields and never accepted a token property. This meant the SDK's own types were actively misleading: passing the typed value to the API would silently compile but fail at the network boundary with a 400 Bad Request.

The Fix

The card shape in CreatePaymentMethodParams has been updated to match the API schema exactly:

// New — correct
type CreatePaymentMethodParams = {
  type: 'card';
  card: {
    number: string;     // Full PAN
    exp_month: number;  // 1–12
    exp_year: number;   // Four-digit year, e.g. 2027
    cvc: string;        // 3 or 4 digits
  };
};

How to update your integration

Replace any card: { token: '...' } argument with the full card-field object:

const paymentMethod = await calmonyPay.paymentMethods.create({
  type: 'card',
  card: {
    number: '4242424242424242',
    exp_month: 12,
    exp_year: 2027,
    cvc: '123',
  },
});

If your project uses TypeScript, the compiler will flag any remaining token usage after upgrading to v1.0.67.

PCI considerations

Passing raw card data means your integration is in the request path for cardholder data. Ensure your server-side code handles these fields in accordance with your PCI DSS obligations. If you prefer to keep raw card data off your servers, use Cardstream's hosted payment page and capture the resulting charge reference directly — do not attempt to pass the hosted-page token through paymentMethods.create().

API reference

See the Payment Methods API reference for the full POST /v1/payment_methods request and response schema.