Breaking Type Fix: SDK Card Fields for paymentMethods.create()

Release: v1.0.73 · Severity: Breaking (compile-time types were misleading, runtime calls failed)

Background

A spec drift was discovered between the Calmony Pay TypeScript SDK and the POST /v1/payment_methods REST API. The SDK's CreatePaymentMethodParams type described the card object using a token field (a Cardstream hosted-page token), while the API has always required raw card fields: number, exp_month, exp_year, and cvc.

As a result, any developer who relied on the SDK's TypeScript types to construct a paymentMethods.create() call would receive a HTTP 400 validation error at runtime — despite the code appearing correct at the type level. The API schema rejected token entirely and expected the four card fields listed above.

Root Cause

The CreatePaymentMethodParams type in src/lib/calmony-pay/client.ts was defined as:

// INCORRECT — prior to v1.0.73
type CreatePaymentMethodParams = {
  type: 'card';
  card: {
    token: string; // ← Cardstream hosted-page token — not accepted by the API
  };
};

The REST API handler at src/app/api/v1/payment_methods/route.ts validates the request body using a schema that requires:

{
  "type": "card",
  "card": {
    "number": "string",
    "exp_month": "integer",
    "exp_year": "integer",
    "cvc": "string"
  }
}

The two were incompatible. The API schema was confirmed as the correct source of truth.

What Changed in v1.0.73

The CreatePaymentMethodParams type has been corrected to match the API contract:

// CORRECT — v1.0.73 onwards
type CreatePaymentMethodParams = {
  type: 'card';
  card: {
    number: string;
    exp_month: number;
    exp_year: number;
    cvc: string;
  };
};

No changes were made to the API route itself — POST /v1/payment_methods continues to behave exactly as before.

How to Update Your Code

If you are calling paymentMethods.create() using the SDK, update the card object as follows:

Before

const paymentMethod = await pay.paymentMethods.create({
  type: 'card',
  card: {
    token: 'cst_live_xxxxxxxxxxxxxx',
  },
});

After

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

Note: Raw card data must only be transmitted over HTTPS. Never log or persist number or cvc values.

Affected Files

File	Change
src/lib/calmony-pay/client.ts	CreatePaymentMethodParams.card type updated from { token } to { number, exp_month, exp_year, cvc }
src/app/api/v1/payment_methods/route.ts	No change — confirmed as source of truth

Identifying Affected Call Sites

Search your codebase for any usage of the old token pattern:

grep -r "card: { token" .
grep -r 'card: { token' .

Any matches must be updated to pass raw card fields as shown above.